AUTO-UCD-008 End-to-End Example

Overview

AUTO-UCD-008, Determine Trade-In Value, compares candidate trade-in appraisal options using vehicle fit, market demand, gross margin potential, reconditioning cost, compliance risk, and customer value.

Decision ID: AUTO-UCD-008
Decision Name: Determine Trade-In Value
Industry Profile: used-car-dealership-determine-trade-in-value-auto-ucd-008 version 1.0.0
Default Profile: balanced
Runnable Scenario: standard_retail
Catalog: DKR-AUTO-RUNTIME-001, version 13.9.3
API Compatibility: 7.4.0 or later catalog execution flow

The deterministic Decision Engine ranks the options. AI explanation text, when returned, is explanatory only and must not choose, rerank, or override the deterministic result.

Understanding This Decision

Determine Trade-In Value helps a used-car dealership compare ways to handle a trade-in appraisal before committing to a valuation path. The decision is useful when an appraisal team needs a repeatable recommendation that balances retail fit, market demand, expected margin, reconditioning burden, compliance exposure, and customer value.

Business question

Which option should be recommended for determine trade-in value in the selected Used Car Dealership context?

Expected outcome

A recommended option or ranked set of options with the criteria that most influenced the result.

Typical users

Used-car managers, appraisal teams, inventory planners, sales managers, and integration teams building trade-in workflows.

Decision boundary

Use this decision to rank submitted candidate options. It does not discover missing options and does not replace dealership approvals, compliance checks, or professional appraisal judgment.

Assumptions: submitted options represent real options, values use the units and scales requested by the catalog, and the selected profile and scenario reflect the intended dealership priorities.

Architecture

Request a token from the Identity service.
Use the returned jwtToken as the bearer token.
Load the catalog and decision detail from DKS.
Build a Prepared Decision Input using canonical criterion IDs.
Execute the decision through DDE.
Use X-Request-Id and X-Correlation-Id for tracing across DDE and DKS.

Token propagation: when DDE needs authoritative decision metadata during execution, it forwards the caller's bearer token to DKS with the request identifiers. This lets the catalog and execution records share the same security and tracing context.

Authentication

Request a secure session token from Identity. The current token response field is jwtToken.

Token request

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

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

Catalog Discovery

Use DKS to discover the catalog and then load complete metadata for AUTO-UCD-008.

Catalog

GET https://dks.vinquery.com/decisioncatalog
Authorization: Bearer {jwtToken}

Decision Detail

GET https://dks.vinquery.com/decisioncatalog/decisions/AUTO-UCD-008
Authorization: Bearer {jwtToken}

Criteria

Criterion IDs are intentionally stable machine identifiers. Display labels are for users; request values should be keyed by canonical criterionId.

Criterion ID	Name	Direction	Weight	Validation
`determine_trade_in_value_vehicle_fit_score`	Determine Trade In Value Fit Score	maximize	20	`score_0_to_100`
`determine_trade_in_value_market_demand_score`	Market Demand Score	maximize	17	`score_0_to_100`
`determine_trade_in_value_gross_margin_potential`	Gross Margin Potential	maximize	17	`non_negative_currency`
`determine_trade_in_value_reconditioning_or_process_cost`	Reconditioning / Process Cost	minimize	16	`non_negative_currency`
`determine_trade_in_value_compliance_risk_score`	Compliance Risk Score	minimize	15	`score_0_to_100`
`determine_trade_in_value_customer_value_score`	Customer Value Score	maximize	15	`score_0_to_100`

Constraint Processing

This decision currently has no catalog-defined hard constraints. All validated candidates proceed to criteria-based ranking.

Verified Catalog Constraint	Status	Effect
None returned by DKS for `AUTO-UCD-008`	No hard constraints defined	Candidate eligibility is determined by request validation; all validated candidates are ranked by criteria.

Eligible and Excluded Candidates

{
  "constraintSummary": {
    "definedConstraintCount": 0,
    "activeConstraintCount": 0,
    "eligibleOptionCount": 3,
    "excludedOptionCount": 0,
    "eligibleOptions": [
      "OPTION-001",
      "OPTION-002",
      "OPTION-003"
    ],
    "excludedOptions": []
  }
}

Constraint Handling Pattern

