The Sandbox Scenario object

A sandbox scenario is a client-authored test case: when this input arrives, behave like this and return that. Create one, sign in with its login in Truv Bridge, and the task completes with your data instead of Truv’s built-in test data. Scenarios are scoped to your account, so every teammate’s sandbox key reads and writes the same set. The endpoints accept sandbox keys only — a production key gets 403 env_not_sandbox. For a walkthrough with worked examples of payroll scenarios, see Custom Sandbox Data.

Attributes

Identity and routing

Attribute	Type	Description
id	string	Unique identifier of the scenario
data_source	string	Data source the scenario answers for. Inferred from which matching fields are set when omitted. Can’t be changed after create — to use another data source, create a new scenario
label	string	How the scenario is recognized in a list. Unique per data source within your account
description	string	Free-form notes about what the case covers
products	array	Products the scenario applies to. Payroll scenarios use `income`, `employment`, `deposit_switch`, and `pll`. Empty matches every product
enabled	boolean	Whether the scenario takes part in resolution
created_at	datetime	Timestamp for created scenario
updated_at	datetime	Timestamp for updated scenario

How a scenario is selected

These matching fields decide which input the scenario answers. A field left unset narrows nothing, so it matches any value. The API refuses a scenario that sets none of them, and is_refresh alone doesn’t count — such a scenario would answer every input of its data source. No two scenarios of the same data source can have the same matching fields; enabled and products don’t make them distinct.

Attribute	Type	Data source	Description
username	string	Payroll, financial accounts, insurance	The login the user types. Matched exactly
password	string	Payroll, financial accounts, insurance	The password the user types
provider_id	string	Payroll, financial accounts, insurance	Narrows the match to one data provider
company_domain	string	Payroll	Narrows the match to one company
is_refresh	boolean	Every data source	`true` matches refreshes only, `false` initial verifications only, null both
filenames	array	Document upload	Uploaded filenames that select this case
ssn_last4	string	Education, credit	Last four SSN digits that select this case
date_of_birth	date	Education	Date of birth that selects this case
phone	string	Credit	Phone number that selects this case, stored in E.164

Behavior

Attribute	Type	Description
behavior_status	string	Terminal status the task settles on. Defaults to `done`
behavior_error_message	string	Error message surfaced on a failing task
behavior_duration_seconds	integer	Artificial delay before the task settles, `0`–`120`
behavior_mfa	object	Multi-factor authentication (MFA) screens replayed before the data is returned

Content

Attribute	Type	Description
payload	object	The data the scenario returns. Shape depends on `data_source`. Required unless `behavior_status` is a failure status

Which scenario wins

If multiple scenarios match, Truv selects the scenario with more matching fields, excluding is_refresh. is_refresh is supported on every data source but doesn’t count toward matching fields; if there is still a tie, a scenario that sets it wins over one that doesn’t. After that, Truv selects the oldest scenario. Disabled scenarios never take part, and a scenario pinned to products is skipped for tasks of any other product. When nothing matches, the task falls through to Truv’s built-in test data. Resolve a sandbox scenario reports the winner for an input without running a verification.

The Sandbox Document object

A sandbox document is a file in your sandbox document library. Payroll paystubs and W-2s reference one by document_id to serve a real PDF; every W-2 requires one.

Attribute	Type	Description
id	string	Unique identifier of the library entry, and the value a payload references as `document_id`
uploaded_file	object	The stored file: `file_id`, `filename`, `mime_type`, `size`, `md5`, a pre-signed `file` URL, plus the declared `status`, `validations` and `last_error`
documents	array	Test metadata describing the documents in the file, used when a document-upload scenario serves it. You configure it; Truv doesn’t extract it from the file. Defaults to one paystub for John Doe at Acme Inc. when omitted
created_at	datetime	Timestamp for created entry
updated_at	datetime	Timestamp for updated entry

When a task uses a sandbox document, Truv creates a separate copy for that task. The original stays in your sandbox document library and can be reused. Remove all scenario references before deleting the library entry.

Endpoints

Scenarios

List sandbox scenarios - GET /v1/sandbox/scenarios/
Create a sandbox scenario - POST /v1/sandbox/scenarios/
Resolve a sandbox scenario - POST /v1/sandbox/scenarios/resolve/
Retrieve a sandbox scenario - GET /v1/sandbox/scenarios/{scenario_id}/
Update a sandbox scenario - PATCH /v1/sandbox/scenarios/{scenario_id}/
Delete a sandbox scenario - DELETE /v1/sandbox/scenarios/{scenario_id}/

Documents

List sandbox documents - GET /v1/sandbox/documents/
Upload a sandbox document - POST /v1/sandbox/documents/
Retrieve a sandbox document - GET /v1/sandbox/documents/{document_id}/
Update a sandbox document - PATCH /v1/sandbox/documents/{document_id}/
Delete a sandbox document - DELETE /v1/sandbox/documents/{document_id}/

Errors

Sandbox configuration errors use the standard error envelope.

Code	Status	Cause
`env_not_sandbox`	403	The request authenticated with a production key
`data_source_required`	400	The matching fields set on the scenario fit more than one data source. Send `data_source` explicitly
`unsupported_data_source`	400	The scenario sets a matching field the data source doesn’t accept
`reserved_credential`	400	The login or filename collides with one of Truv’s own documented sandbox credentials
`sandbox_limit_exceeded`	400	A sandbox quota would be exceeded
`resource_in_use`	409	A document is still referenced by a scenario
`incorrect_parameters`	400	A field failed validation. `extra.invalid-params` names the field and the reason

API Reference

Platform

Income & Employment

Financial Accounts

Document Processing

Direct Deposit Switch

Insurance Verification

The Sandbox Scenario object

Attributes

Identity and routing

How a scenario is selected

Behavior

Content

Which scenario wins

The Sandbox Document object

Endpoints

Scenarios

Documents

Errors

​Attributes

​Identity and routing

​How a scenario is selected

​Behavior

​Content

​Which scenario wins

​The Sandbox Document object

​Endpoints

​Scenarios

​Documents

​Errors

Attributes

Identity and routing

How a scenario is selected

Behavior

Content

Which scenario wins

The Sandbox Document object

Endpoints

Scenarios

Documents

Errors