Custom Sandbox Data

Create custom test data in sandbox. A scenario pairs an input (a login, a set of uploaded filenames, or an applicant identity) with the exact data Truv should return for it and how the task should behave on the way. Your scenarios sit alongside Truv’s built-in test data; nothing you create replaces or hides it. Use it when the built-in test credentials and sample files don’t cover the case you need to test: a pay frequency, a bank with a specific deposit history, a student who graduates next month, an insurance policy with two vehicles, or income near your approval threshold. For the full request and response schemas, see the Sandbox API reference.

Scenarios are configuration, not verification data. They live on your account, are shared by every teammate using a sandbox key, and have no effect in production. The endpoints accept sandbox keys only; a production key gets 403 env_not_sandbox.

Start from a working sandbox integration. Your Bridge or order flow should already complete a verification with Truv’s built-in test credentials. A scenario changes only the data that comes back.

How it works

Create a scenario

POST /v1/sandbox/scenarios/ with the input it answers for, a payload of the data to return, and optionally how the task should behave: status, delay, multi-factor authentication (MFA).

Run a verification

Start a normal sandbox verification and supply that input: sign in with the scenario’s login, upload the files it names, or order for the applicant it identifies.

Get your data back

Truv resolves the scenario and serves your payload as the task result. Tasks, webhooks, and reports behave exactly as they do for any other connection.

Pick a data source

Every scenario belongs to one data_source. The data source decides which fields select the scenario, what the user does in Truv Bridge to reach it, and the shape of its payload. Two optional fields narrow a scenario further. On a login data source, provider_id restricts the scenario to one provider or carrier. products limits which products can use the scenario. For example, financial_accounts is a data source, truv_bank is a provider, and assets is a product. Each guide below works through its data source end to end.

`data_source`	Products	Matched on	How the user reaches it	Guide
`payroll`	`income`, `employment`, `deposit_switch`, `pll`	`username`, `password`, `provider_id`, `company_domain`	Signs in to a payroll provider in Truv Bridge	Payroll
`docs`	`income`, `employment`	`filenames`	Uploads documents in Truv Bridge, or your backend uploads them to a document collection	Document upload
`financial_accounts`	`assets`, `transactions`, bank-income `income` and `employment`	`username`, `password`, `provider_id`	Signs in to Truv Bank OAuth or Truv Bank non-OAuth in Truv Bridge	Financial accounts
`education`	`education`	`ssn_last4`, `date_of_birth`	Is identified by the SSN or date of birth on the order	Education
`insurance`	`insurance`	`username`, `password`, `provider_id`	Signs in to an insurance carrier in Truv Bridge	Insurance

is_refresh is accepted on every data source.

Create a scenario [Server-side]

A scenario is one flat object: what it matches on, how it behaves, and what it returns. This request creates a payroll scenario; the other guides show the same call for their data source.

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 '{
  "data_source": "payroll",
  "label": "Acme — getting started",
  "username": "acme.start",
  "password": "s4ndb0x",
  "payload": {
    "employments": [
      {
        "profile": { "full_name": "Jane Roe", "ssn": "991-91-9991" },
        "company": { "name": "Acme Inc.", "domain": "acme.com" },
        "job_title": "Staff Engineer",
        "start_date": "2022-03-01",
        "is_active": true,
        "income": "124800.00",
        "income_unit": "YEARLY",
        "pay_frequency": "BW"
      }
    ]
  }
}'

The response is the stored scenario with every field filled in, including the matching fields of other data sources, which stay empty. See the payroll guide for a full response. The guides use their own logins and labels, so you can keep this scenario while you follow them.

Check that it works

Start a sandbox verification, select Truv Payroll Provider in Truv Bridge, and sign in with acme.start / s4ndb0x. The income and employment report lists Jane Roe as a Staff Engineer at Acme Inc. If it shows Truv’s built-in test data instead, no scenario matched the input. Send the same input to the resolve endpoint to see which scenario, if any, answers it.

Truv’s built-in test data is reserved, and the API refuses a scenario that collides with it with reserved_credential. That covers the payroll, bank, and insurance logins such as goodlogin and error.user, the test document filenames, and the SSN digits and dates of birth of the education scenarios. The reserved set grows as Truv publishes new test data, so a value accepted today can be refused on a later edit. Use a distinctive prefix, such as acme., to stay clear of it.

Identity and routing

