Skip to main content
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 first.
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:
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 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:
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 from the link’s income report.

Matching fields

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: 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_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 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 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, 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:
Read the employments with the link’s income report:
The report for the first scenario looks like this, abbreviated:
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.

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

Current job only

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

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.

Raise on refresh

Pair the first scenario 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.

No record found

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

Slow lookup that fails

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

Limits

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

Next steps

Custom Sandbox Data

Shared concepts, scenario resolution, and limits for every data source

Create an order

The request that carries the applicant’s name, SSN, and date of birth

Create a refresh order

Run instant verification again and reach your is_refresh scenarios

Sandbox API reference

Full request and response schemas for every sandbox endpoint