Developer Center | DecisioQ

Recommended Integration Path

Request a JWT token from identity.vinquery.com with the required audience.
Load the secured Knowledge Catalog to discover sectors, categories, decisions, profiles, scenarios, criteria, validation rules, and hard constraints.
Review Decision Concepts to understand profiles, scenarios, criteria, constraints, sensitivity analysis, and explanations.
Build a Prepared Decision Input from business data.
Preview or validate the request before execution.
Execute the decision and display the Decision Result, eligible/excluded option outcomes, and explanation.

Public Service Hosts

Production integrations use three public service hosts. Client applications request a secure session token from the Identity service, read catalog metadata from the Knowledge service, and submit validated decision requests to the Decision Execution service.

Identity service:           https://identity.vinquery.com
Knowledge Catalog service:  https://dks.vinquery.com
Decision Execution service: https://dde.vinquery.com

End-to-End Flow

A typical integration starts with catalog discovery, not hard-coded fields. The selected decision definition tells the client which criteria, profiles, scenarios, validation rules, hard constraints, and option fields are required before validation and execution.

Authenticate once and store the bearer token securely on the server side.
Load sectors and categories from the catalog.
Load a decision definition such as AUTO-AUCT-008.
Render the criterion collection and collect business data for each option.
Validate the prepared decision input before execution.
Execute the decision and show the recommendation, ranked options, excluded option outcomes, explanation, warnings, and correlation identifier.

Authentication

Client applications request a bearer token from the Identity service and send it to Knowledge Catalog and Decision Execution calls using the Authorization header. The token request includes the intended audience for the API being called.

POST https://identity.vinquery.com/connect/token
Content-Type: application/json

{
  "clientId": "{clientId}",
  "clientSecret": "{clientSecret}",
  "audience": "vinquery:api:decisioq"
}

The API Consumer must be enabled, allowed to request the DecisioQ audience, and linked to a DecisioQ account so the Decision API can perform usage accounting.

Authorization: Bearer {jwtToken}

Catalog Discovery

The catalog lets client applications discover automotive sectors, categories, decisions, profiles, scenarios, criterion metadata, validation rules, and hard constraints without hard-coding decision inputs. Dropdowns should display business names while retaining stable identifiers internally.

GET https://dks.vinquery.com/decisioncatalog
GET https://dks.vinquery.com/decisioncatalog/decisions/AUTO-AUCT-008

Decision dropdowns should show Decision Name only. The selected decisionId should still be visible in a developer-friendly location such as an overview or diagnostics panel.

Using Profiles and Scenarios

Profiles and Scenarios are selected after a decision is chosen. They belong to the decision definition returned by the Knowledge Catalog, so clients should discover them from decision detail metadata and should not hard-code values that are not available for the selected decision.

Business Data
    |
    v
Decision
    |
    +----------------+
    v                v
Profile          Scenario
(how)            (assumptions)
    |                |
    +--------+-------+
             v
       Decision Engine
             v
       Decision Result

Concept	What it controls	What it does not mean	Examples for AUTO-AUCT-006
Profile	How the decision is evaluated: criterion weights, scoring priorities, risk tolerance, and ranking preferences.	It is not different business data.	`balanced`, `cost_focused`, `quality_focused`, `risk_averse`.
Scenario	The operating assumptions under which the same business data is evaluated. A scenario may be metadata-only or may contain computational adjustments.	It does not replace incoming business data.	`standard`, `limited_budget`, `high_demand`, `risk_control`.

The example below uses the real Auto Auctions decision AUTO-AUCT-006, Select Auction House. The candidate auction houses remain identical; only profileId or scenarioId changes.

{
  "decisionId": "AUTO-AUCT-006",
  "profileId": "balanced",
  "scenarioId": "standard",
  "requestContext": { "correlationId": "auction-house-demo-001" },
  "options": [
    {
      "optionId": "premium-metro",
      "name": "Premium Metro Auction",
      "values": {
        "vehicle_availability_score": 95,
        "buyer_fee_level": 1800,
        "average_vehicle_quality": 99,
        "distance_to_facility": 70000,
        "auction_reputation_score": 98,
        "title_processing_speed": 94
      }
    },
    {
      "optionId": "nearby-budget",
      "name": "Nearby Budget Auction",
      "values": {
        "vehicle_availability_score": 65,
        "buyer_fee_level": 850,
        "average_vehicle_quality": 60,
        "distance_to_facility": 8000,
        "auction_reputation_score": 81,
        "title_processing_speed": 75
      }
    },
    {
      "optionId": "regional-low-fee",
      "name": "Regional Low-Fee Auction",
      "values": {
        "vehicle_availability_score": 70,
        "buyer_fee_level": 700,
        "average_vehicle_quality": 70,
        "distance_to_facility": 140000,
        "auction_reputation_score": 82,
        "title_processing_speed": 70
      }
    }
  ]
}

