DecisioQ Decision API Quick Start

1Prerequisites

You need your assigned identity base URL, Decision API base URL, Knowledge Catalog base URL, API Consumer client ID, API Consumer client secret, and token audience. For Decision API calls, the audience is vinquery:api:decisioq.

Keep this page quick. Use this page to make the first working calls. Route details, error formats, and integration patterns live in the API Guide.

2Obtain a JWT token

Call the identity service with your assigned credentials and the target audience.

POST https://identity.vinquery.com/connect/token

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

export DECISIOQ_TOKEN="paste-token-here"

const tokenResponse = await fetch("https://identity.vinquery.com/connect/token", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    clientId: "YOUR_CLIENT_ID",
    clientSecret: "YOUR_CLIENT_SECRET",
    audience: "vinquery:api:decisioq"
  })
});

const { jwtToken } = await tokenResponse.json();

type TokenResponse = { jwtToken: string };

const tokenResponse = await fetch("https://identity.vinquery.com/connect/token", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    clientId: "YOUR_CLIENT_ID",
    clientSecret: "YOUR_CLIENT_SECRET",
    audience: "vinquery:api:decisioq"
  })
});

const { jwtToken } = await tokenResponse.json() as TokenResponse;

import requests

token_response = requests.post(
    "https://identity.vinquery.com/connect/token",
    json={
        "clientId": "YOUR_CLIENT_ID",
        "clientSecret": "YOUR_CLIENT_SECRET",
        "audience": "vinquery:api:decisioq"
    },
    timeout=30
)
jwtToken = token_response.json()["jwtToken"]

<?php
$payload = json_encode([
    "clientId" => "YOUR_CLIENT_ID",
    "clientSecret" => "YOUR_CLIENT_SECRET",
    "audience" => "vinquery:api:decisioq"
]);

$context = stream_context_create([
    "http" => [
        "method" => "POST",
        "header" => "Content-Type: application/json\r\n",
        "content" => $payload,
        "ignore_errors" => true
    ]
]);

$response = file_get_contents("https://identity.vinquery.com/connect/token", false, $context);
$token = json_decode($response, true);
$jwtToken = $token["jwtToken"];

package main

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

func getToken() (string, error) {
    body := []byte(`{"clientId":"YOUR_CLIENT_ID","clientSecret":"YOUR_CLIENT_SECRET","audience":"vinquery:api:decisioq"}`)

    resp, err := http.Post("https://identity.vinquery.com/connect/token", "application/json", bytes.NewReader(body))
    if err != nil {
        return "", err
    }
    defer resp.Body.Close()

    var token struct {
        JwtToken string `json:"jwtToken"`
    }
    if err := json.NewDecoder(resp.Body).Decode(&token); err != nil {
        return "", err
    }
    return token.JwtToken, nil
}

using System.Net.Http.Json;

using var client = new HttpClient();

var tokenResponse = await client.PostAsJsonAsync(
    "https://identity.vinquery.com/connect/token",
    new
    {
        clientId = "YOUR_CLIENT_ID",
        clientSecret = "YOUR_CLIENT_SECRET",
        audience = "vinquery:api:decisioq"
    });

tokenResponse.EnsureSuccessStatusCode();

var token = await tokenResponse.Content.ReadFromJsonAsync<TokenResponse>();
var jwtToken = token!.JwtToken;

public sealed record TokenResponse(string JwtToken);

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://identity.vinquery.com/connect/token"))
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString("""
      {"clientId":"YOUR_CLIENT_ID","clientSecret":"YOUR_CLIENT_SECRET","audience":"vinquery:api:decisioq"}
      """))
    .build();

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

3Load the Knowledge Catalog

Load sectors, categories, and decision metadata before collecting business data. The Knowledge Catalog is secured, so send the bearer token on catalog requests.

GET https://dks.vinquery.com/decisioncatalog

curl -X GET "https://dks.vinquery.com/decisioncatalog" \
  -H "Authorization: Bearer $DECISIOQ_TOKEN" \
  -H "Accept: application/json"

