Auto Insurance Integration Manual

Developer guidance for integrating DecisioQ Auto Insurance decisions with claims, underwriting, repair, fraud, mobility, compliance, analytics, and customer service platforms.
1Auto Insurance Overview

The Auto Insurance sector in the DecisioQ Decision Catalog is identified by AUTO-INS. It supports decision support for claims, underwriting, repair approvals, risk scoring, compliance, analytics, and customer service operations across automotive insurance workflows.

DecisioQ integrations should load sector, category, decision, Decision Preparation Model, and scenario metadata from the Decision Catalog. Do not hard-code legacy template names or old decision payload structures.

Recommended first deployment: start with a high-volume advisory workflow such as claim intake prioritization, adjuster assignment, rental extension approval, or coverage validation. Compare DecisioQ recommendations against existing claim handling decisions before automating downstream actions.

2Catalog Discovery Flow

Auto Insurance client applications should use the same discovery flow as the Business Decision Studio:

  1. Load GET /decisioncatalog through the approved server-side Decision Catalog gateway.
  2. Populate Sector from catalog.sectors[] and select AUTO-INS for Auto Insurance.
  3. Populate Category from selectedSector.categories[]. Example categories include Claims Intake & Triage, Coverage & Liability, Customer Mobility, Compliance & Regulatory, and Analytics & Reporting.
  4. Populate Decision from selectedCategory.decisions[] when available, or call /decisioncatalog/sectors/{sectorCode}/categories/{categoryCode}/decisions.
  5. Display Decision Name only in the dropdown while keeping decisionId as the option value.
  6. Load full decision detail from /decisioncatalog/decisions/{decisionId} before rendering Guided Data Collection.

Decision detail is the source of truth for criterion names, data guidance, scale, direction, profile options, scenarios, and overview metadata.

For regional deployments, keep DecisioQ technical identifiers stable and localize only user-facing labels and guidance. Unless the selected endpoint and decision schema explicitly support unit-qualified input, convert mileage, distance, pressure, temperature, mass, volume, speed, fuel consumption, and other measurements to the required canonical units before submission. Do not infer units or currency from locale.

3Auto Insurance Use Cases
Use CasePrimary UsersTypical Inputs
Claim intake and triageClaims operations, adjusters, service teamsClaim severity, coverage confidence, customer impact, SLA urgency, complexity, fraud risk.
Adjuster and appraisal assignmentClaims managers, appraisal coordinatorsWorkload, expertise, location, claim severity, vehicle type, response deadline.
Coverage and liability reviewAdjusters, coverage specialists, legal reviewersPolicy status, deductible terms, loss facts, evidence quality, liability indicators, injury exposure.
Rental and mobility approvalClaims teams, mobility teams, partner repair networksCoverage entitlement, repair duration, replacement need, cost exposure, customer impact.
Compliance and regulatory prioritizationCompliance teams, claims leadershipFiling deadlines, complaint severity, jurisdiction, exposure, exception risk, audit history.
Analytics and portfolio prioritizationAnalytics leaders, product managers, operations executivesBusiness value, data readiness, adoption effort, operational risk, monitoring value.
Special investigation triageSIU, claims quality, fraud analystsAnomaly signals, prior history, evidence quality, financial exposure, repair pattern, policy timing.
4Business Data Mapping

Auto Insurance integrations should map operational claim, policy, customer, vehicle, repair, and service data into decision-specific Business Data. The selected decision detail defines which criteria are required and how each value should be measured.

Business Data SourceCommon UseIntegration Notes
Claim, policy, vehicle, customer, or repair order IDoptionId and audit correlation.Keep stable IDs. Business users may edit option IDs in demos, but production systems should preserve source-system identifiers.
Policy coverage and deductible termsCoverage validation, rental approval, liability and reserve decisions.Use normalized values and ensure policy effective dates match the loss date.
Claim severity and estimated lossIntake prioritization, reserve review, appraisal routing.Keep amount units consistent and avoid mixing estimated and approved amounts.
Evidence, police report, witness, and liability indicatorsLiability position and coverage exception review.Distinguish missing evidence from evidence that is negative or conflicting.
Repair duration and rental needRental approval, extension, and mobility decisions.Use current repair estimate dates and update the decision if repair status changes materially.
Adjuster capacity, skill, territory, and workloadAssignment and routing decisions.Refresh capacity data before execution to avoid stale workload recommendations.
Customer impact and SLA urgencyPriority and service escalation decisions.Separate business urgency from customer sentiment when the decision model expects distinct criteria.

Do not invent criterion IDs. Use the canonical criteria returned by /decisioncatalog/decisions/{decisionId}, including criterion overview metadata, unit, direction, scale, and data guidance.

5Preview and Execute Workflow

Production integrations should keep credentials and bearer tokens on trusted servers or server-side gateways. Browser pages should use same-origin proxy handlers or their own backend service.

  1. Trusted backend obtains a JWT token from identity.vinquery.com.
  2. Application loads catalog and decision detail metadata.
  3. User or system prepares Business Data for candidate claims, policies, repair cases, or operational actions.
  4. Call POST /api/v1/validate to validate and prepare the decision input before execution.
  5. Call POST /api/v1/decide to return the authoritative Decision Result.
  6. Display the recommendation, ranked alternatives, warnings, assumptions, and Explanation of Decision Result.
  7. Keep execution trace and diagnostics available to integrators, but collapsed or hidden by default for business users.

Use /api/v1/decide for both Prepared Criteria Mode and business-data integrations that submit a businessData object. New public onboarding should prefer Preview Decision and Execute Decision terminology.

