AUTO-AUCT-044 End-to-End Example

Overview

AUTO-AUCT-044, Approve High-Risk Purchase, determines whether a high-risk auction vehicle purchase should be approved, escalated, deferred, or rejected.

Decision ID: AUTO-AUCT-044
Decision Name: Approve High-Risk Purchase
Decision Preparation Model: auto-auctions-approve-high-risk-purchase-auto-auct-044 version 1.0.0
Default Profile: balanced
Default Scenario: standard
Catalog: DKR-AUTO-RUNTIME-001, version 13.9.3

The deterministic Decision Service ranks eligible purchase cases. The explanation object is explanatory only and must not choose, rerank, or override the deterministic result.

5-Minute Quick Path

Goal

evaluate a high-risk purchase using expected margin, risk exposure, title confidence, repair uncertainty, and management priority.

Recommended mode

Business Data Mode when you have ordinary operational records.

You provide

Candidate records matching the published input schema and Decision Preparation Model.

DecisioQ returns

A ranked recommendation with the winning option and score evidence.

First working request →

Understanding This Decision

Approve High-Risk Purchase helps Compliance & Risk teams compare candidate purchase cases when profit opportunity must be weighed against risk exposure, title confidence, repair uncertainty, and management priority.

Business question

Which high-risk purchase case should be recommended in the selected Auto Auctions context?

Expected outcome

A recommended purchase case or ranked set of purchase cases with the criteria and constraints that most influenced the result.

Typical users

Operations managers, compliance teams, auction buyers, risk reviewers, and integration teams building controlled purchase workflows.

Decision boundary

Use this decision to compare submitted purchase cases. It supports business judgment and does not replace required legal, title, compliance, or management approvals.

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
`expected_profit_margin`	Expected Profit Margin	maximize	25	`non_negative_currency`
`risk_exposure`	Risk Exposure	minimize	30	`score_0_to_100`
`title_confidence`	Title Confidence	maximize	15	`score_0_to_100`
`repair_uncertainty`	Repair Uncertainty	minimize	15	`score_0_to_100`
`management_priority`	Management Priority	maximize	15	`score_0_to_100`

Data Preparation Guide

Loading criterion-specific integration guidance...

Constraint Processing

This decision includes one catalog-defined hard constraint. Decision Catalog returns the constraint with the decision detail, and Decision Service evaluates it before criteria-based ranking.

Verified Catalog Constraint	Status	Effect
`AUTO-AUCT-044-TITLE-CONFIDENCE-MIN-80`	Hard, enabled, mandatory	Requires `title_confidence >= 80` before a candidate can participate in ranking.

Eligible and Excluded Candidates

{
  "constraintSummary": {
    "definedConstraintCount": 1,
    "activeConstraintCount": 1,
    "eligibleOptionCount": 2,
    "excludedOptionCount": 1,
    "eligibleOptions": [
      "option-1",
      "option-2"
    ],
    "excludedOptions": [
      {
        "optionId": "option-3",
        "reasons": [
          "Title confidence is below the minimum threshold of 80."
        ]
      }
    ]
  }
}

Constraint Handling Pattern

const constraints = decisionDetail.constraints || [];
if (constraints.length > 0) {
  // Decision Service applies catalog constraints before ranking.
  // Excluded candidates appear in response.constraintSummary.excludedOptions.
}

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-AUCT-044, option-3 is excluded from the showcase sample because its title confidence is below the catalog threshold.

Decision Preparation Model

The published Decision Preparation Model validates and transforms illustrative Business Data into the canonical criteria required by AUTO-AUCT-044 before Decision Service applies ranking.

Profile ID: auto-auctions-approve-high-risk-purchase-auto-auct-044
Version: 1.0.0
Options Path: $.auctionLots
Option ID Path: $.optionId
Display Name Path: $.name

