Skip to main content

​
Personal Lines Payload-Only Integration

This is the recommended launch path for personal-lines integrations. You send:
  • the insured profile
  • current home / auto / umbrella coverage
  • the quoted packages you want Nexio to compare
  • inline offerings representing the quoted line items
Nexio returns:
  • ranked solutions
  • per-solution scorecards
  • line-level carrier breakdown
  • a deterministic polling contract your team can integrate cleanly
The current production path is POST /api/v1/jobs followed by GET /api/v1/jobs/{run_id} polling. Webhooks are not the baseline integration path today.

​
Integration Model

Brokerage platform
        |
        |  POST /api/v1/jobs
        |  - input
        |  - offerings
        v
   Nexio queues run
        |
        |  GET /api/v1/jobs/{run_id}
        |  until status = completed | failed
        v
 ranked solutions + scorecards

​
Top-Level Request Shape

{
  "input": {
    "coverage_types": ["home", "auto", "umbrella"],
    "address": {
      "state": "CA",
      "zip_code": "92648"
    },
    "drivers": [],
    "vehicles_detail": [],
    "current_coverage": {},
    "quotes": []
  },
  "offerings": []
}

​
What Matters Operationally

These fields drive the launch path most directly:
FieldWhy it matters
input.coverage_typesCreates the required lines Nexio must satisfy
input.address.stateDrives state-based filtering
input.vehicles or input.household.vehiclesSupports vehicle-bound filtering logic
input.premiumSets the submission-level premium context
offerings[*].categoryMust line up with requested coverage types (home, auto, umbrella)
offerings[*].provider_nameShows carrier identity in ranked output
offerings[*].attributes.line_premium_annualGives integrators a clear quoted line cost
offerings[*].attributes.package_premium_annualPreserves package context for the quote set
Everything else enriches scoring and operator review.

​
Personal Lines Input Schema

​
Required for a useful launch payload

​
input.coverage_types
array
required
Requested personal-lines coverage categories. For the current launch path this should be some combination of home, auto, and umbrella.
​
input.address.state
string
required
Two-letter state code used by deterministic filtering.
​
input.address.zip_code
string
required
ZIP code for the insured property / garaging context.
​
input.drivers
array
required
Driver profiles used to represent the actual quoting context.
​
input.vehicles_detail
array
required
Vehicle-level quoting information, including year, make, model, garaging ZIP, and primary driver.
​
input.current_coverage
object
required
Incumbent home, auto, and umbrella details. This supports comparison and review context.
​
input.quotes
array
required
The quoted packages your brokerage workflow already produced.
​
input.applicant
object
Named insured profile.
​
input.residence
object
Home underwriting context such as square footage, construction type, renovation years, and estimated replacement cost.
​
input.insurance_history
object
Continuous coverage, claim history, lapses, and non-renewals.

​
Offerings Schema

offerings is the engine-facing quoted offering set. For the payload-only launch path, this is what Nexio actually ranks.
​
offerings
array
required
Inline quoted line items to evaluate. Include one offering per quoted line.
​
offerings[*].category
string
required
Must match the requested line, such as home, auto, or umbrella.
​
offerings[*].provider_name
string
required
Carrier display name.
​
offerings[*].coverage.product_name
string
required
Quoted product or form name.
​
offerings[*].coverage.program_type
string
required
Use quoted_line for already-quoted personal-lines offerings.
​
offerings[*].attributes.quote_id
string
required
The brokerage quote identifier for that line.
​
offerings[*].attributes.line_premium_annual
number
required
Annual premium for the quoted line.
​
offerings[*].attributes.package_premium_annual
number
required
Annual premium for the package the line belongs to.

​
Example Request

