Insurance Scenarios

Set the insurance data a sandbox verification returns. An insurance scenario pairs a login with the policies you want back, each with drivers, vehicles, and policy documents, and serves them when the user signs in to a carrier in Truv Bridge with that login. Use it when Truv’s built-in carrier logins don’t cover the case you need: a policy that expires next week, two vehicles with different coverage, a renters policy next to an auto policy, or a declarations page PDF with your own numbers. For the shared concepts, read Custom Sandbox Data first.

Create a scenario [Server-side]

Truv’s built-in carrier logins goodlogin and error.user are reserved, whatever the password, and the API refuses them with reserved_credential. Use a distinctive username prefix, such as acme..

This request creates a scenario with one active auto policy, one driver, and one vehicle:

curl --request POST \
     --url https://prod.truv.com/v1/sandbox/scenarios/ \
     --header 'X-Access-Client-Id: YOUR_TRUV_CLIENT_ID' \
     --header 'X-Access-Secret: YOUR_TRUV_SANDBOX_SECRET' \
     --header 'Content-Type: application/json' \
     --data '{
  "data_source": "insurance",
  "label": "Auto — one vehicle, active",
  "username": "acme.auto",
  "password": "s4ndb0x",
  "payload": {
    "account_email": "clark.kent@theplanet.com",
    "addresses": [
      { "address_nature": "MAILING", "full_address": "344 Clinton St, Brooklyn, NY, 11231", "number": "344", "street": "Clinton", "type": "St", "city": "Brooklyn", "state": "NY", "zip": "11231" }
    ],
    "policies": [
      {
        "name": "Personal Auto Policy",
        "policy_type": "AUTO",
        "status": "ACTIVE",
        "carrier_policy_number": "PA-4471902",
        "effective_date": "2026-02-20",
        "expiry_date": "2027-02-20",
        "renewal_date": "2027-02-20",
        "total_premium_cents": 142800,
        "deductible_cents": 50000,
        "drivers": [
          { "first_name": "Clark", "last_name": "Kent", "drivers_license_state": "NY", "date_of_birth": "1988-04-12" }
        ],
        "vehicles": [
          { "vin": "1HGCM82633A004352", "year": 2021, "make": "Honda", "model": "Accord" }
        ]
      }
    ]
  }
}'

Always send "data_source": "insurance". username and password are supported on payroll, financial accounts, and insurance, so Truv can’t infer the data source from them and refuses the request with data_source_required.

Use it in Bridge

Start a sandbox verification with product_type: insurance. In Truv Bridge, pick any insurance carrier and sign in with acme.auto / s4ndb0x. The task completes with your policies instead of Truv’s built-in test data, and the carrier on every policy is the one the user picked. Read the result from the task webhooks and the insurance report. The scenario above sets no provider_id, so every carrier works. A scenario that sets a carrier’s provider_id answers only connections through that carrier.

Matching fields

Field	Type	Description
`username`	string	The login the user types. Matched exactly.
`password`	string	The password the user types. Omit it to match on username alone.
`provider_id`	string	Narrows the match to one carrier.
`is_refresh`	boolean	`true` matches data refreshes only, `false` initial verifications only. `null` (the default) matches both.

products can only be insurance, so leave it empty.

Behavior

An insurance scenario accepts every behavior_status, and each ends the task with that status except not_supported, which ends it with unavailable. behavior_mfa is replayed at login, and a response that doesn’t match a challenge’s answer or answers ends the task with mfa_error. See Behavior for the fields.

How policies are served

The carrier comes from the connection. carrier_name and insurance_provider_name are not part of the payload; the policy carries whichever carrier the user picked. One scenario works for every carrier.
Ids are stable. Policies, drivers, vehicles, documents, and addresses get ids derived from their position in the payload, so a refresh updates the same records. A carrier_policy_number you leave out is derived from the policy’s id and stays the same across runs.
The policyholder is the first named driver. The identity on the report takes its name, and date of birth, from the first driver with both a first and last name. A driver listed on several policies is served once.
Documents must be PDFs. A policy document names a document library entry; one that names no entry, or a non-PDF one, is dropped when the task is served. date_added defaults to the policy’s effective_date.
Vehicles pass through. vehicles are free-form objects served as authored, so you can supply every field the report renders.