Client Business Data Path	Transformation	Canonical Criterion ID	Unit	Validation
`option.financial.expectedProfitMargin`	direct value	`expected_profit_margin`	Currency	Input Contract
`option.risk.riskExposure`	direct value	`risk_exposure`	Score	Input Contract
`option.compliance.and.risk.titleConfidence`	direct value	`title_confidence`	Score	Input Contract
`option.compliance.and.risk.repairUncertainty`	direct value	`repair_uncertainty`	Score	Input Contract
`option.compliance.and.risk.managementPriority`	direct value	`management_priority`	Score	Input Contract

Illustrative Business Data

{
  "requestContext": {
    "sourceSystem": "automotive-profile-factory",
    "correlationId": "factory-auto-auct-044"
  },
  "auctionLots": [
    {
      "optionId": "LOT-044-01",
      "name": "Approve High-Risk Purchase Option 1",
      "financial": {
        "expectedProfitMargin": 55000.0
      },
      "risk": {
        "riskExposure": 35.0
      },
      "compliance": {
        "and": {
          "risk": {
            "titleConfidence": 88.0,
            "repairUncertainty": 83.0,
            "managementPriority": 29.0
          }
        }
      }
    },
    {
      "optionId": "LOT-044-02",
      "name": "Approve High-Risk Purchase Option 2",
      "financial": {
        "expectedProfitMargin": 90000.0
      },
      "risk": {
        "riskExposure": 42.0
      },
      "compliance": {
        "and": {
          "risk": {
            "titleConfidence": 92.0,
            "repairUncertainty": 45.0,
            "managementPriority": 50.0
          }
        }
      }
    }
  ]
}

Prepared Option Values

{
  "optionId": "LOT-044-01",
  "name": "Approve High-Risk Purchase Option 1",
  "values": {
    "expected_profit_margin": 55000.0,
    "risk_exposure": 35.0,
    "title_confidence": 88.0,
    "repair_uncertainty": 83.0,
    "management_priority": 29.0
  }
}

This example illustrates the published request structure. Adapt it to your organization and validate it against the Input Contract.

Profiles and Scenarios

This example selects a Profile for evaluation emphasis and a Scenario for operating context. Discover both from the selected Decision Catalog definition.

Profile ID	Name	Purpose
`balanced`	Balanced	Preserves the default Decision Catalog criterion weights.
`cost_focused`	Cost Focused	Places stronger emphasis on minimized cost, fee, and expense criteria.
`quality_focused`	Quality Focused	Places stronger emphasis on maximized quality, confidence, value, and performance criteria.
`risk_averse`	Risk Averse	Places stronger emphasis on risk reduction, compliance confidence, and operational reliability.

Scenario ID	Name	Use When
`standard`	Standard Operating Scenario	Routine auction decision execution.
`limited_budget`	Limited Budget	Purchasing or operating capital is constrained, requiring greater cost discipline.
`high_demand`	High Demand	Market demand is strong and timely inventory acquisition is more valuable.
`risk_control`	Risk Control	Operational or compliance risk is elevated and conservative decisioning is preferred.

Business Data Mode

Start here when your application has operational data. DecisioQ applies the published Decision Preparation Model to produce the required criteria.

Business DataDomain records

Preparation ModelValidate and transform

Prepared CriteriaDecision-ready values

DecisionRank candidates

Illustrative certified Business Data request

{
  "decisionId": "AUTO-AUCT-044",
  "businessData": {
    "requestContext": {
      "sourceSystem": "automotive-profile-factory",
      "correlationId": "factory-auto-auct-044"
    },
    "auctionLots": [
      {
        "optionId": "LOT-044-01",
        "name": "Approve High-Risk Purchase Option 1",
        "financial": {
          "expectedProfitMargin": 55000.0
        },
        "risk": {
          "riskExposure": 35.0
        },
        "compliance": {
          "and": {
            "risk": {
              "titleConfidence": 88.0,
              "repairUncertainty": 83.0,
              "managementPriority": 29.0
            }
          }
        }
      },
      {
        "optionId": "LOT-044-02",
        "name": "Approve High-Risk Purchase Option 2",
        "financial": {
          "expectedProfitMargin": 90000.0
        },
        "risk": {
          "riskExposure": 42.0
        },
        "compliance": {
          "and": {
            "risk": {
              "titleConfidence": 92.0,
              "repairUncertainty": 45.0,
              "managementPriority": 50.0
            }
          }
        }
      }
    ]
  }
}

