DecisioQ Decision API Quick Start

What is the Easiest Way to Use DecisioQ?

DecisioQ turns the business facts supplied by an application into a consistent, ranked, explainable recommendation. Use it programmatically from your application: these are API calls performed automatically by software, and end users usually see only the resulting recommendation.

Authenticate
  ↓
Discover available decisions (or use a cached decisionId)
  ↓
Select the appropriate decision
  ↓
Submit business data
  ↓
Receive recommendation
  ↓
Present the result or continue the business workflow

The Decision Catalog is normally queried during development, application startup, or configuration—not before every decision. Once a decision is selected, production applications commonly cache or configure its decisionId and call POST /api/v1/decide directly.

Make Your First Decision Call in Five Minutes

Goal: authenticate, discover one business decision, and execute it. Run these commands from trusted server-side code or a development terminal; never expose the Client Secret in browser JavaScript.

Create an API Consumer: sign in to the VINquery portal, open My API Consumers, create a DecisioQ consumer, and securely save its one-time Client Secret.
Obtain a JWT: call the Identity service with audience vinquery:api:decisioq.
Discover a decision: retrieve the catalog, select AUTO-AUCT-044, and load its definition.
Execute: submit its decisionId and business facts to POST /api/v1/decide.
Continue your workflow: read decisionResult and explanation, then persist the complete decisionReceipt with the business transaction.

1. Obtain and export the JWT

curl -X POST "https://identity.vinquery.com/connect/token" \
  -H "Content-Type: application/json" \
  -d '{"clientId":"YOUR_CLIENT_ID","clientSecret":"YOUR_CLIENT_SECRET","audience":"vinquery:api:decisioq"}'

# Copy jwtToken from the response, then:
export DECISIOQ_TOKEN="paste-jwtToken-here"

2. Discover and inspect the decision

curl "https://dks.vinquery.com/decisioncatalog" \
  -H "Authorization: Bearer $DECISIOQ_TOKEN"

curl "https://dks.vinquery.com/decisioncatalog/decisions/AUTO-AUCT-044" \
  -H "Authorization: Bearer $DECISIOQ_TOKEN"

Production tip: catalog calls are normally made during development, startup, configuration, or administration. Store the selected decisionId; do not browse the catalog before every business event.

3. Submit the business data

POST https://dde.vinquery.com/api/v1/decide

curl -X POST "https://dde.vinquery.com/api/v1/decide" \
  -H "Authorization: Bearer $DECISIOQ_TOKEN" \
  -H "Content-Type: application/json" \
  --data-binary @decision-request.json

Save the following payload as decision-request.json:

{
  "decisionId": "AUTO-AUCT-044",
  "businessData": {
    "auctionLots": [
      {
        "optionId": "LOT-044-01",
        "name": "Purchase Option 1",
        "financial": { "expectedProfitMargin": 55000 },
        "risk": { "riskExposure": 35 },
        "compliance": { "and": { "risk": { "titleConfidence": 88, "repairUncertainty": 83, "managementPriority": 29 } } }
      },
      {
        "optionId": "LOT-044-02",
        "name": "Purchase Option 2",
        "financial": { "expectedProfitMargin": 90000 },
        "risk": { "riskExposure": 42 },
        "compliance": { "and": { "risk": { "titleConfidence": 92, "repairUncertainty": 45, "managementPriority": 50 } } }
      }
    ]
  },
  "requestContext": { "correlationId": "quick-start-001" }
}