Payload reference

The payload object contains account_email, an addresses array, and a policies array. Every field is optional unless noted: send only what your test needs, and leave the rest out.

Top level

Field	Type	Description
`account_email`	string	Email on the carrier account.
`addresses`	array	Addresses on the account.
`policies`	array	Policies to return. An empty list serves an account with no policies, and the task ends with `no_data`.

addresses[]

Field	Type	Description
`address_nature`	string	What the address is for, e.g. `MAILING`.
`full_address`	string	The address as one line.
`number`	string	Street number.
`street`	string	Street name.
`type`	string	Street type, e.g. `St`.
`sec_unit_type`	string	e.g. `Apt`.
`sec_unit_num`	string
`city`	string
`state`	string	Two letters.
`zip`	string

policies[]

Field	Type	Description
`name`	string	Required.
`policy_type`	string	Required. `AUTO`, `HOMEOWNERS`, `RENTERS`, `CONDO`, `LANDLORD`, `FLOOD`, `UMBRELLA`, `MOTORCYCLE`, `BOAT`, `LIFE`, `TERM_LIFE`, `COMMERCIAL_AUTO`, `BUSINESS_OWNERS`, `WORKERS_COMPENSATION`, `PET`, and the rest of the carrier policy types. The API reference lists all of them.
`status`	string	`ACTIVE`, `CANCELLED`, `EXPIRED`, `UNVERIFIED`, `PENDING_ACTIVATION`, `PENDING_CANCELLATION`, `RESCINDED`.
`description`	string
`carrier_policy_number`	string	Derived from the policy when omitted.
`effective_date`	date
`expiry_date`	date
`renewal_date`	date
`canceled_date`	date
`total_premium_cents`	integer	Premium in cents.
`deductible_cents`	integer	Deductible in cents.
`drivers`	array	Drivers on the policy.
`vehicles`	array	Vehicles on the policy, as free-form objects.
`documents`	array	Policy documents.

policies[].drivers[]

Field	Type	Description
`first_name`	string
`middle_name`	string
`last_name`	string
`drivers_license`	string
`drivers_license_state`	string	Two letters.
`date_of_birth`	date

policies[].vehicles[]

Free-form objects. The insurance report renders these keys:

Field	Type	Description
`vin`	string
`year`	integer
`make`	string
`model`	string
`series`, `series2`	string	Trim lines.
`type`	string	Vehicle type.
`annual_mileage`	integer
`purchase_date`	date
`is_removed`	boolean	Whether the vehicle is excluded from the policy. Default `false`.
`lien_holder`	string
`garaging_address`, `lien_holder_address`	object	Same keys as `addresses[]`, plus `country`.
`coverages`	array	Objects of `name` (a report coverage name such as `BODILY_INJURY_LIABILITY`, `COLLISION`, or `COMPREHENSIVE`), `premium_cents`, `per_person_limit_cents`, `per_incident_limit_cents`, `deductible_cents`, `per_day_limit_cents`, `per_mile_premium_tenth_of_cents`, and `is_declined` (default `false`).
`drivers`	array	Objects of `first_name`, `last_name`, `drivers_license`, `date_of_birth_str`, `is_excluded`.

policies[].documents[]

Field	Type	Description
`title`	string	Required.
`document_type`	string	Required. `INSURANCE_APPLICATION`, `INSURANCE_BINDER`, `DECLARATIONS`, `ENDORSEMENT`, `INSURANCE_ID_CARD`, `VERIFICATION_OF_INSURANCE`.
`date_added`	date	Defaults to the policy’s `effective_date`.
`document_id`	string	Library entry served as the document’s PDF. A document without one is dropped. See Attach policy PDFs.

Examples

Each example is a request body for POST /v1/sandbox/scenarios/ and creates a new scenario. Send it with the same curl command as the first scenario.

Auto policy with two vehicles and coverages

Give each vehicle its own coverages to test how your integration renders limits and deductibles per vehicle.