Download Business Data request

Prepared Criteria Mode

Use this mode when your application already calculates decision-ready values keyed by authoritative criterion IDs. Prepared Criteria go directly to the decision.

Download Prepared Criteria request

For Prepared Criteria Mode, send decisionId, selected profile/scenario IDs, and option values keyed by canonical criterion ID. This request intentionally does not duplicate values under display labels.

Prepared Criteria Mode JSON

{
  "decisionId": "AUTO-AUCT-044",
  "profileId": "balanced",
  "scenarioId": "standard",
  "algorithm": "TOPSIS",
  "weightStrategy": "Expert",
  "runSensitivity": false,
  "requestContext": {
    "correlationId": "auto-auct-044-demo-001"
  },
  "options": [
    {
      "optionId": "option-1",
      "name": "Controlled High-Margin Purchase",
      "values": {
        "expected_profit_margin": 5200,
        "risk_exposure": 12,
        "title_confidence": 90,
        "repair_uncertainty": 12,
        "management_priority": 90
      }
    },
    {
      "optionId": "option-2",
      "name": "Borderline Risk Purchase",
      "values": {
        "expected_profit_margin": 4700,
        "risk_exposure": 22,
        "title_confidence": 82,
        "repair_uncertainty": 22,
        "management_priority": 82
      }
    },
    {
      "optionId": "option-3",
      "name": "Defer Pending Documentation",
      "values": {
        "expected_profit_margin": 4300,
        "risk_exposure": 34,
        "title_confidence": 74,
        "repair_uncertainty": 34,
        "management_priority": 74
      }
    }
  ]
}

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-auct-044-demo-001" \
  --data @auto-auct-044-execute.json

Decision Service retrieves authoritative criteria, validation metadata, and constraints from Decision Catalog, excludes candidates that fail mandatory hard constraints, executes the deterministic ranking, and returns the decision result plus execution metadata.

Understanding the Result

Verified Local Result

Recommended option: LOT-044-02

Scores are relative TOPSIS closeness coefficients within this candidate set, not probabilities.

Rank	Option	ID	Score
1	Approve High-Risk Purchase Option 2	`LOT-044-02`	0.545837
2	Approve High-Risk Purchase Option 1	`LOT-044-01`	0.454163

The ranking was calculated in-process with DecisioQ.DecisionEngine.Services.TopsisEngine from the published canonical request. It is not a hosted API capture. Download evidence.

The successful response includes both the deterministic decisionResult and a top-level explanation object. The explanation adds context but does not select, rerank, recalculate, or override the ranking.

Illustrative contract shape — not runtime output

{
  "service": "decisioq",
  "version": "7.6.3",
  "requestId": "0HNE...",
  "operation": "Decide",
  "success": true,
  "decisionType": "AUTO-AUCT-044",
  "decisionVersion": "13.9.3",
  "timestampUtc": "2026-07-19T00:00:00Z",
  "decisionResult": {
    "winner": "option-1",
    "confidence": 91,
    "ranking": [
      {
        "optionId": "option-1",
        "score": 0.91,
        "breakdown": {
          "expected_profit_margin": 0.25,
          "risk_exposure": 0.30,
          "title_confidence": 0.15,
          "repair_uncertainty": 0.15,
          "management_priority": 0.15
        },
        "normalizationBreakdown": {}
      },
      {
        "optionId": "option-2",
        "score": 0.84,
        "breakdown": {},
        "normalizationBreakdown": {}
      }
    ],
    "excludedOptions": [
      {
        "optionId": "option-3",
        "reasons": [
          "Title confidence is below the minimum threshold of 80."
        ]
      }
    ]
  },
  "explanation": {
      "summary": "The selected purchase case provided the strongest overall balance of margin, risk, confidence, and management priority.",
      "whyRecommended": "It met the hard title-confidence threshold and ranked highest among eligible cases.",
      "keyDrivers": [],
      "tradeoffs": [],
      "competitors": [],
      "sensitivitySummary": "Sensitivity analysis was not included in this response.",
      "scenarioSummary": "The standard scenario was selected.",
      "risks": [],
      "nextSteps": [],
      "assumptions": []
  },
  "constraintSummary": {
    "definedConstraintCount": 1,
    "activeConstraintCount": 1,
    "eligibleOptionCount": 2,
    "excludedOptionCount": 1,
    "eligibleOptions": [
      "option-1",
      "option-2"
    ],
    "excludedOptions": [
      {
        "optionId": "option-3",
        "reasons": [
          "Title confidence is below the minimum threshold of 80."
        ]
      }
    ]
  },
  "warnings": [],
  "requestContext": {
    "correlationId": "auto-auct-044-demo-001"
  }
}

