You are viewing legacy endpoint documentation. See the
Modern docs for engine-scoped endpoints.
Runs
A run is an async job submitted to POST /api/v1/jobs. Each run gets a run_id and is
processed through the pipeline. Poll GET /api/v1/jobs/{run_id} for results.
input is the insured’s profile: applicant details, address, drivers, vehicles, residence,
current home/auto/umbrella policies, insurance history, and the coverage_types to evaluate.
Offerings
offerings is the array of carrier quotes Nexio evaluates. Each offering represents one carrier’s
quote for one coverage line (e.g., one carrier’s home quote, another carrier’s auto quote). If you have 3
carriers quoting home, auto, and umbrella, that’s 9 offerings.
Solutions
Nexio assembles offerings into ranked solutions — complete placement packages that cover all
requested lines. Solutions may be single-carrier bundles or mixed-carrier packages, whichever
combinations score best.
Each solution has a rank (1 = best) and a cluster_label that categorizes it:
recommended, best_value, best_coverage, or simplest.
Routing modes
Control which pipeline runs via request_config flags in input:
| Flag | Default | Effect |
|---|
coverage_analysis | false | Gap analysis pipeline. Requires current_portfolio. |
quote_matching | implicit | Quote ranking pipeline. Requires offerings. |
true for dual-mode runs. Gap-only requires coverage_analysis: true and
quote_matching: false together.
When both flags are omitted, implicit routing applies: submissions with
current_portfolio default to gap analysis; all other submissions default to quote matching.
Set request_config flags explicitly in production. Implicit detection is a convenience fallback.
Solutions
A solution is a ranked placement package. Each includes:
offerings — the quoted lines in the packageprovider_count — 1 = single-carrier, 2+ = mixedest_cost_low / est_cost_high — annual cost rangescorecard — six-dimension evaluationrank and cluster_label
Carrier identity is on solutions[*].offerings[*].provider_name, not on the solution root.
Ranking strategy
appetite_bucket controls how Nexio weights the scorecard dimensions when ranking solutions.
Set it in input to express the customer’s priority:
appetite_bucket | Emphasis |
|---|
coverage_first | Broadest coverage, strongest forms |
cost_sensitive | Lowest cost within quality bounds |
simplicity | Fewest carriers, easiest to bind |
balanced | Even weighting across all dimensions |
output.top_label and on each solution as
cluster_label. Labels like recommended, best_value, best_coverage, and simplest
reflect where each solution excels — they’re the output side of the ranking strategy.
Scorecards
Six dimensions, each rated L1–L4 (lower is better):
coverage_completenesspricing_competitivenessprovider_qualityplacement_likelihoodoperational_simplicityrisk_alignment
The package score is scorecard.overall_level — a weighted average based on the ranking strategy.
The pipeline
Quote matching
| Stage | What happens |
|---|
| INTAKE | Parse submission, infer requirements |
| FILTER | Remove offerings that fail hard constraints (state, coverage line, vehicle count) |
| MATCH | Match remaining offerings to requirements by category |
| ASSEMBLE | Build candidate solutions with bundle discounts |
| EVALUATE | Score across six dimensions, rank, and label |
Coverage analysis
| Step | What happens |
|---|
| Infer Requirements | Generate coverage needs from profile and assets |
| Punch Card Check | Compare against current portfolio (MET / UNMET) |
| Deterministic Checks | Rule-based gap detection |
| LLM Adequacy | AI analysis of coverage adequacy |
| Merge & Dedupe | Combine gaps, sort by severity (HIGH → MEDIUM → LOW) |
Rate limits
Rate limits are enforced on the public API. 429 Too Many Requests includes a Retry-After header.
Contact support@usenexio.com for higher limits.
