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, supply its input in a sandbox verification (sign in with its login, upload the files it names, or order for the applicant it identifies), 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, see Custom Sandbox Data and its per-data-source guides for payroll, document upload, financial accounts, education, and insurance.

Attributes

Identity and routing

Attribute	Type	Description
id	string	Unique identifier of the scenario
data_source	string	Data source the scenario answers for: `payroll`, `docs`, `financial_accounts`, `education`, or `insurance`. It can be omitted only when `company_domain`, `filenames`, or `date_of_birth` identifies it. `ssn_last4` is an Education matching field, but it does not identify `data_source`, so send `data_source` with it. It can’t be changed after creation; 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. Empty matches every product. Payroll serves `income`, `employment`, `deposit_switch`, and `pll`; document upload `income` and `employment`; financial accounts `assets`, `transactions`, and the bank-income `income` and `employment`; education `education`; insurance `insurance`
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. A value that collides with Truv’s own test data is refused with reserved_credential.

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, compared without regard to case. Each must be in the document library, and the scenario matches an upload that includes every one of them
ssn_last4	string	Education	Last four SSN digits that select this case
date_of_birth	date	Education	Date of birth that selects this case

Behavior

Attribute	Type	Description
behavior_status	string	Final task status. Defaults to `done`. A `docs` scenario accepts `done`, `error`, `no_data`, `config_error`, and `unavailable`; an `education` scenario those plus `login_error`
behavior_error_message	string	Error message surfaced on a failing task
behavior_duration_seconds	integer	Artificial delay before the task finishes, `0`–`120`
behavior_mfa	object	Multi-factor authentication (MFA) screens replayed at login. Refused on `docs` and `education`, which have no login step

Content

Attribute	Type	Description
payload	object	The data the scenario returns. Shape depends on `data_source`; the request body of Create a sandbox scenario documents each variant. Required unless `behavior_status` is a failure status

Which scenario wins

If multiple scenarios match, Truv selects the most specific. On docs, a scenario whose filenames are exactly the uploaded files beats one naming only some of them, and among partial matches the one naming more files wins. Then the scenario with more matching fields set wins; if there is still a tie, a scenario that sets is_refresh wins over one that doesn’t. After that, Truv selects the oldest scenario. Disabled scenarios never take part, and a scenario restricted to products is skipped for tasks of any other product. Truv uses its built-in test data when no custom scenario matches. 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. A scenario references one by document_id wherever it serves a file: a payroll or document-upload paystub, W-2, 1099, 1040, volunteer letter, or PCS order, a bank statement, or an insurance policy document. A document-upload scenario also selects on the entry’s filename.

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, read when a document collection receives a file with this filename. 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, filename, SSN digits, or date of birth collides with Truv’s own test data
`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