Field	Type	Description
`data_source`	string	`payroll`, `docs`, `financial_accounts`, `education`, or `insurance`. Send it explicitly, except when `company_domain`, `filenames`, or `date_of_birth` is present: Truv infers it only from those. `ssn_last4` is an Education matching field, but it does not identify `data_source`. `username`, `password`, and `provider_id` fit more than one source. You can’t change it after creating a scenario.
`label`	string	Required. How you recognize the scenario in a list. Unique per data source within your account.
`description`	string	Free-form notes. Up to 2000 characters.
`products`	array	Products the scenario applies to. Empty (the default) matches every product. A scenario restricted to products its data source never serves never matches.
`enabled`	boolean	Whether the scenario takes part in resolution. Default `true`.

Matching fields

These fields decide which input the scenario answers. A field you leave out narrows nothing, so it matches any value. Set at least one field the data source accepts; is_refresh doesn’t count on its own, because a scenario that constrains nothing would answer every input of its data source.

Field	Type	Data sources	Description
`username`	string	`payroll`, `financial_accounts`, `insurance`	The login the user types. Matched exactly, including case and any `@domain` suffix.
`password`	string	`payroll`, `financial_accounts`, `insurance`	The password the user types. Omit it to match on username alone.
`provider_id`	string	`payroll`, `financial_accounts`, `insurance`	Narrows the match to one data provider, e.g. `adp` or `truv_bank`.
`company_domain`	string	`payroll`	Narrows the match to one employer, e.g. `acme.com`.
`filenames`	array	`docs`	Filenames the user uploads, compared without regard to case. Each must be in your document library.
`ssn_last4`	string	`education`	Last four digits of the applicant’s SSN.
`date_of_birth`	date	`education`	The applicant’s date of birth, `YYYY-MM-DD`.
`is_refresh`	boolean	every data source	`true` matches data refreshes only, `false` initial verifications only. `null` (the default) matches both.

No two of your scenarios on the same data source can have the same matching fields. The API refuses a duplicate and names the scenario that already has them. enabled and products don’t make two scenarios distinct: change a matching field, or edit the existing scenario instead.

Behavior

Field	Type	Description
`behavior_status`	string	Final task status: `done`, `error`, `login_error`, `account_locked`, `mfa_error`, `config_error`, `no_data`, `unavailable`, `unable_to_reset`, `not_supported`. Default `done`.
`behavior_error_message`	string	Error message surfaced on the task. Up to 500 characters.
`behavior_duration_seconds`	integer	Artificial delay before the task finishes. `0`–`120`. Default `0`.
`behavior_mfa`	object	MFA screens to replay at login, as `{"challenges": [...]}`. Each challenge has a `type` of `TEXT` or `OPTIONS`, a `label`, `options` of `{value, label}` for a select, and `answer` or `answers`. A response that matches neither ends the task with `mfa_error`, and a challenge with neither accepts anything. Up to 5 challenges.

payload is required unless behavior_status is a failure status. A scenario that only ever fails carries no data. Two data sources have no login step, so they accept a subset of this:

Data source	`behavior_status` accepted	`behavior_mfa`
`docs`	`done`, `error`, `no_data`, `config_error`, `unavailable`	Refused
`education`	`done`, `error`, `no_data`, `config_error`, `unavailable`, `login_error`	Refused

See Task lifecycle for what each status means to your integration.

Payload

payload holds the data the scenario returns. Its shape depends on data_source, and the API validates it against that shape: unknown keys are dropped, choice fields and required fields are checked, and money is a decimal string ("4615.38", not 4615.38) so nothing is lost to floating point. Each guide has the full field reference:

Payroll payload: employments with paystubs, W-2s, bank accounts, and shifts
Document upload payload: employments with paystubs, W-2s, 1099s, 1040s, and volunteer letters, plus permanent change of station (PCS) orders
Financial accounts payload: accounts with balances, owners, transactions, holdings, statements, and recurring deposits
Education payload: National Student Clearinghouse (NSC) outcome, degrees, and enrollments
Insurance payload: policies with drivers, vehicles, and documents

Which scenario wins

Several scenarios can match the same input. Truv uses the following rules, in order, to choose one:

On docs, a scenario whose filenames are exactly the uploaded files beats one that names only some of them, and among partial matches the one naming more files wins.
The scenario with more matching fields set (username, password, provider_id, company_domain, ssn_last4, date_of_birth) wins. is_refresh doesn’t count here.
A scenario that sets is_refresh wins over one that doesn’t.
The oldest scenario wins.

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.

Check the winner without running a verification

POST /v1/sandbox/scenarios/resolve/ is a dry run: send the input a user would supply and get back the scenario that would answer it.