const constraints = decisionDetail.constraints || [];
if (constraints.length === 0) {
  // No catalog-defined hard constraints.
  // Submit all validated candidates for criteria-based ranking.
}

const summary = response.constraintSummary;
const excluded = response.decisionResult?.excludedOptions || [];

Excluded candidates do not participate in ranking because hard constraints are evaluated before scoring. For AUTO-UCD-008, no candidates are excluded by catalog-defined constraints because DKS currently defines none for this decision.

Industry Profile

The active industry profile uses $.salesOpportunities as the options path, $.optionId as the option ID, and $.name as the option display name.

Business Data Path	Criterion ID
`option.assessment.determineTradeInValueFitScore`	`determine_trade_in_value_vehicle_fit_score`
`option.assessment.marketDemandScore`	`determine_trade_in_value_market_demand_score`
`option.financial.grossMarginPotential`	`determine_trade_in_value_gross_margin_potential`
`option.financial.reconditioningProcessCost`	`determine_trade_in_value_reconditioning_or_process_cost`
`option.risk.complianceRiskScore`	`determine_trade_in_value_compliance_risk_score`
`option.assessment.customerValueScore`	`determine_trade_in_value_customer_value_score`

Business Data Fragment

{
  "requestContext": {
    "sourceSystem": "used-car-appraisal-demo",
    "correlationId": "auto-ucd-008-demo-001"
  },
  "salesOpportunities": [
    {
      "optionId": "OPTION-001",
      "name": "Retail Trade Option",
      "assessment": {
        "determineTradeInValueFitScore": 86,
        "marketDemandScore": 92,
        "customerValueScore": 84
      },
      "financial": {
        "grossMarginPotential": 3200,
        "reconditioningProcessCost": 900
      },
      "risk": {
        "complianceRiskScore": 22
      }
    }
  ]
}

Prepared Option Values

{
  "optionId": "OPTION-001",
  "name": "Retail Trade Option",
  "values": {
    "determine_trade_in_value_vehicle_fit_score": 86,
    "determine_trade_in_value_market_demand_score": 92,
    "determine_trade_in_value_gross_margin_potential": 3200,
    "determine_trade_in_value_reconditioning_or_process_cost": 900,
    "determine_trade_in_value_compliance_risk_score": 22,
    "determine_trade_in_value_customer_value_score": 84
  }
}

Profiles and Scenarios

A profile changes criterion weights. A scenario describes the operating context for the execution. The active DKS catalog exposes these choices with the decision detail response.

Profile ID	Name	Purpose
`balanced`	Balanced	Balances vehicle fit, market demand, profitability, cost, compliance risk, and customer value.
`profit_focused`	Profit Focused	Places extra emphasis on gross margin potential and cost control.
`risk_control`	Risk Control	Places extra emphasis on title, compliance, condition, and operational risk control.
`customer_value`	Customer Value	Places extra emphasis on customer fit, customer value, and market demand.

Scenario ID	Name	Use When
`standard_retail`	Standard Retail Case	Normal used-car dealership operating conditions for Determine Trade-In Value.
`margin_pressure`	Margin Pressure	Competitive pricing, auction costs, reconditioning spend, or aged inventory creates pressure to protect gross margin.
`high_compliance_risk`	High Compliance Risk	Title, disclosure, financing, warranty, certification, or customer-risk factors require stronger compliance controls.
`fast_turn_inventory`	Fast-Turn Inventory	Faster inventory movement, shorter cycle time, or quicker customer conversion is prioritized.

Use standard_retail in runnable examples because it is present in the active DKS scenario list for AUTO-UCD-008.

Prepared Input

For Prepared Decision Input, send decisionId, selected profile/scenario IDs, and option values keyed by canonical criterion ID.

Prepared Decision Input JSON