WinnerThe selected option ID in decisionResult.winner.

RankingOnly eligible options ordered by deterministic score.

ExclusionsHard-constraint failures listed under constraintSummary and decisionResult.excludedOptions.

Sensitivity Analysis

runSensitivity is an optional execution flag supported by both Business Data Mode and Prepared Criteria Mode. Set it to true when the client wants recommendation-stability information in the same response. The sensitivity engine analyzes the prepared criteria produced by either input path, perturbs criterion weights by controlled factors, and reports whether the winner remains stable.

Sensitivity Result Shape

{
  "sensitivityResult": {
    "stableWinner": true,
    "winner": "option-1",
    "mostSensitiveCriterion": "risk_exposure",
    "confidence": 95,
    "criterionImpacts": {
      "risk_exposure": 0.1842
    },
    "winnerChangeCounts": {
      "risk_exposure": 0
    }
  }
}

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

Scenario Analysis

Use a published scenario only when it matches the operating context: standard, limited_budget, high_demand, risk_control. Compare the winner, ranking gap, and key trade-offs with the baseline run.

Explanation of Decision Result

Every successful response includes a provider-neutral top-level explanation object. It explains the already-finalized deterministic result and does not change the ranking.

Explanation Shape

{
  "explanation": {
      "summary": "The selected purchase case provided the strongest overall balance of margin, risk, confidence, and management priority.",
      "whyRecommended": "It met the hard title-confidence threshold and ranked highest among eligible cases.",
      "keyDrivers": [],
      "tradeoffs": [],
      "competitors": [],
      "sensitivitySummary": "Sensitivity analysis was not included in this response.",
      "scenarioSummary": "The standard 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 Decision Service to Decision Catalog.
requestContext.correlationId: Optional payload value echoed in the response and used for tracing.
configurationUsed: The authoritative effective weight strategy, ranking algorithm, profile, scenario, sensitivity setting, and source for each value.
diagnostics: Safe execution counts returned only when responseOptions.includeDiagnostics is true.

Integration Examples

These examples demonstrate the current DecisioQ flow:

Request jwtToken from https://identity.vinquery.com/connect/token.
Load AUTO-AUCT-044 metadata from https://dks.vinquery.com/decisioncatalog/decisions/AUTO-AUCT-044.
Execute a Prepared Criteria Mode 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_AUDIENCE=vinquery:api:decisioq
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-auct-044.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

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-AUCT-044` 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.
Candidate excluded	A mandatory hard constraint failed.	Review `constraintSummary.excludedOptions` for the exact candidate and reason.
HTML error response	An upstream hosted service failed before returning JSON.	Check service health and server logs for Identity, Decision Catalog, or Decision Service.

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 Decision Catalog and cache cautiously. Refresh when catalog versions change.

Request Quality

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

Constraints

Show excluded candidates separately. Do not include them in user-facing ranking tables.

Explanation

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

User Experience

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

Next Steps

Review Decision Concepts for criteria, weights, profiles, scenarios, confidence, and sensitivity; use the API Guide for transport details; and return to the examples library to compare related workflows.