DecisioQ Auto Insurance Developer Integration Manual

How software developers should incorporate DecisioQ into underwriting, rating, claims, fraud, repair, retention, agent, and reinsurance platforms

Version 1.0 | Generated June 25, 2026

Contents

1. Executive summary

2. Auto Insurance integration architecture

3. Supported Auto Insurance decision templates

4. Endpoint workflow and security model

5. Data mapping standards

6. Implementation recipes by workflow

7. Payload examples

8. User interface and audit integration

9. Production readiness checklist

10. Appendix: template catalog and field dictionary

1. Executive summary

DecisioQ is a decision-analysis API that ranks alternatives using weighted criteria, constraints, and algorithms such as TOPSIS or WSM. In an Auto Insurance system, DecisioQ should be used when the application needs an explainable recommendation among competing policy, claim, pricing, repair, retention, or vendor options.

The integration pattern is consistent across insurance workflows: collect candidate options from policy, claims, telematics, CRM, and finance systems; normalize each candidate into DecisioQ criteria; call the selected Auto Insurance template; persist the recommendation and explanation; then present the result to adjusters, underwriters, pricing analysts, agents, or operations staff.

2. Auto Insurance integration architecture

Canonical request flow

1. Authenticate server-side using /api/v1/token and store credentials only in a vault or secret manager.
2. Load available templates through /api/v1/templates and cache the Auto Insurance catalog.
3. Select the template that matches the workflow, such as Policy Underwriting, Claims Approval, Fraud Detection, or Repair Shop Selection.
4. Build a DecisionRequest where each option has an optionId, name, and scores for every criterion required by the template.
5. Call /api/v1/decide. For high-impact decisions, also call sensitivity or scenario endpoints before allowing automation.
6. Persist request, response, excluded options, warnings, confidence, explanation, selected action, final human decision, and downstream result.

3. Supported Auto Insurance decision templates

4. Endpoint workflow and security model

Authentication example

POST /api/v1/token
Content-Type: application/json

{
  "clientId": "auto-insurance-platform-service",
  "clientSecret": "<stored in vault or secret manager>"
}

Use the returned bearer token on subsequent API calls:
Authorization: Bearer <accessToken>

5. Data mapping standards

DecisioQ recommendations are only as reliable as the input score definitions. Define score transformations centrally and test them against historical outcomes. Every criterion should have a documented unit, scale, direction, data source, freshness rule, missing-data rule, and audit owner.

6. Implementation recipes by workflow

Recipe A: Policy Underwriting support

1. Trigger DecisioQ when a quote or renewal enters an underwriting referral state.
2. Create one option per underwriting action, such as Approve Standard, Approve with Exclusions, Request Information, Manual Review, or Decline Referral.
3. Map applicant, driver, vehicle, prior claims, and fraud signals into CreditScore, DrivingHistory, VehicleRisk, ClaimsHistory, and FraudRisk.
4. Apply hard constraints outside DecisioQ for statutory eligibility, product availability, sanctions, licensing, or mandatory decline rules.
5. Show the recommended action as advisory, with key drivers and sensitivity for underwriter review.

Recipe B: Premium Pricing optimization

1. Create one option per pricing scenario, package, deductible, discount configuration, or renewal offer.
2. Calculate ExpectedProfit, CustomerRetentionProbability, RiskExposure, CompetitivePosition, and ClaimsCost for each option.
3. Use scenario analysis to compare base price, market-aligned price, retention price, and margin-protecting price.
4. Do not bypass filed-rate, rating-plan, or jurisdictional controls; DecisioQ should rank valid options, not invent illegal rates.
5. Persist the selected price option and later compare retention, claims loss, and profitability against the recommendation.

Recipe C: Claims approval and triage

1. Trigger DecisioQ after coverage, policy-active, loss-date, and required-document checks are complete.
2. Create options such as Approve, Partial Approve, Request More Information, Supervisor Review, or SIU Review.
3. Map ClaimValidity, CustomerValue, RepairCost, FraudRisk, and PolicyActive to the request.
4. Use constraints so inactive-policy claims are excluded from approval recommendations.
5. For straight-through processing, require high confidence, low fraud risk, stable sensitivity, and no missing critical fields.

Recipe D: Fraud Detection / SIU prioritization

1. Create one option per claim or party that could enter the SIU queue.
2. Use FraudScore, ClaimComplexity, HistoricalPatternMatch, and CustomerRiskScore to rank investigation priority.
3. Do not treat DecisioQ as the fraud model itself; it is the decision layer that combines fraud model outputs with operational priorities.
4. Display ranked cases with explanation, but keep sensitive fraud indicators limited to authorized SIU users.
5. Store analyst disposition so the model and criteria can be calibrated against confirmed outcomes.

Recipe E: Repair Shop Selection

1. Create one option per eligible repair provider in the customer geography.
2. Map RepairQuality, RepairCost, TurnaroundTime, CustomerSatisfaction, and WarrantySupport.
3. Filter out shops that cannot service the vehicle type, location, certification, or capacity need before calling DecisioQ.
4. Present the recommendation to the adjuster or customer along with network-status disclosures required by your business.
5. Capture shop accepted, customer override, supplement rate, cycle time, and post-repair satisfaction for feedback analysis.

Recipe F: Total Loss Determination support

1. Use DecisioQ to compare repair, total-loss, salvage, and supervisor-review paths after estimating ACV, repair cost, and salvage value.
2. Map RepairCostRatio, VehicleValue, SalvageValue, and SafetyRisk.
3. Keep jurisdictional total-loss thresholds and legal requirements outside DecisioQ as hard business rules.
4. Use the recommendation as decision support for adjusters, not as an automatic legal determination.
5. Retain request, response, valuation inputs, and adjuster final decision in the claim file.