{
  "data_source": "insurance",
  "label": "Auto — two vehicles with coverages",
  "username": "acme.twocars",
  "password": "s4ndb0x",
  "payload": {
    "policies": [
      {
        "name": "Personal Auto Policy",
        "policy_type": "AUTO",
        "status": "ACTIVE",
        "carrier_policy_number": "PA-4471903",
        "effective_date": "2026-02-20",
        "expiry_date": "2027-02-20",
        "total_premium_cents": 236400,
        "drivers": [
          { "first_name": "Clark", "last_name": "Kent", "drivers_license_state": "NY", "date_of_birth": "1988-04-12" },
          { "first_name": "Lois", "last_name": "Lane", "drivers_license_state": "NY", "date_of_birth": "1989-09-30" }
        ],
        "vehicles": [
          {
            "vin": "1HGCM82633A004352",
            "year": 2021,
            "make": "Honda",
            "model": "Accord",
            "annual_mileage": 12000,
            "coverages": [
              { "name": "BODILY_INJURY_LIABILITY", "premium_cents": 42000, "per_person_limit_cents": 10000000, "per_incident_limit_cents": 30000000, "is_declined": false },
              { "name": "COLLISION", "premium_cents": 61000, "deductible_cents": 50000, "is_declined": false }
            ]
          },
          {
            "vin": "5YJ3E1EA7KF317000",
            "year": 2019,
            "make": "Tesla",
            "model": "Model 3",
            "annual_mileage": 8000,
            "coverages": [
              { "name": "COLLISION", "premium_cents": 73400, "deductible_cents": 100000, "is_declined": false }
            ]
          }
        ]
      }
    ]
  }
}

Homeowners and umbrella

Return more than one policy by adding entries to policies. Up to 10 fit in one scenario.

{
  "data_source": "insurance",
  "label": "Home plus umbrella",
  "username": "acme.home",
  "password": "s4ndb0x",
  "payload": {
    "policies": [
      {
        "name": "Homeowners Policy",
        "policy_type": "HOMEOWNERS",
        "status": "ACTIVE",
        "carrier_policy_number": "HO-8812004",
        "effective_date": "2025-11-01",
        "expiry_date": "2026-11-01",
        "total_premium_cents": 189900,
        "deductible_cents": 250000,
        "drivers": [{ "first_name": "Clark", "last_name": "Kent", "date_of_birth": "1988-04-12" }]
      },
      {
        "name": "Personal Umbrella",
        "policy_type": "UMBRELLA",
        "status": "ACTIVE",
        "carrier_policy_number": "PU-2201177",
        "effective_date": "2025-11-01",
        "expiry_date": "2026-11-01",
        "total_premium_cents": 32000
      }
    ]
  }
}

Expired policy

Set status and the dates to author a lapse.

{
  "data_source": "insurance",
  "label": "Auto — expired last month",
  "username": "acme.expired",
  "password": "s4ndb0x",
  "payload": {
    "policies": [
      {
        "name": "Personal Auto Policy",
        "policy_type": "AUTO",
        "status": "EXPIRED",
        "carrier_policy_number": "PA-4471904",
        "effective_date": "2025-07-15",
        "expiry_date": "2026-07-15",
        "drivers": [{ "first_name": "Clark", "last_name": "Kent" }],
        "vehicles": [{ "vin": "1HGCM82633A004352", "year": 2021, "make": "Honda", "model": "Accord" }]
      }
    ]
  }
}

No policies

An account that signs in but holds nothing. Send an empty policies list: the login succeeds, and the task ends with no_data, as it does for a real carrier account with no policies.

{
  "data_source": "insurance",
  "label": "Account with no policies",
  "username": "acme.nopolicies",
  "password": "s4ndb0x",
  "payload": { "policies": [] }
}

A failure status needs no payload. Use it to exercise the error paths in your integration.

{
  "data_source": "insurance",
  "label": "Carrier account locked",
  "username": "acme.lockedcarrier",
  "password": "s4ndb0x",
  "behavior_status": "account_locked",
  "behavior_error_message": "Your account has been locked after too many attempts."
}

MFA challenge

behavior_mfa.challenges replays one screen per entry, in order.

