Decision Concepts | DecisioQ Developer Center

Introduction

DecisioQ is a catalog-driven decision platform. A client chooses a decision, provides candidate cases, selects optional profiles and scenarios, and receives a deterministic recommendation with ranking, scores, validation feedback, and a business-friendly explanation.

Client Application Authentication Decision Catalog Discovery Industry Profile Mapping Scenario and Profile Selection Algorithmic Decision Execution Sensitivity Analysis Recommendation and Explanation Client Application Review

Start with the business question, not the API call. The API is the transport; the decision model is what determines whether the recommendation is useful.

Decisions

A Decision is a reusable model for answering a specific business question, such as which auction vehicle to purchase, which repair order to prioritize, or which towing request should be dispatched first.

Business Purpose

Make a repeatable recommendation using criteria the business trusts, rather than relying on ad hoc judgment.

Technical Purpose

Provide a stable decisionId, metadata, criteria, profiles, scenarios, and execution rules that clients can discover from the catalog.

Concept	Example	Why It Matters
Decision ID	`AUTO-AUCT-044`	Used as the stable API identifier.
Decision Name	Auction purchase recommendation	Displayed to business users.
Decision Metadata	Purpose, business question, expected outcome	Explains when and why to use the decision.

Common mistake: hard-coding decision inputs instead of loading the decision definition from the catalog.

Criteria

Criteria are the measurable factors used to score each candidate case. Examples include title confidence, estimated margin, repair complexity, customer impact, safety risk, and parts availability.

Weights

Weights indicate relative importance. A high weight on margin means profitability has more influence on the final ranking.

Normalization

DecisioQ converts different units and ranges into comparable scores so that mileage, percentage, cost, and risk can be evaluated together.

Direction

Some criteria are better when higher, such as confidence. Others are better when lower, such as risk or cost.

Validation

Required values and bounded ranges prevent invalid inputs such as a percentage of 740.

A criterion should clearly state what is being measured, the expected unit, whether higher or lower values are preferred, and whether the value is required.

Best practice: show criterion names and overview text to users, but keep criterion IDs in the request payload for stable integration.

Measurement Units and Localization

Measurement-unit normalization is different from criterion scoring normalization. Unit normalization converts the same real-world value into a canonical measurement before the decision is scored. Criterion scoring normalization then compares all criteria fairly inside the algorithm.

Stable identifiers

Decision IDs, criterion IDs, route names, and JSON fields stay in stable American-English technical form.

Localized presentation

Labels and guidance can be displayed for Canadian, US, or future regional users without changing API contracts.

Canonical evaluation

Miles, pounds, Fahrenheit, psi, and other supported US customary values are normalized before deterministic scoring.

Traceability

Source value, source unit, canonical value, canonical unit, and conversion metadata can be kept for diagnostics and audit.

Example: 52,350 miles and 84,249 kilometres describe the same mileage. After normalization, both should lead to the same decision result when all other inputs are equivalent.

Options and Candidate Cases

An Option is a candidate that can be recommended. In the user interface these are often called Candidate Cases. For Auto Auctions, each option may be a vehicle lot. For Auto Towing, each option may be a tow request.

Candidate cases are collected Criteria values are validated Each candidate is scored Candidates are ranked The best-supported recommendation is returned

When not to use: if there is only one possible candidate and no meaningful trade-off, a rule or validation endpoint may be more appropriate than a ranked decision.

Profiles

A Profile adjusts the decision model for a business posture. The same candidate data can produce different recommendations under Conservative, Balanced, or Aggressive profiles because the criterion weights change.

Profile	Typical Emphasis	Automotive Example
Conservative	Risk reduction, confidence, predictable outcomes	A used car dealer avoids auction lots with uncertain title or inspection risk.
Balanced	Moderate mix of profit, risk, and operational fit	An auction buyer balances margin, condition, demand, and title confidence.
Aggressive	Upside, speed, growth, margin opportunity	A wholesaler accepts more uncertainty for high resale margin.

A Balanced profile might weigh profit, risk, condition, and demand evenly. A Conservative profile might give more weight to title confidence, safety, and inspection certainty.

Use Profiles when: different teams, customers, or operating modes use the same decision but value trade-offs differently.

Do not use Profiles when: the business question is actually different. Create a separate Decision instead.

Scenarios

A Scenario represents the operating context for a decision. It does not replace the decision; it changes how the same decision should behave under business conditions such as high demand, low inventory, seasonal pressure, or emergency operations.

Production Scenario

The standard operating configuration used by live systems.

What-if Scenario

A test context used to compare recommendations without changing the production default.

Seasonal Scenario

Weights and assumptions tuned for a period such as winter tire demand or holiday rental volume.

Emergency Scenario

Context where urgency, safety, or service-level impact may dominate normal economics.

Best practice: use Scenarios for context and Profiles for preference. A towing dispatcher may use an emergency Scenario with a conservative Profile.

Sensitivity Analysis

Sensitivity Analysis tests how stable the recommendation is when weights or model assumptions vary. It helps decision makers understand whether a result is robust or fragile.

Stable Decision

The same candidate remains recommended after reasonable weight changes. This increases confidence.

Sensitive Decision

A small change causes a different winner. The business may need more data or manager review.

Original recommendation Weight changes are simulated Ranking stability is measured Decision risk is reported

When Sensitivity Analysis is enabled, users should expect an added stability signal that explains whether the recommendation remains strong under reasonable model variation.