{
  "decisionId": "AUTO-UCD-008",
  "profileId": "balanced",
  "scenarioId": "standard_retail",
  "algorithm": "TOPSIS",
  "weightStrategy": "Manual",
  "runSensitivity": false,
  "requestContext": {
    "correlationId": "auto-ucd-008-demo-001"
  },
  "options": [
    {
      "optionId": "OPTION-001",
      "name": "Retail Trade Option",
      "values": {
        "determine_trade_in_value_vehicle_fit_score": 86,
        "determine_trade_in_value_market_demand_score": 92,
        "determine_trade_in_value_gross_margin_potential": 3200,
        "determine_trade_in_value_reconditioning_or_process_cost": 900,
        "determine_trade_in_value_compliance_risk_score": 22,
        "determine_trade_in_value_customer_value_score": 84
      }
    },
    {
      "optionId": "OPTION-002",
      "name": "Wholesale Backup Option",
      "values": {
        "determine_trade_in_value_vehicle_fit_score": 78,
        "determine_trade_in_value_market_demand_score": 73,
        "determine_trade_in_value_gross_margin_potential": 4100,
        "determine_trade_in_value_reconditioning_or_process_cost": 1600,
        "determine_trade_in_value_compliance_risk_score": 35,
        "determine_trade_in_value_customer_value_score": 76
      }
    },
    {
      "optionId": "OPTION-003",
      "name": "Certified Retail Option",
      "values": {
        "determine_trade_in_value_vehicle_fit_score": 91,
        "determine_trade_in_value_market_demand_score": 85,
        "determine_trade_in_value_gross_margin_potential": 2300,
        "determine_trade_in_value_reconditioning_or_process_cost": 650,
        "determine_trade_in_value_compliance_risk_score": 18,
        "determine_trade_in_value_customer_value_score": 88
      }
    }
  ]
}

Execute

cURL

curl -X POST "https://dde.vinquery.com/api/v1/decide" \
  -H "Authorization: Bearer ${DECISIOQ_TOKEN}" \
  -H "Content-Type: application/json" \
  -H "X-Correlation-Id: auto-ucd-008-demo-001" \
  --data @auto-ucd-008-execute.json

The Decision Engine validates the request, retrieves authoritative criteria, constraints, profiles, scenarios, and validation metadata from DKS, applies hard constraints, ranks eligible options, and returns the decision result plus execution metadata.

Interpret the Result

The successful response is centered on decisionResult. The winner and ranking are deterministic outputs; optional explanation fields add context but do not change the ranking.

Successful Response Shape

{
  "service": "decisioq",
  "version": "7.6.3",
  "requestId": "0HNE...",
  "operation": "Decide",
  "success": true,
  "decisionType": "AUTO-UCD-008",
  "decisionVersion": "13.9.3",
  "timestampUtc": "2026-07-18T00:00:00Z",
  "decisionResult": {
    "winner": "OPTION-001",
    "confidence": 72.4,
    "ranking": [
      {
        "optionId": "OPTION-001",
        "score": 0.8421,
        "breakdown": {
          "determine_trade_in_value_vehicle_fit_score": 0.20,
          "determine_trade_in_value_market_demand_score": 0.17,
          "determine_trade_in_value_gross_margin_potential": 0.17,
          "determine_trade_in_value_reconditioning_or_process_cost": 0.16,
          "determine_trade_in_value_compliance_risk_score": 0.15,
          "determine_trade_in_value_customer_value_score": 0.15
        },
        "normalizationBreakdown": {}
      }
    ],
    "excludedOptions": [],
    "explanation": {
      "summary": "Retail Trade Option ranked highest based on the submitted trade-in valuation criteria.",
      "strengths": [],
      "weaknesses": [],
      "exclusions": []
    }
  },
  "constraintSummary": {
    "definedConstraintCount": 0,
    "activeConstraintCount": 0,
    "eligibleOptionCount": 3,
    "excludedOptionCount": 0,
    "eligibleOptions": [
    "OPTION-001",
    "OPTION-002",
    "OPTION-003"
    ],
    "excludedOptions": []
  },
  "warnings": [],
  "requestContext": {
    "correlationId": "auto-ucd-008-demo-001"
  }
}

WinnerThe selected option ID in decisionResult.winner.

RankingAll eligible options ordered by score.

BreakdownCriterion-level evidence for the ranking.

Sensitivity Analysis

Set runSensitivity to true on catalog execution when the client wants recommendation-stability information in the same response. The sensitivity engine perturbs criterion weights by controlled factors and reports whether the winner remains stable.

Sensitivity Result Shape

