> ## 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.

# Instant Verification Scenarios

> Pair an applicant name with the employers and income a sandbox instant verification should return for it

Set the employment records a sandbox instant verification returns. Instant verification looks up an applicant's employers in the background, without the applicant signing in to Truv Bridge. An `instant` scenario pairs the applicant's name with the employments you want back, and serves them to every sandbox order for that applicant.

Use it to test how your integration handles an order that completes without the applicant connecting: a current job with recent paystubs, a past employer, an applicant with no record, or a lookup that fails. For the shared concepts, read [Custom Sandbox Data](https://docs.truv.com/developers/testing/custom-sandbox-data.md) first.

> [!NOTE]
>
> Instant verification must be enabled for your account. Contact your Truv Customer Success Manager to enable it. Your scenarios are accepted either way, but sandbox orders run instant verification only once it's enabled.

***

## Create a scenario \[Server-side]

This request creates a scenario for Taylor Curtis, a current engineer at Acme Manufacturing with a past job at Globex Logistics:

```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 '{
  "label": "Taylor Curtis — engineer at Acme",
  "first_name": "Taylor",
  "last_name": "Curtis",
  "date_of_birth": "1985-04-12",
  "payload": {
    "employments": [
      {
        "profile": { "email": "taylor.curtis@example.com" },
        "company": { "name": "Acme Manufacturing", "domain": "acme.com" },
        "job_title": "Engineer",
        "job_type": "F",
        "start_date": "2019-01-01",
        "is_active": true,
        "income": "120000.00",
        "income_unit": "YEARLY",
        "pay_frequency": "BW",
        "paystubs": [
          {
            "pay_date": "2026-10-30",
            "period_start": "2026-10-13",
            "period_end": "2026-10-26",
            "gross_pay": "4615.38",
            "net_pay": "3400.00",
            "hours": "80"
          }
        ]
      },
      {
        "company": { "name": "Globex Logistics" },
        "job_title": "Analyst",
        "start_date": "2015-03-01",
        "end_date": "2018-12-01",
        "is_active": false
      }
    ]
  }
}'
```

The response is the stored scenario, with `"data_source": "instant"`. `first_name` and `last_name` are accepted only by instant scenarios, so Truv infers the data source from them.

### Use it in an order

[Create an order](https://docs.truv.com/api-reference/orders/orders_create.md) with your sandbox key for an applicant with that name and date of birth. Instant verification needs the applicant's first and last name, full SSN, and date of birth, and an `income` or `employment` product:

```bash theme={null}
curl --request POST \
     --url https://prod.truv.com/v1/orders/ \
     --header 'X-Access-Client-Id: YOUR_TRUV_CLIENT_ID' \
     --header 'X-Access-Secret: YOUR_TRUV_SANDBOX_SECRET' \
     --header 'Content-Type: application/json' \
     --data '{
  "first_name": "Taylor",
  "last_name": "Curtis",
  "ssn": "666-09-4321",
  "date_of_birth": "1985-04-12",
  "email": "taylor.curtis@example.com",
  "products": ["income"],
  "use_case": "government"
}'
```

Truv runs instant verification when the order is created, if instant verification is the first data source configured for the order's product. The order's employer completes from your scenario with `"data_source": "instant"`. [Read the result](#read-the-result) from the link's income report.

***

## Matching fields

| Field | Type | Description |
| - | - | - |
| `first_name` | string | Required. The applicant's first name on the order. Compared without regard to case or surrounding spaces. |
| `last_name` | string | Required. The applicant's last name on the order, compared the same way. |
| `date_of_birth` | date | Optional. Narrows the match to an applicant born on this date, `YYYY-MM-DD`. |
| `ssn_last4` | string | Optional. Narrows the match to an applicant whose SSN ends in these four digits. |
| `is_refresh` | boolean | `true` matches data refreshes only, `false` initial verifications only. `null` (the default) matches both. |

A scenario that sets `date_of_birth` or `ssn_last4` matches only an applicant with that value, and wins over a scenario with the name alone. Two scenarios whose names differ only in case have the same matching fields, so the API refuses the second one.

`products` can be `income` and `employment`. Leave it empty to serve both.

An applicant who matches none of your scenarios runs against Truv's built-in instant sandbox, which answers by SSN. Nothing is reserved: a scenario that matches the applicant wins, even when the order uses a built-in test SSN.

### Built-in test applicants

The SSN on the order selects what the built-in instant sandbox returns:

| SSN | Result |
| - | - |
| `000-00-0001` | One employment: Program Manager, inactive |
| `000-00-0002` | One employment: Accountant, on leave |
| `000-00-0003` | One employment: Product Manager, active |
| `000-00-0004` | One employment: Customer Service Representative, active |
| `000-00-0005` | One employment: Account Executive, inactive |
| `000-00-0006` | One employment: Recruiter, inactive |
| `000-00-0007` | Two employments as Engineering Manager, one active and one inactive |
| `000-00-0008` | One employment: Operations Manager, active |
| `000-01-0000` | No record. The task ends with `no_data`. |

Any other SSN except `000-00-0000` also ends with `no_data`. When the task doesn't complete, the order's employer stays open, and the order continues to the applicant's other data sources.

Don't use `000-00-0000` as a test SSN. Truv drops an SSN that is all zeros, so the employment it returns has no SSN.

### Behavior

An instant scenario accepts these `behavior_status` values:

| `behavior_status` | Default error message |
| - | - |
| `done` | |
| `no_data` | No employment record was found |
| `unavailable` | Instant verification is temporarily unavailable |
| `config_error` | Instant verification is not configured for this account |
| `error` | Instant verification failed |

`behavior_error_message` replaces the default message. `behavior_duration_seconds` holds the task before it completes or fails. A failure status ends only the instant verification: the order's employer stays open, and the order continues to the applicant's other data sources.

Instant verification has no login step, so `behavior_mfa` is refused. See [Behavior](https://docs.truv.com/developers/testing/custom-sandbox-data.md#behavior) for the shared fields.

***

## How the data is served

* **One employment per entry.** Each `employments[]` entry becomes one employment on the order's instant link. A scenario that serves no employments ends with `no_data`, on a refresh too.
* **The applicant's identity comes from the order.** The SSN, date of birth, and phone number always come from the order. `profile.first_name`, `profile.last_name`, and `profile.email` replace the order's values when you set them. `profile.home_address` is served as authored.
* **Employers are matched to the order by name.** Each employer is matched to an employer the order names. An employer that matches none fills an employer the order left blank. Any other employer is added to the order only when the order lets the applicant add employers. Otherwise it appears only in the link's income report.
* **Truv derives what a real result derives.** Your data goes through the same checks and calculations as a real instant result. Truv computes `pay_rate` from the paystubs, so the payload has no `pay_rate` field. Each employment's `derived_fields` lists the values Truv computed.
* **Every run reads the scenario as it is now.** An edit applies to the next order. A sandbox order never reuses an earlier order's result.

### Refreshes

A [refresh order](https://docs.truv.com/api-reference/orders/orders_create_refresh_order.md) runs instant verification again on the same link and resolves your scenarios with `is_refresh: true`. The refresh updates an employment in place when the scenario lists the same employer with the same `start_date`. An employer the link doesn't have yet is added as a new employment, so renaming an employer adds an employment instead of renaming the old one. When no scenario matches the refresh, it runs against the [built-in instant sandbox](#built-in-test-applicants), as an initial verification does. Add a scenario with `"is_refresh": true` to change the data on refresh only.

***

## Read the result

The order's employer carries the instant link's ID once it completes:

```json theme={null}
{
  "id": "63728a9ff20943babe5fd39b5756c407",
  "status": "completed",
  "company_name": "Acme Manufacturing",
  "data_source": "instant",
  "link_id": "6980d724e53f46c78235b08c51f656fa"
}
```

Read the employments with the [link's income report](https://docs.truv.com/api-reference/account-link-income-and-employment-reports/link_detail_reports_income.md):

```bash theme={null}
curl --request GET \
     --url https://prod.truv.com/v1/links/LINK_ID/income/report/ \
     --header 'X-Access-Client-Id: YOUR_TRUV_CLIENT_ID' \
     --header 'X-Access-Secret: YOUR_TRUV_SANDBOX_SECRET'
```

The report for the first scenario looks like this, abbreviated:

```json theme={null}
{
  "id": "74834283138c4a148c829d9bd93c80e1",
  "status": "done",
  "data_source": "instant",
  "employments": [
    {
      "job_title": "Engineer",
      "job_type": "F",
      "start_date": "2019-01-01",
      "end_date": null,
      "is_active": true,
      "income": "120000.00",
      "income_unit": "YEARLY",
      "pay_rate": "4615.38",
      "pay_frequency": "BW",
      "derived_fields": ["pay_rate"],
      "company": { "name": "Acme Manufacturing", "...": "..." },
      "profile": {
        "first_name": "Taylor",
        "last_name": "Curtis",
        "full_name": "Taylor Curtis",
        "email": "taylor.curtis@example.com",
        "ssn": "666094321",
        "date_of_birth": "1985-04-12",
        "...": "..."
      },
      "statements": [
        {
          "pay_date": "2026-10-30",
          "period_start": "2026-10-13",
          "period_end": "2026-10-26",
          "gross_pay": "4615.38",
          "net_pay": "3400.00",
          "hours": "80.00",
          "...": "..."
        }
      ]
    },
    {
      "job_title": "Analyst",
      "start_date": "2015-03-01",
      "end_date": "2018-12-01",
      "is_active": false,
      "company": { "name": "Globex Logistics", "...": "..." },
      "statements": [],
      "...": "..."
    }
  ]
}
```

The order in this example names no employer, so Acme Manufacturing fills its one blank employer, and Globex Logistics appears only in the report.

***

## Payload reference

The `payload` object contains the `employments` array. Every field except the company name is optional: send only what your test needs. Unknown keys are dropped, including an SSN or date of birth in `profile`.

> [accordion] employments\[]
>
> | Field | Type | Description |
> | - | - | - |
> | `profile` | object | The identity the employer reports. See below. |
> | `company` | object | Required. The employer. See below. |
> | `job_title` | string | |
> | `job_type` | string | `F` full time, `P` part time, `S` seasonal, `D` per diem, `C` contract, `V` volunteer. |
> | `start_date` | date | ISO `YYYY-MM-DD`. |
> | `end_date` | date | On or after `start_date` when both are set. Set it to author a past employment. |
> | `original_hire_date` | date | |
> | `is_active` | boolean | |
> | `income` | decimal string | Income amount expressed in `income_unit`. |
> | `income_unit` | string | `YEARLY`, `MONTHLY`, `WEEKLY`, `DAILY`, `HOURLY`. |
> | `pay_frequency` | string | `M` monthly, `SM` semimonthly, `W` weekly, `BW` biweekly, `A` annually, `SA` semiannually, `C` commission. |
> | `paystubs` | array | Pay statements. |

> [accordion] employments\[].profile
>
> | Field | Type | Description |
> | - | - | - |
> | `first_name` | string | Replaces the order's first name in the report. |
> | `last_name` | string | Replaces the order's last name in the report. |
> | `email` | string | Replaces the order's email in the report. |
> | `home_address` | object | `street`, `city`, `state`, `zip`, `country`. |

> [accordion] employments\[].company
>
> | Field | Type | Description |
> | - | - | - |
> | `name` | string | Required. Matched against the employers the order names. |
> | `ein` | string | |
> | `domain` | string | |
> | `phone` | string | |
> | `address` | object | `street`, `city`, `state`, `zip`, `country`. |

> [accordion] employments\[].paystubs\[]
>
> | Field | Type | Description |
> | - | - | - |
> | `pay_date` | date | Required. |
> | `period_start` | date | |
> | `period_end` | date | |
> | `gross_pay` | decimal string | |
> | `net_pay` | decimal string | |
> | `hours` | decimal string | |
> | `earnings` | array | Objects of `name` (required), `amount` (required), `rate`, `units`. |

***

## 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). Each one uses its own name, so they coexist.

### Current job only

The smallest scenario that completes an order: one employer and an income.

```json theme={null}
{
  "label": "Jordan Reyes — one current job",
  "first_name": "Jordan",
  "last_name": "Reyes",
  "payload": {
    "employments": [
      {
        "company": { "name": "Acme Manufacturing" },
        "job_title": "Warehouse Associate",
        "start_date": "2023-06-05",
        "is_active": true,
        "income": "21.50",
        "income_unit": "HOURLY",
        "pay_frequency": "W"
      }
    ]
  }
}
```

### Two applicants with the same name

Narrow each scenario with `ssn_last4` to tell apart two applicants named Sam Lee. An order for a Sam Lee whose SSN ends in neither set of digits gets no record.

```json theme={null}
{
  "label": "Sam Lee — SSN ending 1111",
  "first_name": "Sam",
  "last_name": "Lee",
  "ssn_last4": "1111",
  "payload": {
    "employments": [
      { "company": { "name": "Acme Manufacturing" }, "job_title": "Engineer", "is_active": true }
    ]
  }
}
```

```json theme={null}
{
  "label": "Sam Lee — SSN ending 2222",
  "first_name": "Sam",
  "last_name": "Lee",
  "ssn_last4": "2222",
  "payload": {
    "employments": [
      { "company": { "name": "Globex Logistics" }, "job_title": "Driver", "is_active": true }
    ]
  }
}
```

### Raise on refresh

Pair the [first scenario](#create-a-scenario-server-side) with this one to see the income change on a refresh order. The two differ in `is_refresh`, so they coexist, and the refresh-only scenario answers refreshes.

```json theme={null}
{
  "label": "Taylor Curtis — raise on refresh",
  "first_name": "Taylor",
  "last_name": "Curtis",
  "date_of_birth": "1985-04-12",
  "is_refresh": true,
  "payload": {
    "employments": [
      {
        "company": { "name": "Acme Manufacturing" },
        "job_title": "Senior Engineer",
        "start_date": "2019-01-01",
        "is_active": true,
        "income": "135000.00",
        "income_unit": "YEARLY",
        "pay_frequency": "BW"
      }
    ]
  }
}
```

### No record found

A failure status needs no payload. The order continues as if instant verification found nothing.

```json theme={null}
{
  "label": "Riley Park — no record",
  "first_name": "Riley",
  "last_name": "Park",
  "behavior_status": "no_data"
}
```

### Slow lookup that fails

Holds the task for 20 seconds, then ends it with `unavailable` and your message.

```json theme={null}
{
  "label": "Morgan Diaz — lookup unavailable",
  "first_name": "Morgan",
  "last_name": "Diaz",
  "behavior_status": "unavailable",
  "behavior_duration_seconds": 20,
  "behavior_error_message": "The employment lookup timed out."
}
```

***

## Limits

These are the default limits for instant payloads. The account-wide limits are listed on [Custom Sandbox Data](https://docs.truv.com/developers/testing/custom-sandbox-data.md#limits).

| Limit | Default |
| - | - |
| Employments per scenario | 10 |
| Paystubs per employment | 60 |

***

## Next steps

> [card] [Custom Sandbox Data](https://docs.truv.com/developers/testing/custom-sandbox-data.md)
>
> Shared concepts, scenario resolution, and limits for every data source

> [card] [Create an order](https://docs.truv.com/api-reference/orders/orders_create.md)
>
> The request that carries the applicant's name, SSN, and date of birth

> [card] [Create a refresh order](https://docs.truv.com/api-reference/orders/orders_create_refresh_order.md)
>
> Run instant verification again and 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.