const catalogResponse = await fetch("https://dks.vinquery.com/decisioncatalog", {
  headers: {
    Authorization: `Bearer ${jwtToken}`,
    Accept: "application/json"
  }
});

const catalog = await catalogResponse.json();

type Catalog = {
  sectors: Array<{ sectorCode: string; sector: string; decisionCount: number }>;
};

const catalogResponse = await fetch("https://dks.vinquery.com/decisioncatalog", {
  headers: {
    Authorization: `Bearer ${jwtToken}`,
    Accept: "application/json"
  }
});

const catalog = await catalogResponse.json() as Catalog;

catalog_response = requests.get(
    "https://dks.vinquery.com/decisioncatalog",
    headers={
        "Authorization": f"Bearer {jwtToken}",
        "Accept": "application/json"
    },
    timeout=30
)
catalog = catalog_response.json()

<?php
$context = stream_context_create([
    "http" => [
        "method" => "GET",
        "header" => "Authorization: Bearer " . $jwtToken . "\r\nAccept: application/json\r\n",
        "ignore_errors" => true
    ]
]);

$response = file_get_contents("https://dks.vinquery.com/decisioncatalog", false, $context);
$catalog = json_decode($response, true);

req, err := http.NewRequest("GET", "https://dks.vinquery.com/decisioncatalog", nil)
if err != nil {
    return err
}
req.Header.Set("Authorization", "Bearer "+jwtToken)
req.Header.Set("Accept", "application/json")

resp, err := http.DefaultClient.Do(req)
if err != nil {
    return err
}
defer resp.Body.Close()

var catalog map[string]any
err = json.NewDecoder(resp.Body).Decode(&catalog)

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

using var client = new HttpClient();
client.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", jwtToken);
client.DefaultRequestHeaders.Accept.ParseAdd("application/json");

var catalog = await client.GetFromJsonAsync<Dictionary<string, object>>(
    "https://dks.vinquery.com/decisioncatalog");

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://dks.vinquery.com/decisioncatalog"))
    .header("Authorization", "Bearer " + jwtToken)
    .header("Accept", "application/json")
    .GET()
    .build();

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

What you should see Sectors, real categories, and decision counts. For a concrete decision detail lookup, call https://dks.vinquery.com/decisioncatalog/decisions/AUTO-AUCT-008.

4Select Profile and Scenario

Decision detail metadata tells you which profileId and scenarioId values are valid for that decision. A Profile controls how the decision is evaluated. A Scenario describes the operating assumptions for the same business data.

{
  "decisionId": "AUTO-AUCT-006",
  "profileId": "balanced",
  "scenarioId": "standard"
}

Do not hard-code unavailable values. Profiles and Scenarios are defined by each decision. Discover them from https://dks.vinquery.com/decisioncatalog/decisions/AUTO-AUCT-006.

5Preview Decision

Preview Decision validates the selected decision and business data without producing a recommendation. Validation includes required fields, candidate counts, ID lengths, and catalog-defined numeric rules such as score and percentage ranges.

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

curl -X POST "https://dde.vinquery.com/api/v1/validate" \
  -H "Authorization: Bearer $DECISIOQ_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"industry":"Automotive","decisionId":"AUTO-AUCT-008","businessData":{"auctionLots":[{"optionId":"lot-001","titleConfidence":74}]},"requestContext":{"correlationId":"client-workflow-123"}}'

const decisionRequest = {
  industry: "Automotive",
  decisionId: "AUTO-AUCT-008",
  businessData: {
    auctionLots: [{ optionId: "lot-001", titleConfidence: 74 }]
  },
  requestContext: {
    correlationId: "client-workflow-123",
    locale: "en-CA",
    measurementSystem: "metric",
    currency: "CAD",
    timeZone: "America/Toronto"
  }
};

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

const preview = await previewResponse.json();

type DecisionRequest = {
  industry: string;
  decisionId: string;
  businessData: { auctionLots: Array<{ optionId: string; titleConfidence: number }> };
  requestContext: { correlationId: string };
};