This is a shortened version of the production-tested personal-lines sample:
cURL
curl -X POST https://api.usenexio.com/api/v1/jobs \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer nx_test_YOUR_KEY" \
  -d '{
    "input": {
      "applicant": {
        "first_name": "Jordan",
        "last_name": "Ramirez"
      },
      "address": {
        "state": "CA",
        "zip_code": "92648"
      },
      "coverage_types": ["home", "auto", "umbrella"],
      "drivers": [
        { "driver_id": "drv_1", "years_licensed": 24, "violations_5yr": 0 },
        { "driver_id": "drv_2", "years_licensed": 21, "violations_5yr": 1 }
      ],
      "vehicles_detail": [
        { "vehicle_id": "veh_1", "make": "Tesla", "model": "Model Y Long Range" },
        { "vehicle_id": "veh_2", "make": "BMW", "model": "X5 xDrive40i" }
      ],
      "current_coverage": {
        "home": { "carrier": "Nationwide", "annual_premium": 5480 },
        "auto": { "carrier": "Nationwide", "annual_premium": 4635 },
        "umbrella": { "carrier": "Nationwide", "annual_premium": 1125 }
      },
      "quotes": [
        { "package_id": "pkg_chubb_001", "carrier": "Chubb", "package_premium_annual": 12840 },
        { "package_id": "pkg_travelers_001", "carrier": "Travelers", "package_premium_annual": 10950 },
        { "package_id": "pkg_pure_001", "carrier": "PURE", "package_premium_annual": 13620 }
      ],
      "premium": 12840,
      "vehicles": 2
    },
    "offerings": [
      {
        "id": "quote_line_pure_home_001",
        "provider_name": "PURE",
        "category": "home",
        "coverage": {
          "product_name": "PURE Home",
          "program_type": "quoted_line",
          "market_type": "admitted",
          "appetite_strength": "strong",
          "coverage_breadth": "broad",
          "bundle_eligible": true,
          "endorsements_included": ["replacement_cost", "extended_replacement_cost"],
          "specialty_flags": ["high_value_home", "member_carrier"]
        },
        "attributes": {
          "quote_id": "qt_pure_home_001",
          "line_premium_annual": 6480,
          "package_premium_annual": 13620
        }
      }
    ]
  }'

​
Submission Response

{
  "run_id": "bcb87157-0bfc-404d-a120-7f5c9cd01037",
  "status": "queued"
}

​
Polling Response

Shortened from a real production run: 
{
  "run_id": "bcb87157-0bfc-404d-a120-7f5c9cd01037",
  "status": "completed",
  "environment": "test",
  "stage": "EVALUATE",
  "output": {
    "requirement_count": 3,
    "solutions_count": 6,
    "top_score": 3.75,
    "top_label": "recommended",
    "tolerance_bucket": "cost_sensitive",
    "diagnostic": null
  },
  "solutions": [
    {
      "rank": 1,
      "cluster_label": "recommended",
      "provider_count": 1,
      "offerings": [
        {
          "category": "auto",
          "provider_name": "PURE",
          "attributes": {
            "line_premium_annual": 5160
          }
        },
        {
          "category": "home",
          "provider_name": "PURE",
          "attributes": {
            "line_premium_annual": 6480
          }
        },
        {
          "category": "umbrella",
          "provider_name": "PURE",
          "attributes": {
            "line_premium_annual": 1980
          }
        }
      ],
      "scorecard": {
        "overall_level": 3.75,
        "coverage_completeness": { "level": 1, "label": "L1 – Comprehensive" },
        "pricing_competitiveness": { "level": 2, "label": "Within budget range" },
        "provider_quality": { "level": 1, "label": "All A+ rated" },
        "placement_likelihood": { "level": 1, "label": "L1 – Highly likely" },
        "operational_simplicity": { "level": 1, "label": "Single provider" },
        "risk_alignment": { "level": 1, "label": "L1 – Strong alignment" }
      }
    }
  ]
}

​
What Your Team Should Build

At minimum:
  1. Create and store a test API key.
  2. Submit a full request body with input and inline offerings.
  3. Persist the returned run_id.
  4. Poll GET /api/v1/jobs/{run_id} until completed or failed.
  5. Render:
    • ranked solutions
    • carrier / line breakdown
    • line premiums
    • overall score
    • per-dimension scorecard

​
Common Failure Cases

​
completed with solutions_count = 0

Usually means one of these:
  • coverage_types did not line up with offerings[*].category
  • required lines were missing from the inline offerings set
  • deterministic filtering removed all offerings for one required line

​
failed

Check error and error_details. Treat this as a terminal run state.

​
Run stays in processing

Personal-lines payload-only runs can spend meaningful time in EVALUATE while scorecards are being computed. Poll with backoff instead of hammering the endpoint.