curl --request POST \
     --url https://prod.truv.com/v1/sandbox/scenarios/resolve/ \
     --header 'X-Access-Client-Id: YOUR_TRUV_CLIENT_ID' \
     --header 'X-Access-Secret: YOUR_TRUV_SANDBOX_SECRET' \
     --header 'Content-Type: application/json' \
     --data '{
  "data_source": "payroll",
  "username": "acme.start",
  "password": "s4ndb0x",
  "provider_id": "adp",
  "product": "income"
}'

{
  "scenario": { "id": "7b9f0c2a4d6e4f1b8c3a5d7e9f0b1c2d", "label": "Acme — getting started", "...": "..." },
  "matched_on": ["password", "username"],
  "tier": "client"
}

scenario is abbreviated here; the API returns the full scenario. matched_on lists the fields the winning scenario actually constrained. Here the scenario sets no provider_id, so it answers the ADP connection without listing provider_id. A 404 means no scenario of yours matches and the verification would get Truv’s built-in test data.

Manage scenarios

List and filter

curl --request GET \
     --url 'https://prod.truv.com/v1/sandbox/scenarios/?data_source=payroll&enabled=true&product=income' \
     --header 'X-Access-Client-Id: YOUR_TRUV_CLIENT_ID' \
     --header 'X-Access-Secret: YOUR_TRUV_SANDBOX_SECRET'

The response is cursor-paginated: {"results": [...], "next": "..."}. Follow next until it is null. Results come back oldest first. Which scenario wins depends on the input, so use the resolve endpoint to see the actual winner.

Parameter	Values
`data_source`	`payroll`, `docs`, `financial_accounts`, `education`, `insurance`
`product`	A product value, such as `income`, `assets`, or `education`. Scenarios with no `products` match every product and are always included.
`enabled`	`true` or `false`

Update

PATCH (or PUT, they behave identically) replaces every top-level key you send and leaves the rest untouched. payload is replaced wholesale, so send the complete object, not a fragment.

curl --request PATCH \
     --url https://prod.truv.com/v1/sandbox/scenarios/SCENARIO_ID/ \
     --header 'X-Access-Client-Id: YOUR_TRUV_CLIENT_ID' \
     --header 'X-Access-Secret: YOUR_TRUV_SANDBOX_SECRET' \
     --header 'Content-Type: application/json' \
     --data '{ "enabled": false }'

You can’t change data_source after creating a scenario. To use another data source, create a new scenario with that source and a compatible payload.

Delete

curl --request DELETE \
     --url https://prod.truv.com/v1/sandbox/scenarios/SCENARIO_ID/ \
     --header 'X-Access-Client-Id: YOUR_TRUV_CLIENT_ID' \
     --header 'X-Access-Secret: YOUR_TRUV_SANDBOX_SECRET'

Document library

Any record a scenario serves as a file comes from your sandbox document library: a paystub or W-2 PDF on a payroll or document upload scenario, a 1099, volunteer letter, or PCS order, a bank statement, or an insurance policy document. Upload the file once, then reference its id as document_id from as many scenarios as you like. When a task uses an entry, Truv serves a separate copy for that task; the original stays in the library. Document upload scenarios also use the library for matching: every name in a scenario’s filenames must be an entry, and an entry’s test metadata describes what a document collection finds in the file.

Upload a file

Send the file as multipart/form-data, or as JSON with the bytes base64-encoded in content. Send exactly one of file or content. filename is a separate field: it is the name the entry is addressed by and does not have to match the name on disk. Filenames are unique per account, compared without regard to case, and Truv’s own test document filenames are reserved.

curl --request POST \
     --url https://prod.truv.com/v1/sandbox/documents/ \
     --header 'X-Access-Client-Id: YOUR_TRUV_CLIENT_ID' \
     --header 'X-Access-Secret: YOUR_TRUV_SANDBOX_SECRET' \
     --form 'filename=acme-paystub-2026-08-14.pdf' \
     --form 'file=@./acme-paystub-2026-08-14.pdf'

Truv validates the file on upload the same way a document collection does, so an unreadable or unsupported file is refused rather than stored. Supported types are PDF and JPEG, PNG, TIFF, WebP, BMP, HEIC, and HEIF images; HEIC and HEIF are converted to PNG. The response is the library entry. Keep the top-level id: that is the document_id your payloads reference.