const decisionRequest: DecisionRequest = {
  industry: "Automotive",
  decisionId: "AUTO-AUCT-008",
  businessData: {
    auctionLots: [{ optionId: "lot-001", titleConfidence: 74 }]
  },
  requestContext: { correlationId: "client-workflow-123" }
};

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

const preview = await previewResponse.json();

decision_request = {
    "industry": "Automotive",
    "decisionId": "AUTO-AUCT-008",
    "businessData": {
        "auctionLots": [{"optionId": "lot-001", "titleConfidence": 74}]
    },
    "requestContext": {"correlationId": "client-workflow-123"}
}

preview_response = requests.post(
    "https://dde.vinquery.com/api/v1/validate",
    headers={"Authorization": f"Bearer {jwtToken}"},
    json=decision_request,
    timeout=30
)
preview = preview_response.json()

<?php
$decisionRequest = [
    "industry" => "Automotive",
    "decisionId" => "AUTO-AUCT-008",
    "businessData" => [
        "auctionLots" => [
            ["optionId" => "lot-001", "titleConfidence" => 74]
        ]
    ],
    "requestContext" => ["correlationId" => "client-workflow-123"]
];

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

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

decisionRequest := map[string]any{
    "industry": "Automotive",
    "decisionId": "AUTO-AUCT-008",
    "businessData": map[string]any{
        "auctionLots": []map[string]any{{"optionId": "lot-001", "titleConfidence": 74}},
    },
    "requestContext": map[string]any{"correlationId": "client-workflow-123"},
}

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

resp, err := http.DefaultClient.Do(req)

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

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

var decisionRequest = new
{
    industry = "Automotive",
    decisionId = "AUTO-AUCT-008",
    businessData = new
    {
        auctionLots = new[]
        {
            new { optionId = "lot-001", titleConfidence = 74 }
        }
    },
    requestContext = new { correlationId = "client-workflow-123" }
};

var previewResponse = await client.PostAsJsonAsync(
    "https://dde.vinquery.com/api/v1/validate",
    decisionRequest);

var preview = await previewResponse.Content.ReadFromJsonAsync<Dictionary<string, object>>();

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

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

What you should see A validation result. If validation fails, fix the business data before executing.

6Execute Decision

Execute Decision runs the selected catalog decision and returns the recommendation. Execution applies catalog-defined hard constraints before ranking eligible options.

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" \
  -d '{"decisionId":"AUTO-AUCT-044","requestContext":{"correlationId":"client-workflow-123"},"options":[{"optionId":"lot-001","values":{"expected_profit_margin":5200,"risk_exposure":12,"title_confidence":90,"repair_uncertainty":12,"management_priority":90}},{"optionId":"lot-002","values":{"expected_profit_margin":4700,"risk_exposure":22,"title_confidence":82,"repair_uncertainty":22,"management_priority":82}}]}'

const catalogExecutionRequest = {
  decisionId: "AUTO-AUCT-044",
  requestContext: {
    correlationId: "client-workflow-123",
    locale: "en-CA",
    measurementSystem: "metric",
    currency: "CAD",
    timeZone: "America/Toronto"
  },
  options: [
    { optionId: "lot-001", values: { expected_profit_margin: 5200, risk_exposure: 12, title_confidence: 90, repair_uncertainty: 12, management_priority: 90 } },
    { optionId: "lot-002", values: { expected_profit_margin: 4700, risk_exposure: 22, title_confidence: 82, repair_uncertainty: 22, management_priority: 82 } }
  ]
};

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

const decisionResult = await executeResponse.json();

type CatalogExecutionRequest = {
  decisionId: string;
  requestContext: { correlationId: string };
  options: Array<{ optionId: string; values: Record<string, number | string | boolean> }>;
};