7. Payload examples

Policy Underwriting request

{
  "template": "Policy Underwriting",
  "algorithm": "TOPSIS",
  "runSensitivity": true,
  "validationMode": "Strict",
  "options": [
    {
      "optionId": "UW-ACTION-APPROVE-STANDARD",
      "name": "Approve standard policy",
      "scores": {
        "CreditScore": 720,
        "DrivingHistory": 86,
        "VehicleRisk": 42,
        "ClaimsHistory": 1,
        "FraudRisk": 12
      }
    },
    {
      "optionId": "UW-ACTION-APPROVE-RESTRICTED",
      "name": "Approve with coverage restrictions",
      "scores": {
        "CreditScore": 720,
        "DrivingHistory": 78,
        "VehicleRisk": 36,
        "ClaimsHistory": 1,
        "FraudRisk": 10
      }
    },
    {
      "optionId": "UW-ACTION-MANUAL-REVIEW",
      "name": "Refer to senior underwriter",
      "scores": {
        "CreditScore": 720,
        "DrivingHistory": 70,
        "VehicleRisk": 30,
        "ClaimsHistory": 2,
        "FraudRisk": 20
      }
    }
  ],
  "context": {
    "correlationId": "optional",
    "attributes": {}
  }
}

Claims Approval request

{
  "template": "Claims Approval",
  "algorithm": "TOPSIS",
  "runSensitivity": true,
  "options": [
    {
      "optionId": "CLAIM-84291-APPROVE",
      "name": "Approve claim payment",
      "scores": {
        "ClaimValidity": 91,
        "CustomerValue": 78,
        "RepairCost": 3200,
        "FraudRisk": 9,
        "PolicyActive": 1
      }
    },
    {
      "optionId": "CLAIM-84291-DOCS",
      "name": "Request additional documentation",
      "scores": {
        "ClaimValidity": 74,
        "CustomerValue": 78,
        "RepairCost": 3200,
        "FraudRisk": 18,
        "PolicyActive": 1
      }
    },
    {
      "optionId": "CLAIM-84291-SIU",
      "name": "Route to SIU review",
      "scores": {
        "ClaimValidity": 55,
        "CustomerValue": 78,
        "RepairCost": 3200,
        "FraudRisk": 72,
        "PolicyActive": 1
      }
    }
  ],
  "context": {
    "correlationId": "optional",
    "attributes": {}
  }
}

Repair Shop Selection request

{
  "template": "Repair Shop Selection",
  "algorithm": "TOPSIS",
  "options": [
    {
      "optionId": "SHOP-1042",
      "name": "Northside Certified Collision",
      "scores": {
        "RepairQuality": 92,
        "RepairCost": 4100,
        "TurnaroundTime": 8,
        "CustomerSatisfaction": 88,
        "WarrantySupport": 95
      }
    },
    {
      "optionId": "SHOP-2215",
      "name": "Metro Auto Body",
      "scores": {
        "RepairQuality": 87,
        "RepairCost": 3750,
        "TurnaroundTime": 11,
        "CustomerSatisfaction": 82,
        "WarrantySupport": 90
      }
    },
    {
      "optionId": "SHOP-3189",
      "name": "Rapid Paint and Body",
      "scores": {
        "RepairQuality": 84,
        "RepairCost": 3500,
        "TurnaroundTime": 6,
        "CustomerSatisfaction": 79,
        "WarrantySupport": 80
      }
    }
  ],
  "context": {
    "correlationId": "optional",
    "attributes": {}
  }
}

Expected response handling pattern

// Pseudocode for backend handling
var response = await decisioQ.DecideAsync(request);

await auditStore.SaveAsync(new DecisionAuditRecord {
    Workflow = "ClaimsApproval",
    BusinessKey = claimId,
    RequestJson = Serialize(request),
    ResponseJson = Serialize(response),
    RecommendedOptionId = response.RecommendedOptionId,
    Confidence = response.ConfidenceScore,
    CreatedBy = currentUserOrService,
    CreatedUtc = clock.UtcNow
});

ui.ShowRecommendation(
    recommended: response.RecommendedOption,
    rankedOptions: response.Results,
    excludedOptions: response.ExcludedOptions,
    explanation: response.Explanation,
    warnings: response.Warnings);

8. User interface and audit integration

Audit table design

9. Production readiness checklist

• Each template criterion has an owner, source system, unit, scale, direction, and missing-data rule.
• Hard regulatory, legal, licensing, eligibility, and jurisdictional rules remain outside DecisioQ as deterministic controls.
• DecisioQ credentials are stored in a secret manager and never exposed to clients.
• Every call includes correlation IDs and is logged without leaking unnecessary PII.
• Requests and responses are retained according to policy and privacy requirements.
• Sensitivity analysis is required for high-impact automated actions.
• Users can see explanations and record override reasons.
• Fallback behavior exists for DecisioQ outage, timeout, validation error, and missing data.
• Monitoring tracks latency, error rate, recommendation distribution, override rate, and outcome performance.
• Model, score, and criteria changes are versioned and regression-tested against historical cases.

Failure-mode handling

10. Appendix: template catalog and field dictionary

Developer handoff summary

A successful Auto Insurance integration treats DecisioQ as an explainable decision orchestration layer, not as the sole source of truth for law, regulation, rating-plan compliance, or fraud modelling. The best integrations feed DecisioQ with high-quality normalized scores, constrain the candidate set with deterministic business rules, preserve the complete audit trail, and present recommendations in the existing underwriter, adjuster, pricing, and operations workflows.