Profile comparison

Profile	Example top score	Outcome	Why
Balanced	0.650	Nearby Budget Auction	Balanced weighting still rewards low fees and very short distance enough to offset lower quality.
Cost Focused	0.755	Nearby Budget Auction	Cost and distance weights increase, so the nearby lower-fee option becomes more clearly preferred.
Quality Focused	0.564	Premium Metro Auction	Quality, availability, and reputation matter more, so the higher-fee premium auction can overtake the cheaper nearby option.
Risk Averse	0.649	Nearby Budget Auction	Risk controls add emphasis to title speed and reputation, but the nearby option remains strong enough under this sample data.

Scenario comparison

Scenario	Expected outcome pattern	Why
Standard	Uses the selected profile and submitted values without special scenario adjustment.	Routine operating assumptions are used.
Limited Budget	Cost-sensitive options may improve when the scenario contains cost or budget adjustments.	Budget pressure changes the operating assumptions, not the submitted business data.
High Demand	Availability and quality may become more important when the scenario defines demand-related adjustments.	Scarcity can make speed, availability, and quality more valuable.
Risk Control	Options with stronger reputation, title speed, and lower uncertainty may improve.	The scenario represents a more cautious operating context.

If a selected scenario contains computational overrides, the Decision API applies them before scoring and records that in execution metadata. If the selected scenario is descriptive only, it is still preserved as decision context, but no scenario-specific score adjustment is detected.

Complete API examples

curl -X POST "https://dde.vinquery.com/api/v1/decide" \
  -H "Authorization: Bearer $DECISIOQ_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"decisionId":"AUTO-AUCT-006","profileId":"quality_focused","scenarioId":"standard","requestContext":{"correlationId":"auction-house-demo-001"},"options":[{"optionId":"premium-metro","name":"Premium Metro Auction","values":{"vehicle_availability_score":95,"buyer_fee_level":1800,"average_vehicle_quality":99,"distance_to_facility":70000,"auction_reputation_score":98,"title_processing_speed":94}},{"optionId":"nearby-budget","name":"Nearby Budget Auction","values":{"vehicle_availability_score":65,"buyer_fee_level":850,"average_vehicle_quality":60,"distance_to_facility":8000,"auction_reputation_score":81,"title_processing_speed":75}}]}'

const request = {
  decisionId: "AUTO-AUCT-006",
  profileId: "quality_focused",
  scenarioId: "standard",
  requestContext: { correlationId: "auction-house-demo-001" },
  options: [
    {
      optionId: "premium-metro",
      name: "Premium Metro Auction",
      values: {
        vehicle_availability_score: 95,
        buyer_fee_level: 1800,
        average_vehicle_quality: 99,
        distance_to_facility: 70000,
        auction_reputation_score: 98,
        title_processing_speed: 94
      }
    },
    {
      optionId: "nearby-budget",
      name: "Nearby Budget Auction",
      values: {
        vehicle_availability_score: 65,
        buyer_fee_level: 850,
        average_vehicle_quality: 60,
        distance_to_facility: 8000,
        auction_reputation_score: 81,
        title_processing_speed: 75
      }
    }
  ]
};

const response = await fetch("https://dde.vinquery.com/api/v1/decide", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${jwtToken}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify(request)
});

const result = await response.json();

type DecisionOption = {
  optionId: string;
  name: string;
  values: Record<string, number>;
};

type DecisionRequest = {
  decisionId: string;
  profileId: string;
  scenarioId: string;
  requestContext: { correlationId: string };
  options: DecisionOption[];
};

const request: DecisionRequest = {
  decisionId: "AUTO-AUCT-006",
  profileId: "quality_focused",
  scenarioId: "standard",
  requestContext: { correlationId: "auction-house-demo-001" },
  options: [
    {
      optionId: "premium-metro",
      name: "Premium Metro Auction",
      values: {
        vehicle_availability_score: 95,
        buyer_fee_level: 1800,
        average_vehicle_quality: 99,
        distance_to_facility: 70000,
        auction_reputation_score: 98,
        title_processing_speed: 94
      }
    },
    {
      optionId: "nearby-budget",
      name: "Nearby Budget Auction",
      values: {
        vehicle_availability_score: 65,
        buyer_fee_level: 850,
        average_vehicle_quality: 60,
        distance_to_facility: 8000,
        auction_reputation_score: 81,
        title_processing_speed: 75
      }
    }
  ]
};

