What DecisioQ Does

DecisioQ helps software teams turn repeatable business choices into consistent, explainable recommendations. A client application sends candidate options, DecisioQ evaluates those options against the criteria defined for the selected decision, applies the chosen business profile and scenario, and returns a deterministic recommendation with ranked results and supporting context.

The platform is useful when a team needs to compare operational choices that involve competing business factors, such as cost, risk, quality, speed, capacity, reputation, compliance, or customer impact. Automotive examples include auction buying, insurance claims, fleet replacement, parts sourcing, repair routing, tire service, towing, vehicle inspection, leasing, rental, and dealership operations.

The deterministic Decision Result is the authoritative computational output. Explanation text helps business users understand the result, but it does not replace the scores, ranks, constraint outcomes, validation messages, or audit identifiers returned by the Decision API.

Recommended Integration Path

One-time integration

Choose a catalog decision, map your application fields to its Business Data contract, and store the selected decisionId in configuration.

Application startup or configuration refresh

Authenticate from trusted server-side code, cache the JWT until shortly before expiration, and optionally refresh the selected decision definition. Do not browse the catalog before every request.

Every decision event

Send decisionId and current businessData to POST /api/v1/decide, then display the recommendation, ranking, explanation, warnings, and correlation identifier. DecisioQ applies the catalog-defined methodology automatically unless you deliberately override it.

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
Decision Catalog service:  https://dks.vinquery.com
Decision Execution service: https://dde.vinquery.com

End-to-End Flow

A healthy integration starts with catalog discovery, not hard-coded form 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.

1. Authenticate once from the server side and reuse the bearer token until shortly before it expires.
2. Load sectors, categories, and decisions from the catalog so users can choose a business decision by name.
3. Load a decision definition such as AUTO-AUCT-006 to retrieve criteria, profiles, scenarios, constraints, samples, and display metadata.
4. Render the criterion collection and collect business data for each option, preserving the stable decisionId, profileId, scenarioId, and optionId values internally.
5. Validate the prepared criteria mode before execution and show field-level guidance when available.
6. Execute the decision and show the recommendation, ranked options, excluded option outcomes, explanation, warnings, and correlation identifier.

Authentication

Authentication is server-to-server. A browser, mobile app, or desktop client should call your backend, and your backend should request a JWT from the Identity service. Never place the API Consumer Client Secret in browser JavaScript, public source code, or distributed client applications.

The token request includes the intended audience for the API being called. For DecisioQ, use vinquery:api:decisioq. Use the returned expiresUtc value as the source of truth and refresh the token shortly before it expires instead of requesting a new token for every API call.

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}

Learn how to build a Server-Side Proxy->

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. Use discovery when building selectors, guided data collection screens, decision detail pages, and developer tools.

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

Sector and Category selectors should display business names and populate from the real catalog hierarchy. Decision dropdowns should show Decision Name only, while the selected decisionId remains available internally and visible in an appropriate developer or integrator context.

Decision detail metadata should drive the user interface. Criterion summaries, purpose, business meaning, data guidance, common pitfalls, profile choices, scenario choices, and constraint definitions can be shown beside the Business Data entry fields so a first-time user understands what to provide.

Data Preparation Guide

This generated guide translates the selected Decision Catalog definition into practical field-mapping, validation, and criterion-preparation guidance. It is the authoritative detailed reference; the Interactive Playground shows only a compact summary for the decision currently being tested.

Optional: Profiles and Scenarios

Profiles and Scenarios are distinct core concepts. Decision Concepts is their canonical definition; this section focuses on discovering valid IDs and using them in an integration.

Profiles and Scenarios are selected after a decision is chosen. They belong to the decision definition returned by the Decision 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 Service
             v
       Decision Result

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

Scenario comparison

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 Criteria Mode

Prepared Criteria Mode is the request your backend sends after selecting a decision and mapping business data into the fields required by that decision. Each request should identify the decision, selected profile and scenario when used, a correlation identifier for traceability, and two or more candidate options.

Each option should include a stable optionId, a user-facing name when available, and values for the criteria required by the selected decision definition. Do not invent fields that are not part of the decision metadata, and do not submit duplicate criterion keys under both label and identifier forms.

{
  "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
      }
    }
  ]
}

Result Handling

Client applications should separate business-facing result content from developer diagnostics. Business users usually need the recommended option, ranked options, excluded options, summary explanation, warnings, and the most important criteria. Developers and integrators may also need correlation identifiers, HTTP status, validation messages, timing, and execution metadata.

Hard constraints are evaluated before ranking. Excluded options should be shown clearly, but they should not be mixed into the ranked option list because they did not participate in criteria-based scoring.

Localization and Unit Normalization

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

Unless the selected endpoint and decision schema explicitly support unit-bearing values, convert measurements to the canonical units required by the decision definition before validation and execution. Do not infer units or currency from locale.

The following object is conceptual only and illustrates independent presentation concerns; do not add it to a request unless the endpoint schema documents these fields.

"requestContext": {
  "locale": "en-CA",
  "measurementSystem": "metric",
  "currency": "CAD",
  "timeZone": "America/Toronto",
  "jurisdiction": "CA-ON"
}

Validation

Validation checks required Business Data, candidate count, option identifiers, decision identifiers, correlation identifiers, required fields, and criterion rules such as score and percentage ranges. Unit validation or conversion applies only where the selected endpoint and schema explicitly document it.

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, option 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

HTTP Status Codes and Error Handling

Handle failures by category and keep customer-facing messages separate from developer diagnostics. The following statuses are supported by the current Decision Catalog and Decision Service implementation; endpoint-specific validation details remain in the API Guide.

Do not assume 422 or 429 behavior: the current public Decision Catalog and Decision Service implementation does not define those as general response contracts. Add handling only when an endpoint contract or gateway policy explicitly documents it.

Send a stable business-workflow value in requestContext.correlationId (or X-Correlation-Id where documented). Record the server-generated requestId from the response body or X-Request-Id response header. Include both when troubleshooting, without logging tokens, secrets, or sensitive Business Data.

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"
    ]
  }
}

Production Readiness

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.