When to use: high-value purchases, borderline rankings, audit-sensitive decisions, or decisions where a small data error could change the outcome.

When not to use: very high-throughput flows where latency matters more and the recommendation is already operationally low risk.

Industry Profiles and Data Preparation

An Industry Profile describes how raw business data is prepared for a selected decision. It connects client system fields to the catalog-defined criterion IDs used by DecisioQ without exposing internal implementation details to business users.

Business Field	Canonical Criterion	Validation or Transformation
`titleConfidence`	`AUTO-AUCT-TITLE-CONFIDENCE`	Validate as percentage 0 to 100.
`estimatedRepairCost`	`AUTO-AUCT-REPAIR-COST`	Normalize cost where lower is better.
`marketDemandScore`	`AUTO-AUCT-MARKET-DEMAND`	Validate as score 0 to 100.
`odometer.value` plus `odometer.unit`	`vehicle_mileage`	Convert supported `mi` or `km` inputs to the canonical metric value.

Common mistake: treating data preparation as the same thing as business preference. Data preparation gets values into the expected decision shape; Profiles express business preference through weights, defaults, and context.

Algorithms

Algorithms define how criteria are combined into a recommendation. DecisioQ keeps deterministic scoring authoritative so that identical inputs produce consistent, explainable results.

Algorithm Type	Strengths	Best Fit	Watch For
Weighted scoring	Transparent, fast, easy to explain	Most ranked business decisions	Requires carefully maintained weights.
Constraint-aware ranking	Can remove unacceptable candidates	Safety, compliance, or operational eligibility	Hard constraints should be visible to users.
Sensitivity-enhanced scoring	Shows stability and risk	High-value or audit-sensitive recommendations	May add processing time.

Best practice: expose the algorithm choice only when integrators genuinely need it. Most business users should choose a Decision, Profile, and Scenario instead.

Decision Results

A Decision Result contains the recommendation, ranking, scores, confidence, validation feedback, warnings, and optional sensitivity output. Consumers should display the result in business language while retaining technical details for developers and support teams.

A useful result view should show the recommended option, why it ranked first, how close the other options were, and whether any warnings or validation messages affect interpretation.

Interpretation guidance: the top-ranked candidate is recommended because it best satisfies the configured criteria, profile, scenario, and validation rules.

Explanation of Decision Results

The deterministic result is authoritative. The explanation translates the result into business language so users can understand why a candidate was recommended. The explanation must not change the scores or ranking.

Think of the explanation as an interpreter, not the decision maker. It explains the deterministic recommendation and can include assumptions, limitations, warnings, and decision context.

Good explanation: "Lot 2 is recommended because it combines high title confidence with stronger market demand and acceptable repair cost."

Poor explanation: "The algorithm chose Lot 2." That hides the deterministic model and overstates the role of generated text.

Complete Walkthrough: Auto Auction Purchase

Authenticate with https://identity.vinquery.com/connect/token and include the required token audience.
Retrieve the catalog from https://dks.vinquery.com/decisioncatalog.
Select the Auto Auctions sector and a purchase decision.
Load the decision definition, criteria, profiles, scenarios, and example candidate cases.
Prepare two or more vehicle lots as candidate cases.
Choose a Profile such as Balanced and a Scenario such as Standard.
Enable Sensitivity Analysis for high-value purchases.
Execute Prepared Decision Input through https://dde.vinquery.com/api/v1/decide. Use https://dde.vinquery.com/api/v1/decide only for business-data integrations that submit a businessData object.
Display the recommendation, ranking, explanation, and any validation messages.

Use this walkthrough to understand the business sequence. For executable API calls and language-specific examples, use the Developer Center.

Best Practices

Load decision definitions from the catalog instead of hard-coding criteria.
Use Profiles for business preference and Scenarios for operating context.
Validate candidate cases before execution and show field-level validation feedback.
Display hard constraint outcomes clearly; excluded options do not participate in ranking.
Enable Sensitivity Analysis for high-value, borderline, or audit-sensitive decisions.
Keep technical diagnostics available to integrators but collapsed for business users.
Log correlation IDs, decision IDs, and validation outcomes for support and audit.
Version integration changes and test them against realistic automotive examples.

Troubleshooting

Issue	Likely Cause	Recommended Action
Invalid or expired JWT	Token missing, expired, or issued for the wrong audience.	Request a fresh token from identity.vinquery.com and resend the request.
Unknown Decision	The decisionId is not in the active catalog.	Reload the catalog and use a listed decisionId.
Profile not found	The selected profile does not belong to the decision.	Populate the Profile dropdown from the selected decision definition.
Scenario not found	The scenario is not available for this decision.	Use the decision's scenario list or omit scenarioId for the default.
Validation failure	Missing candidate data or out-of-range values.	Use criterion metadata and display validation feedback next to fields.

FAQ

When should I use Profiles? Use them when the same decision needs different business priorities, such as Conservative, Balanced, or Aggressive.

When should I use Scenarios? Use them when the operating context changes, such as high demand, low inventory, emergency dispatch, or seasonal pressure.

Do Profiles override weights? Profiles can adjust the active weighting strategy for a decision, but they should remain within the decision's intended business purpose.

Should Sensitivity Analysis always be enabled? No. Use it where decision stability matters enough to justify extra analysis.

What is the difference between Industry Profiles and Profiles? Industry Profiles map business data to criteria. Profiles change decision preference and weighting.

How does the explanation relate to the deterministic result? The explanation interprets the result. It does not overwrite the recommendation, ranking, or score.