{
  "service": "decisioq",
  "operation": "Decide",
  "success": true,
  "requestContext": {
    "correlationId": "quick-start-001",
    "decision": { "id": "AUTO-AUCT-044", "name": "Approve High-Risk Purchase", "catalogVersion": "13.9.3" }
  },
  "configurationUsed": {
    "weightStrategy": { "value": "Expert", "source": "DecisionRecommendedConfiguration" },
    "rankingAlgorithm": { "value": "TOPSIS", "source": "DecisionRecommendedConfiguration" },
    "sensitivity": { "value": false, "source": "PlatformDefault" }
  },
  "decisionReceipt": {
    "schemaVersion": "1.0",
    "executionId": "89df1c15a1b948e8a6e684b367f25610",
    "correlationId": "quick-start-001",
    "versions": { "decisionId": "AUTO-AUCT-044", "catalogVersion": "13.9.3", "engineVersion": "7.6.3" },
    "executionDurationMs": 4,
    "integrityAlgorithm": "SHA-256",
    "integrityHash": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
  },
  "decisionResult": {
    "winner": "LOT-044-02",
    "ranking": [
      { "optionId": "LOT-044-02", "score": 0.84 },
      { "optionId": "LOT-044-01", "score": 0.67 }
    ]
  },
  "explanation": {
    "summary": "Purchase Option 2 provides the strongest overall fit.",
    "whyRecommended": "It provides the strongest balance of expected margin, title confidence, and manageable uncertainty.",
    "sensitivitySummary": "Sensitivity analysis was not requested.",
    "scenarioSummary": "The catalog default scenario was used."
  }
}

Audit and replay: This shortened receipt omits its populated input, criteria, rule, exclusion, ranking, warning, and validation arrays for readability. Production clients should persist the complete object unchanged. Use executionId for one engine run and correlationId for the surrounding workflow.

Decision Discovery vs. Decision Execution

Discovery: occasional

Used during development, application startup, configuration, and administrative tooling.

GET /decisioncatalog
GET /decisioncatalog/decisions/{decisionId}

Execution: continuous

Used for each production business event after the application already knows its configured decision.

POST /api/v1/decide

Common misconception: end users do not normally browse the Decision Catalog. The client application performs these API calls and presents the resulting recommendation inside its business workflow.

Required vs. Optional

Required for most integrations

JWT authentication
A configured or catalog-discovered decisionId
Decision-specific businessData
POST /api/v1/decide

Optional advanced capabilities

Decision Profiles and scenarios
Recommended, AHP-assisted, or client-provided criterion weighting
Independent TOPSIS or WSM option ranking
Constraints and normalization overrides
Scenario and Sensitivity Analysis

Start with the recommended catalog defaults. Add advanced configuration only for a verified business requirement.

Typical Production Workflow

Application startup

Authenticate
  ↓
Load or validate supported decisions
  ↓
Cache decision identifiers
  ↓
Application ready

Normal operation

Business event
  ↓
Collect business data
  ↓
POST /api/v1/decide
  ↓
Receive recommendation
  ↓
Store requestId and continue business workflow
  ↓
When the result is known, POST /api/v1/decision-outcomes

Close the loop when practical. Outcome reporting is optional for execution, but it is how an integration measures acceptance, overrides, and realized business value. Use the successful decision response's requestId as originalDecisionRequestId. See Decision Outcome Feedback.

What DecisioQ Handles Automatically

Most applications can omit weighting and ranking overrides. The Decision Knowledge Service supplies recommended criterion priorities and a ranking method. Use AHP only when stakeholders provide relative judgments; provide manual weights only when established percentages exist.

This example uses Decision Defaults. You can provide custom weights or derive weights from your business priorities later.

Start with decisionId and businessData. Customize the methodology only when a verified business requirement calls for it.

Decision Profiles AHP & Weight Discovery TOPSIS WSM Scenarios, Sensitivity, Constraints, and Explainability

Use the Data Preparation Guide

Every published decision has a generated Data Preparation Guide. It combines Decision Catalog business meaning, units, and direction with Integration Platform guidance for typical source fields, illustrative preparation, validation, assumptions, and example prepared inputs.

Open the Interactive Playground or Business Decision Studio, select a decision, and review its guide before replacing sample values with your operational data.

7Next steps and advanced topics

After the first successful integration, continue to the Integration Guide and Decision Catalog.

Integration Guide Decision Catalog Business Decision Studio API Guide AHP & Weight Discovery Ranking Algorithms

DecisioQ Quick Start