6Example Request Shape

The exact fields depend on the selected Auto Insurance decision. The example below shows the integration style rather than a guaranteed schema for every decision.

{
  "decisionId": "AUTO-INS-011",
  "decisionPreparationModelId": "AUTO-INS-PROFILE-STANDARD",
  "scenarioId": "AUTO-INS-SCENARIO-CLAIMS-TRIAGE",
  "businessData": {
    "candidates": [
      {
        "optionId": "CLAIM-78421",
        "name": "2019 Honda Civic rear-end collision",
        "values": {
          "claimSeverityScore": 82,
          "coverageConfidenceScore": 94,
          "customerImpactScore": 76,
          "slaUrgencyScore": 88,
          "fraudRiskScore": 18,
          "estimatedLossAmount": 7400
        }
      },
      {
        "optionId": "CLAIM-78433",
        "name": "2022 Ford F-150 hail damage",
        "values": {
          "claimSeverityScore": 61,
          "coverageConfidenceScore": 89,
          "customerImpactScore": 58,
          "slaUrgencyScore": 64,
          "fraudRiskScore": 12,
          "estimatedLossAmount": 5200
        }
      }
    ]
  },
  "requestContext": {
    "correlationId": "claims-workbench-20260717-001"
  }
}
7Backend Call Pattern

This pattern belongs in a trusted backend, not directly in browser JavaScript.

async function executeAutoInsuranceDecision(decisionInput, jwtToken) {
  const response = await fetch(`${process.env.DECISIOQ_BASE_URL}/api/v1/decide`, {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${jwtToken}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify(decisionInput)
  });

  if (!response.ok) {
    throw new Error(`DecisioQ execution failed: ${response.status} ${await response.text()}`);
  }

  return await response.json();
}
8UI and Workflow Integration
UI ElementRecommended DisplayWhy It Matters
Choose a DecisionSector, Category, Decision, Profile, and Scenario selectors populated from catalog metadata.Users see business names while integrators retain stable IDs.
Selection OverviewSector, category, and decision overviews in one collapsible panel.Claims and operations users understand the decision before entering data.
Guided Data CollectionCriterion label, field, data type indicator, summary, and expandable "More about this criterion".Improves claim data quality and reduces inconsistent intake.
Candidate CasesTwo fields per row where practical, editable option ID, and visible units or data type indicators.Claims teams can compare cases quickly without feeling like they are using an API tool.
Decision ResultRecommendation, ranking, confidence, and key drivers.Users need the answer and the reason.
Outcome Follow-upAccepted, Rejected, or Overridden; selected option and override reason when applicable.Connects the recommendation to the action actually taken.
Realized ValueOutcome status plus a consistently defined financial or operational metric.Measures adoption and business value without changing deterministic scoring.
ExplanationBusiness-friendly explanation without AI provider branding.Supports trust while keeping the UI provider-neutral.
DiagnosticsCollapsed technical panel for status, timings, warnings, and errors.Useful for integrators without distracting business users.
9Production Readiness
  • Store identity credentials, Decision API base URL, and proxy configuration in trusted server configuration or a secret manager.
  • Do not expose bearer tokens or integration credentials in browser code.
  • Use catalog metadata rather than hard-coded categories, decisions, criteria, profiles, or scenarios.
  • Validate Business Data before execution and show user-friendly validation messages.
  • Persist correlation ID, claim ID, policy ID, decision ID, profile ID, scenario ID, selected option, score, and explanation for audit.
  • Retain the successful decision response requestId with the host business transaction, then call POST /api/v1/decision-outcomes when the action and realized result are known.
  • Require an overrideReason for overridden recommendations; never infer acceptance merely because a result was displayed.
  • Monitor GET /api/v1/decision-outcomes/summary for acceptance rate, override rate, and realized-value aggregates. Treat outcome feedback as reporting evidence, not automatic model training.
  • Redact claim notes, customer identifiers, policy details, medical details, and payment data in logs and diagnostics.
  • Monitor catalog load failures, token refresh failures, API latency, validation failures, account verification failures, and unusual exclusion rates.
  • Define fallback behavior so claims workflows remain usable when DecisioQ is unavailable.
  • Review Decision Preparation Models and scenario assumptions with claims, compliance, and product owners when policy rules or regulatory requirements change.
10Troubleshooting
SymptomLikely CauseFix
Category list is empty.The catalog response does not include categories for the selected sector, or the client is reading an old category layer.Use selectedSector.categories[] from /decisioncatalog.
Decision dropdown shows IDs only.The client did not load decision detail or category decision names.Display Decision Name as the label and keep decision ID as the option value.
Criterion guidance is missing.Decision detail lacks criterion overview metadata or the page is not rendering it.Read criterion overview from /decisioncatalog/decisions/{decisionId} and show available summaries.
Secure session could not be refreshed.Token proxy or identity service configuration failed.Check server-side identity configuration and proxy logs; do not request tokens directly from browser JavaScript.
Decision execution failed.Decision API unavailable, invalid Business Data, authorization failure, or account verification issue.Check response envelope, HTTP status, correlation ID, Decision API health, and server logs.
Unexpected recommendation.Scale, units, direction, or values do not match catalog criterion guidance.Compare Business Data fields against criterion overview and validation metadata.
Recommendation conflicts with policy rules.The selected scenario or Decision Preparation Model may not match the product, jurisdiction, or claim type.Review scenario assumptions and profile metadata before execution.