const catalogExecutionRequest: CatalogExecutionRequest = {
  decisionId: "AUTO-AUCT-044",
  requestContext: { correlationId: "client-workflow-123" },
  options: [
    { optionId: "lot-001", values: { expected_profit_margin: 5200, risk_exposure: 12, title_confidence: 90, repair_uncertainty: 12, management_priority: 90 } },
    { optionId: "lot-002", values: { expected_profit_margin: 4700, risk_exposure: 22, title_confidence: 82, repair_uncertainty: 22, management_priority: 82 } }
  ]
};

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

const decisionResult = await executeResponse.json();

catalog_execution_request = {
    "decisionId": "AUTO-AUCT-044",
    "requestContext": {"correlationId": "client-workflow-123"},
    "options": [
        {"optionId": "lot-001", "values": {"expected_profit_margin": 5200, "risk_exposure": 12, "title_confidence": 90, "repair_uncertainty": 12, "management_priority": 90}},
        {"optionId": "lot-002", "values": {"expected_profit_margin": 4700, "risk_exposure": 22, "title_confidence": 82, "repair_uncertainty": 22, "management_priority": 82}}
    ]
}

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

<?php
$catalogExecutionRequest = [
    "decisionId" => "AUTO-AUCT-044",
    "requestContext" => ["correlationId" => "client-workflow-123"],
    "options" => [
        [
            "optionId" => "lot-001",
            "values" => [
                "expected_profit_margin" => 5200,
                "risk_exposure" => 12,
                "title_confidence" => 90,
                "repair_uncertainty" => 12,
                "management_priority" => 90
            ]
        ],
        [
            "optionId" => "lot-002",
            "values" => [
                "expected_profit_margin" => 4700,
                "risk_exposure" => 22,
                "title_confidence" => 82,
                "repair_uncertainty" => 22,
                "management_priority" => 82
            ]
        ]
    ]
];

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

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

catalogExecutionRequest := map[string]any{
    "decisionId": "AUTO-AUCT-044",
    "requestContext": map[string]any{"correlationId": "client-workflow-123"},
    "options": []map[string]any{
        {"optionId": "lot-001", "values": map[string]any{"expected_profit_margin": 5200, "risk_exposure": 12, "title_confidence": 90, "repair_uncertainty": 12, "management_priority": 90}},
        {"optionId": "lot-002", "values": map[string]any{"expected_profit_margin": 4700, "risk_exposure": 22, "title_confidence": 82, "repair_uncertainty": 22, "management_priority": 82}},
    },
}

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

resp, err := http.DefaultClient.Do(req)
if err != nil {
    return err
}
defer resp.Body.Close()

var decisionResult map[string]any
err = json.NewDecoder(resp.Body).Decode(&decisionResult)

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

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

var catalogExecutionRequest = new
{
    decisionId = "AUTO-AUCT-044",
    requestContext = new { correlationId = "client-workflow-123" },
    options = new[]
    {
        new
        {
            optionId = "lot-001",
            values = new Dictionary<string, object>
            {
                ["expected_profit_margin"] = 5200,
                ["risk_exposure"] = 12,
                ["title_confidence"] = 90,
                ["repair_uncertainty"] = 12,
                ["management_priority"] = 90
            }
        },
        new
        {
            optionId = "lot-002",
            values = new Dictionary<string, object>
            {
                ["expected_profit_margin"] = 4700,
                ["risk_exposure"] = 22,
                ["title_confidence"] = 82,
                ["repair_uncertainty"] = 22,
                ["management_priority"] = 82
            }
        }
    }
};

var executeResponse = await client.PostAsJsonAsync(
    "https://dde.vinquery.com/api/v1/decide",
    catalogExecutionRequest);

var decisionResult = await executeResponse.Content.ReadFromJsonAsync<Dictionary<string, object>>();

HttpRequest request = 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(catalogExecutionRequestJson))
    .build();

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

What you should see A decision response with ranking, recommendation, confidence, warnings when applicable, execution metadata, and explanation when returned.

6Next steps

After the first successful calls, use the studio for an end-to-end walkthrough or open the API Guide for full route details.

Open Business Decision Studio Open Developer Center Open API Guide

DecisioQ Quick Start