const response = await fetch("https://dde.vinquery.com/api/v1/decide", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${jwtToken}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify(request)
});

const result = await response.json();

import requests

request = {
    "decisionId": "AUTO-AUCT-006",
    "profileId": "quality_focused",
    "scenarioId": "standard",
    "requestContext": {"correlationId": "auction-house-demo-001"},
    "options": [
        {
            "optionId": "premium-metro",
            "name": "Premium Metro Auction",
            "values": {
                "vehicle_availability_score": 95,
                "buyer_fee_level": 1800,
                "average_vehicle_quality": 99,
                "distance_to_facility": 70000,
                "auction_reputation_score": 98,
                "title_processing_speed": 94
            }
        },
        {
            "optionId": "nearby-budget",
            "name": "Nearby Budget Auction",
            "values": {
                "vehicle_availability_score": 65,
                "buyer_fee_level": 850,
                "average_vehicle_quality": 60,
                "distance_to_facility": 8000,
                "auction_reputation_score": 81,
                "title_processing_speed": 75
            }
        }
    ]
}

response = requests.post(
    "https://dde.vinquery.com/api/v1/decide",
    headers={"Authorization": f"Bearer {jwtToken}"},
    json=request,
    timeout=30
)
result = response.json()

<?php
$request = [
    "decisionId" => "AUTO-AUCT-006",
    "profileId" => "quality_focused",
    "scenarioId" => "standard",
    "requestContext" => ["correlationId" => "auction-house-demo-001"],
    "options" => [
        [
            "optionId" => "premium-metro",
            "name" => "Premium Metro Auction",
            "values" => [
                "vehicle_availability_score" => 95,
                "buyer_fee_level" => 1800,
                "average_vehicle_quality" => 99,
                "distance_to_facility" => 70000,
                "auction_reputation_score" => 98,
                "title_processing_speed" => 94
            ]
        ],
        [
            "optionId" => "nearby-budget",
            "name" => "Nearby Budget Auction",
            "values" => [
                "vehicle_availability_score" => 65,
                "buyer_fee_level" => 850,
                "average_vehicle_quality" => 60,
                "distance_to_facility" => 8000,
                "auction_reputation_score" => 81,
                "title_processing_speed" => 75
            ]
        ]
    ]
];

$context = stream_context_create([
    "http" => [
        "method" => "POST",
        "header" => "Authorization: Bearer " . $jwtToken . "\r\nContent-Type: application/json\r\n",
        "content" => json_encode($request),
        "ignore_errors" => true
    ]
]);

$response = file_get_contents("https://dde.vinquery.com/api/v1/decide", false, $context);
$result = json_decode($response, true);

package main

import (
    "bytes"
    "encoding/json"
    "net/http"
)

func executeDecision(jwtToken string) (*http.Response, error) {
    request := map[string]any{
        "decisionId": "AUTO-AUCT-006",
        "profileId": "quality_focused",
        "scenarioId": "standard",
        "requestContext": map[string]any{"correlationId": "auction-house-demo-001"},
        "options": []map[string]any{
            {
                "optionId": "premium-metro",
                "name": "Premium Metro Auction",
                "values": map[string]any{
                    "vehicle_availability_score": 95,
                    "buyer_fee_level": 1800,
                    "average_vehicle_quality": 99,
                    "distance_to_facility": 70000,
                    "auction_reputation_score": 98,
                    "title_processing_speed": 94,
                },
            },
            {
                "optionId": "nearby-budget",
                "name": "Nearby Budget Auction",
                "values": map[string]any{
                    "vehicle_availability_score": 65,
                    "buyer_fee_level": 850,
                    "average_vehicle_quality": 60,
                    "distance_to_facility": 8000,
                    "auction_reputation_score": 81,
                    "title_processing_speed": 75,
                },
            },
        },
    }

    payload, err := json.Marshal(request)
    if err != nil {
        return nil, err
    }

    req, err := http.NewRequest("POST", "https://dde.vinquery.com/api/v1/decide", bytes.NewReader(payload))
    if err != nil {
        return nil, err
    }
    req.Header.Set("Authorization", "Bearer "+jwtToken)
    req.Header.Set("Content-Type", "application/json")

    return http.DefaultClient.Do(req)
}