{
  "data_source": "insurance",
  "label": "Carrier — delivery method then code",
  "username": "acme.carriermfa",
  "password": "s4ndb0x",
  "behavior_mfa": {
    "challenges": [
      {
        "type": "OPTIONS",
        "label": "Where should we send your code?",
        "options": [
          { "value": "sms", "label": "Text message" },
          { "value": "email", "label": "Email" }
        ],
        "answers": ["sms", "email"]
      },
      { "type": "TEXT", "label": "Enter the code", "answer": "12345" }
    ]
  },
  "payload": {
    "policies": [
      { "name": "Personal Auto Policy", "policy_type": "AUTO", "status": "ACTIVE" }
    ]
  }
}

Attach policy PDFs

A policy document is served from a document library entry. Upload the PDF once, then reference its id from the document.

curl --request POST \
     --url https://prod.truv.com/v1/sandbox/documents/ \
     --header 'X-Access-Client-Id: YOUR_TRUV_CLIENT_ID' \
     --header 'X-Access-Secret: YOUR_TRUV_SANDBOX_SECRET' \
     --form 'filename=acme-auto-declarations.pdf' \
     --form 'file=@./acme-auto-declarations.pdf'

The response is the library entry, abbreviated here; the scenario below references its id as the document’s document_id.

{
  "id": "9e7b5c3a1d2f4e6a8c0b2d4f6a8c1e35",
  "uploaded_file": { "file_id": "9e7b5c3a1d2f4e6a8c0b2d4f6a8c1e35", "filename": "acme-auto-declarations.pdf", "...": "..." },
  "documents": ["..."],
  "created_at": "2026-09-17T10:11:02.104882Z",
  "updated_at": "2026-09-17T10:11:02.104901Z"
}

Then put that id on the document. Abbreviated: the policy carries whatever other data your test needs.

{
  "data_source": "insurance",
  "label": "Auto — with declarations page",
  "username": "acme.declarations",
  "password": "s4ndb0x",
  "payload": {
    "policies": [
      {
        "name": "Personal Auto Policy",
        "policy_type": "AUTO",
        "status": "ACTIVE",
        "effective_date": "2026-02-20",
        "documents": [
          {
            "title": "Auto declarations page",
            "document_type": "DECLARATIONS",
            "date_added": "2026-02-20",
            "document_id": "9e7b5c3a1d2f4e6a8c0b2d4f6a8c1e35"
          }
        ]
      }
    ]
  }
}

Limits

These are the default limits for insurance payloads. The account-wide limits are listed on Custom Sandbox Data.

Limit	Default
Policies per scenario	10
Addresses per scenario	10
Drivers per policy	10
Vehicles per policy	10
Documents per policy	10

Next steps

Insurance report

The report your policies are rendered into

Test Credentials

Truv’s built-in logins and the universal MFA and error scenarios

Data refresh

How refreshes reach your is_refresh scenarios

Sandbox API reference

Full request and response schemas for every sandbox endpoint

Get Started

Start Building

Implementation

Bridge SDK

Testing & Launch

Dashboard & Configuration

Coverage

Insurance Scenarios

Create a scenario [Server-side]

Use it in Bridge

Matching fields

Behavior

How policies are served

Payload reference

Examples

Auto policy with two vehicles and coverages

Homeowners and umbrella

Expired policy

No policies

MFA challenge

Attach policy PDFs

Limits

Next steps

Insurance report

Test Credentials

Data refresh

Sandbox API reference

​Create a scenario [Server-side]

​Use it in Bridge

​Matching fields

​Behavior

​How policies are served

​Payload reference

​Examples

​Auto policy with two vehicles and coverages

​Homeowners and umbrella

​Expired policy

​No policies

​Failing login

​MFA challenge

​Attach policy PDFs

​Limits

​Next steps

Insurance report

Test Credentials

Data refresh

Sandbox API reference

Create a scenario [Server-side]

Use it in Bridge

Matching fields

Behavior

How policies are served

Payload reference

Examples

Auto policy with two vehicles and coverages

Homeowners and umbrella

Expired policy

No policies

Failing login

MFA challenge

Attach policy PDFs

Limits

Next steps