{
  "sensitivityResult": {
    "stableWinner": true,
    "winner": "OPTION-001",
    "mostSensitiveCriterion": "determine_trade_in_value_market_demand_score",
    "confidence": 95,
    "criterionImpacts": {
      "determine_trade_in_value_market_demand_score": 0.1842
    },
    "winnerChangeCounts": {
      "determine_trade_in_value_market_demand_score": 0
    }
  }
}

Use sensitivity output to decide whether a recommendation is robust enough for automation or should be reviewed by a person.

Explanation of Decision Result

Every successful response can include deterministic explanation text under decisionResult.explanation and explanation. If the optional AI layer is enabled, the response may also include an ai block with structured business-language explanation fields.

AI Explanation Shape

{
  "ai": {
    "enabled": true,
    "generated": true,
    "schemaValidated": true,
    "explanation": {
      "summary": "The selected trade-in option provided the strongest overall trade-in valuation fit.",
      "whyRecommended": "It combined strong vehicle fit and market demand with acceptable reconditioning cost, compliance risk, and customer value.",
      "keyDrivers": [],
      "tradeoffs": [],
      "competitors": [],
      "sensitivitySummary": "Sensitivity analysis was not included in this response.",
      "scenarioSummary": "The standard retail scenario was selected.",
      "risks": [],
      "nextSteps": [],
      "assumptions": []
    }
  }
}

Explanation output is supporting context. Business-facing pages should render the explanation, warnings, assumptions, and limitations without provider branding.

Tracing and Logs

Use request identifiers to connect client, catalog, and execution activity during support or integration testing.

X-Request-Id: Optional client-supplied request ID. If omitted, the server generates one.
X-Correlation-Id: Optional client correlation value propagated from DDE to DKS.
requestContext.correlationId: Optional payload value echoed in the response and used for tracing.
executionTrace: Advanced execution metadata including selected profile, selected scenario, effective weights, and applied constraints.

Code Examples

These examples demonstrate the current DecisioQ flow:

Request jwtToken from https://identity.vinquery.com/connect/token.
Load AUTO-UCD-008 metadata from https://dks.vinquery.com/decisioncatalog/decisions/AUTO-UCD-008.
Execute a Prepared Decision Input at https://dde.vinquery.com/api/v1/decide.

Set these environment variables before running any companion example:

Environment variables

DECISIOQ_CLIENT_ID
DECISIOQ_CLIENT_SECRET

Optional:
DECISIOQ_IDENTITY_URL=https://identity.vinquery.com/connect/token
DECISIOQ_DKS_URL=https://dks.vinquery.com
DECISIOQ_DDE_URL=https://dde.vinquery.com

Download the source files directly:

README.mdSetup and run notes Prepared Input JSONShared request payload cURL shell scriptrun-auto-ucd-008.sh C# Program.cs.NET 8 console example JavaScriptNode.js module TypeScriptTyped fetch example PythonStandard library example PHPcURL extension example Gonet/http example Javajava.net.http example Complete ASP.NET Core ExampleRunnable .NET 8 project ZIP

Troubleshooting

Symptom	Likely Cause	What to Check
401 Unauthorized	Missing, expired, or invalid bearer token.	Request a fresh `jwtToken` from Identity and send it as `Authorization: Bearer ...`.
Decision not found	The decision ID is not in the active catalog.	Load `/decisioncatalog/decisions/AUTO-UCD-008` and confirm the ID is published.
Validation failed	A required criterion value is missing or outside its rule.	Use canonical criterion IDs and keep score values in the expected range.
HTML error response	An upstream hosted service failed before returning JSON.	Check service health and server logs for Identity, DKS, or DDE.

Production Checklist

Security

Keep API Consumer credentials and jwtTokens on the server side. Use HTTPS, short-lived bearer tokens, and an API Consumer linked to a DecisioQ account for usage accounting.

Catalog

Load decision metadata from DKS and cache cautiously. Refresh when catalog versions change.

Request Quality

Use canonical criterion IDs, validate value ranges, and send at least two candidate options.

Operations

Send correlation IDs, record request IDs, and monitor non-JSON upstream failures.

Explanation

Display explanation text as supporting context only. Never let AI text override deterministic results.

User Experience

Show business labels to users and keep raw execution trace collapsed for advanced diagnostics.