using System.Net.Http.Headers;
using System.Net.Http.Json;

using var client = new HttpClient();
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", jwtToken);

var request = new
{
    decisionId = "AUTO-AUCT-006",
    profileId = "quality_focused",
    scenarioId = "standard",
    requestContext = new { correlationId = "auction-house-demo-001" },
    options = new[]
    {
        new
        {
            optionId = "premium-metro",
            name = "Premium Metro Auction",
            values = new
            {
                vehicle_availability_score = 95,
                buyer_fee_level = 1800,
                average_vehicle_quality = 99,
                distance_to_facility = 70000,
                auction_reputation_score = 98,
                title_processing_speed = 94
            }
        },
        new
        {
            optionId = "nearby-budget",
            name = "Nearby Budget Auction",
            values = new
            {
                vehicle_availability_score = 65,
                buyer_fee_level = 850,
                average_vehicle_quality = 60,
                distance_to_facility = 8000,
                auction_reputation_score = 81,
                title_processing_speed = 75
            }
        }
    }
};

var response = await client.PostAsJsonAsync("https://dde.vinquery.com/api/v1/decide", request);
var result = await response.Content.ReadFromJsonAsync<object>();

String requestJson = """
{
  "decisionId": "AUTO-AUCT-006",
  "profileId": "quality_focused",
  "scenarioId": "standard",
  "requestContext": { "correlationId": "auction-house-demo-001" },
  "options": [
    {
      "optionId": "premium-metro",
      "name": "Premium Metro Auction",
      "values": {
        "vehicle_availability_score": 95,
        "buyer_fee_level": 1800,
        "average_vehicle_quality": 99,
        "distance_to_facility": 70000,
        "auction_reputation_score": 98,
        "title_processing_speed": 94
      }
    },
    {
      "optionId": "nearby-budget",
      "name": "Nearby Budget Auction",
      "values": {
        "vehicle_availability_score": 65,
        "buyer_fee_level": 850,
        "average_vehicle_quality": 60,
        "distance_to_facility": 8000,
        "auction_reputation_score": 81,
        "title_processing_speed": 75
      }
    }
  ]
}
""";

HttpRequest httpRequest = HttpRequest.newBuilder()
    .uri(URI.create("https://dde.vinquery.com/api/v1/decide"))
    .header("Authorization", "Bearer " + jwtToken)
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(requestJson))
    .build();

HttpResponse<String> response =
    client.send(httpRequest, HttpResponse.BodyHandlers.ofString());

Response and validation examples

{
  "requestId": "b7f1d58c-9e2a-4e3f-9c36-0d8f77f8d001",
  "decisionId": "AUTO-AUCT-006",
  "profile": { "id": "quality_focused", "version": "1.0" },
  "scenario": { "id": "standard", "version": "1.0" },
  "result": {
    "outcome": "RECOMMENDED",
    "recommendedOption": "Premium Metro Auction",
    "score": 0.564
  }
}

{
  "operation": "Decide",
  "error": {
    "code": "UNKNOWN_PROFILE",
    "message": "Profile 'aggressive' is not available for decision AUTO-AUCT-006.",
    "details": [
      "Available profiles: balanced, cost_focused, quality_focused, risk_averse"
    ]
  }
}

{
  "operation": "Decide",
  "error": {
    "code": "UNKNOWN_SCENARIO",
    "message": "Scenario 'economic_downturn' is not available for decision AUTO-AUCT-006.",
    "details": [
      "Available scenarios: standard, limited_budget, high_demand, risk_control"
    ]
  }
}

Best practices

Use the published default Profile unless there is a clear business reason to choose another.
Do not create unnecessary Profiles or duplicate decision definitions just to represent different priorities.
Use Scenarios for environmental assumptions such as demand, budget pressure, market strength, seasonality, or risk posture.
Keep business data independent from Profiles and Scenarios.
Do not encode market assumptions directly into business data when they belong in a Scenario.

Prepared Decision Input

Execution requests send either Business Data or Prepared Decision Input with two or more option records. Each option should include a stable optionId plus the criteria required by the selected decision definition.

