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:"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 anincome or employment product:
"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 thesebehavior_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 withno_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, andprofile.emailreplace the order’s values when you set them.profile.home_addressis 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_ratefrom the paystubs, so the payload has nopay_ratefield. Each employment’sderived_fieldslists 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 withis_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:Payload reference
Thepayload 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.
employments[]
employments[]
employments[].profile
employments[].profile
employments[].company
employments[].company
employments[].paystubs[]
employments[].paystubs[]
Examples
Each example is a request body forPOST /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 withssn_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 inis_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 withunavailable 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 scenariosSandbox API reference
Full request and response schemas for every sandbox endpoint