{
  "id": "a41d7e9c05b24f6b8e3c1d5a7f92b604",
  "uploaded_file": {
    "file_id": "a41d7e9c05b24f6b8e3c1d5a7f92b604",
    "filename": "acme-paystub-2026-08-14.pdf",
    "mime_type": "application/pdf",
    "size": 48219,
    "md5": "9f2b1c0d4e6a8b3f5c7d9e1a2b4c6d8e",
    "file": "https://...",
    "status": "successful",
    "validations": {
      "is_viable_size": true,
      "is_supported_type": true,
      "is_accessible": true,
      "is_valid": true,
      "is_readable": true,
      "is_unique": true
    },
    "last_error": ""
  },
  "documents": [
    {
      "document_type": "PAYSTUB",
      "identity": { "full_name": "John Doe", "ssn": "991-91-9991" },
      "company_name": "Acme Inc."
    }
  ],
  "created_at": "2026-09-17T10:11:02.104882Z",
  "updated_at": "2026-09-17T10:11:02.104901Z"
}

Test metadata

status, validations, last_error, and documents are test metadata you configure for the entry, not data Truv extracted from the file. Only document upload scenarios read them, when a document collection receives a file with the entry’s filename. Every other use serves the file bytes and ignores the metadata, so leave it out.

Field	Description
`documents`	The documents a collection recognizes in the file: one object per document with `document_type`, optional `document_subtype`, `identity` (`full_name`, `first_name`, `last_name`, `ssn`), `company_name`, `start_page`, and `end_page`. Defaults to one paystub for John Doe at Acme Inc.
`status`	The file outcome a collection reports: `successful` (the default), `invalid`, `duplicate`, or `failed`. A `successful` entry must declare at least one document.
`validations`	Per-check results for a failing status: `is_viable_size`, `is_supported_type`, `is_accessible`, `is_valid`, `is_readable`, `is_unique`.
`last_error`	Message a collection reports for a failed file. Up to 500 characters.

Set them on upload (documents only) or afterwards with PATCH /v1/sandbox/documents/{id}/, which takes filename and the four fields above. The file itself can’t be replaced; upload a new entry instead.

Manage the library

GET /v1/sandbox/documents/ lists your entries newest first, with a fresh pre-signed file URL on every read. DELETE /v1/sandbox/documents/{id}/ removes one. A delete is refused with 409 resource_in_use while any scenario still references the entry, by document_id or by filenames, so drop the reference first. Renaming an entry a docs scenario matches on is refused the same way.

Limits

These are the default limits for your account as a whole. Each guide lists the per-payload limits for its data source. Contact Truv Support if your test plan needs higher limits.

Limit	Default
Scenarios per account (all data sources)	100
Payload size	1024 KB
MFA challenges per scenario	5
Task delay (`behavior_duration_seconds`)	120 seconds
Files in the document library	100
Single file upload	10 MB
Library storage, including copies served to tasks	250 MB
Documents declared on one library file	10

Errors

Sandbox configuration errors use the standard error envelope:

{
  "error": {
    "code": "reserved_credential",
    "message": "Username 'goodlogin' is reserved for Truv's documented sandbox logins."
  }
}

Code	Status	Cause
`env_not_sandbox`	403	The request authenticated with a production key.
`data_source_required`	400	The fields you set fit more than one data source. Send `data_source` explicitly.
`unsupported_data_source`	400	You set 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 quota would be exceeded. The message names the limit and the field.
`resource_in_use`	409	A document is still referenced by a scenario.
`incorrect_parameters`	400	A field failed validation, or another scenario of the same data source already has the same matching fields. `extra.invalid-params` names the field and the reason.

Next steps

Payroll

Employments, paystubs, W-2s, bank accounts, and shifts behind a payroll login

Document upload

What Truv returns for the files a user uploads

Financial accounts

Accounts, transactions, holdings, statements, and recurring deposits behind a bank login

Education

Degrees and enrollments for an applicant’s SSN or date of birth

Insurance

Policies, drivers, vehicles, and documents behind a carrier login

Sandbox API reference

Full request and response schemas for every sandbox endpoint

Get Started

Start Building

Implementation

Bridge SDK

Testing & Launch

Dashboard & Configuration

Coverage

Custom Sandbox Data

How it works

Pick a data source

Create a scenario [Server-side]

Check that it works

Identity and routing

Matching fields

Behavior

Payload

Which scenario wins

Check the winner without running a verification

Manage scenarios

List and filter

Update

Delete

Document library

Upload a file

Test metadata

Manage the library

Limits

Errors

Next steps

Payroll

Document upload

Financial accounts

Education

Insurance

Sandbox API reference