{
  "decisionId": "AUTO-AUCT-008",
  "correlationId": "customer-order-20260718-001",
  "businessData": {
    "options": [
      {
        "optionId": "vehicle-a",
        "titleConfidence": 74,
        "mileage": 82000
      },
      {
        "optionId": "vehicle-b",
        "titleConfidence": 91,
        "mileage": 67000
      }
    ]
  }
}

Localization and Unit Normalization

Keep API identifiers stable. Do not localize decision IDs, criterion IDs, route names, request fields, or response fields. Localize labels, descriptions, and user-facing guidance in the client experience.

When Business Data includes measurements, send the source unit with the value. The Integration Platform normalizes supported metric and US customary units to canonical metric values before validation and execution. The Decision Execution service then scores the normalized values deterministically.

"requestContext": {
  "correlationId": "customer-order-20260718-001",
  "locale": "en-CA",
  "measurementSystem": "metric",
  "currency": "CAD",
  "timeZone": "America/Toronto",
  "jurisdiction": { "countryCode": "CA", "regionCode": "ON" }
}

Use measurementSystem for presentation preference. It does not change the recommendation. Trace metadata preserves source value/unit and canonical value/unit for support and audit.

Validation

Validation checks required businessData, candidate count, option identifiers, decision identifiers, correlation identifiers, required fields, measurement units, unit compatibility, and criterion rules such as score and percentage ranges before the decision is executed.

POST https://dde.vinquery.com/api/v1/validate
Content-Type: application/json

Use validation responses to show specific field-level guidance before calling execution. For example, a score or percentage field outside 0 to 100 should be rejected before a recommendation is produced.

Execution

Execution returns a deterministic recommendation, candidate ranking, constraint outcomes, decision result, explanation, validation messages, and integrator diagnostics. Explanation text may help describe the recommendation, but it should not overwrite deterministic results.

POST https://dde.vinquery.com/api/v1/decide
Content-Type: application/json

Error Handling

Business pages should show friendly messages. Developer pages may show HTTP status, validation errors, correlation identifiers, timing, response summaries, and service availability details.

401 means the token is missing, expired, invalid, or issued for the wrong audience.
400 means the prepared decision input failed validation.
404 means the requested decisionId or catalog route was not found.
5xx means a service-side or deployment issue should be reviewed by an integrator.

The Decision API returns structured JSON errors. Validation failures include field-level details when available.

{
  "operation": "Decide",
  "error": {
    "code": "DECISION_INPUT_INVALID",
    "message": "Criterion 'Title Confidence' must be between 0 and 100.",
    "details": [
      "internalCode:SEMANTIC_VALIDATION_FAILED"
    ]
  }
}

Detailed Industry Manuals

These manuals show how DecisioQ concepts apply to specific automotive operating domains. Each guide explains the sector context, catalog discovery flow, decision selection, criteria, profiles, scenarios, prepared input, execution, result interpretation, and production considerations for that industry area.

Use them when you need more than the API reference: they help teams understand which business decisions are available, what data those decisions require, and how a client application should guide users from catalog discovery through a deterministic recommendation.

Auto Auction Integration Manual - acquisition, bidding, inspection, transportation, reconditioning, and remarketing decisions.
Auto Insurance Integration Manual - claims, coverage, investigation, repair routing, risk, and settlement decisions.
Auto Parts Integration Manual - inventory, sourcing, supplier, fulfillment, warranty, return, and branch allocation decisions.
Auto Repair Integration Manual - repair prioritization, technician readiness, parts planning, warranty review, and customer escalation decisions.
Fleet Vehicle Management Integration Manual - fleet acquisition, allocation, maintenance, utilization, replacement, and downtime-risk decisions.
New Car Dealership Integration Manual - inventory, pricing, incentive, sales operations, and customer experience decisions.
Parking Lot Management Integration Manual - occupancy, pricing, enforcement, asset use, event planning, and revenue decisions.
Tire Retail Service Integration Manual - tire sales, fitment, inspection, inventory, service scheduling, and customer retention decisions.
Used Car Dealership Integration Manual - appraisal, acquisition, reconditioning, pricing, merchandising, sales, and inventory-turn decisions.
Vehicle Inspection and Testing Integration Manual - inspection scheduling, compliance review, test routing, certification, and throughput decisions.
Vehicle Leasing Integration Manual - eligibility, renewal, remarketing, residual-value, portfolio, and customer-risk decisions.
Vehicle Rental Integration Manual - fleet allocation, pricing, reservations, maintenance priority, damage handling, and utilization decisions.

DecisioQ Developer Center