> ## Documentation Index
> Fetch the complete documentation index at: https://docs.truv.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Insurance Scenarios

> Pair a carrier login with the policies, drivers, vehicles, and documents Truv should return for it

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](https://docs.truv.com/developers/testing/custom-sandbox-data.md) first.

***

## Create a scenario \[Server-side]

> [!WARNING]
>
> 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:

```bash theme={null}
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" }
        ]
      }
    ]
  }
}'
```

> [!NOTE]
>
> 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](https://docs.truv.com/developers/testing/test-credentials.md) 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](https://docs.truv.com/api-reference/webhooks/object.md) and the [insurance report](https://docs.truv.com/api-reference/insurance/object.md).

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](https://docs.truv.com/developers/testing/custom-sandbox-data.md#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](https://docs.truv.com/developers/testing/custom-sandbox-data.md#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.

> [accordion] 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`. |

> [accordion] 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 | |

> [accordion] 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](https://docs.truv.com/api-reference/sandbox/v1_sandbox_scenarios_create.md) 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. |

> [accordion] 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 | |

> [accordion] policies\[].vehicles\[]
>
> Free-form objects. The [insurance report](https://docs.truv.com/api-reference/insurance/object.md) 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`. |

> [accordion] 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](#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](#create-a-scenario-server-side).

### Auto policy with two vehicles and coverages

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

```json theme={null}
{
  "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.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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.

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

### Failing login

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

```json theme={null}
{
  "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.

```json theme={null}
{
  "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](https://docs.truv.com/developers/testing/custom-sandbox-data.md#document-library) entry. Upload the PDF once, then reference its `id` from the document.

```bash theme={null}
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`.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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](https://docs.truv.com/developers/testing/custom-sandbox-data.md#limits).

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

***

## Next steps

> [card] [Insurance report](https://docs.truv.com/api-reference/insurance/object.md)
>
> The report your policies are rendered into

> [card] [Test Credentials](https://docs.truv.com/developers/testing/test-credentials.md)
>
> Truv's built-in logins and the universal MFA and error scenarios

> [card] [Data refresh](https://docs.truv.com/developers/integration/embedded-orders/data-refresh.md)
>
> How refreshes reach your `is_refresh` scenarios

> [card] [Sandbox API reference](https://docs.truv.com/api-reference/sandbox/object.md)
>
> Full request and response schemas for every sandbox endpoint


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.