Skip to main content
PATCH
Update a sandbox scenario

Authorizations

X-Access-Client-Id
string
header
required

Client ID

X-Access-Secret
string
header
required

Client Access Key

Path Parameters

scenario_id
string
required

Body

application/json

A partial update. A top-level key present in the body replaces that key entirely, and an absent key is left untouched - payload included, so send the complete object rather than a fragment. PUT behaves identically. data_source cannot be changed after create.

label
string

How the scenario is recognized in a list.

Maximum string length: 128
Example:

"Acme - salaried, biweekly"

description
string

Free-form notes about what the case covers.

Maximum string length: 2000
Example:

"Full-time salaried user with two paystubs"

products
enum<string>[]

Products the scenario applies to. Empty matches every product.

Available options:
income,
employment,
deposit_switch,
pll,
insurance,
transactions,
assets,
admin,
education
Example:
enabled
boolean

Whether the scenario takes part in resolution.

Example:

false

username
string

The login the user types, matched exactly.

Maximum string length: 255
Example:

"acme.salaried"

password
string

The password the user types.

Maximum string length: 255
Example:

"s4ndb0x"

provider_id
string

Narrows the match to one data provider.

Maximum string length: 64
Example:

"adp"

company_domain
string

Narrows the match to one company.

Maximum string length: 128
Example:

"acme.com"

is_refresh
boolean

Narrows the match to refreshes or to initial verifications.

Example:

true

filenames
string[]

Uploaded filenames that select this case. Document upload only.

Maximum string length: 255
Example:
ssn_last4
string

Last four SSN digits that select this case. Education only.

Maximum string length: 4
Example:

"4321"

date_of_birth
string<date>

Date of birth that selects this case. Education only.

Example:

"1990-01-02"

behavior_status
enum<string>

Final task status.

Available options:
done,
error,
login_error,
account_locked,
mfa_error,
config_error,
no_data,
unavailable,
unable_to_reset,
not_supported
Example:

"login_error"

behavior_error_message
string

Error message surfaced on a failing task.

Maximum string length: 500
Example:

"Your account has been locked after too many attempts."

behavior_duration_seconds
integer

Artificial delay before the task finishes.

Required range: 0 <= x <= 120
Example:

45

behavior_mfa
object

Multi-factor authentication (MFA) screens replayed at login. Refused on docs and education scenarios, which have no login step.

Example:
payload
Payroll · object

The data the scenario returns, in the shape of the scenario's data_source. Keys outside the shape are dropped on write. Empty only on a scenario whose behavior_status is a failure status; a successful scenario must carry data.

Response

A client-authored sandbox case - what it matches on, how it behaves, and the data it returns. data_source decides the shape of payload and the statuses behavior_status can hold, and payload is empty only on a scenario whose behavior_status is a failure status.

data_source
enum<string>

payroll. The scenario answers payroll logins and payload is payroll data. Cannot be changed after create.

Available options:
payroll
Example:

"payroll"

id
string
read-only

Unique identifier of the scenario.

Maximum string length: 64
Example:

"7b9f0c2a4d6e4f1b8c3a5d7e9f0b1c2d"

label
string

How the scenario is recognized in a list. Unique per data source within your account.

Maximum string length: 128
Example:

"Acme - salaried, biweekly"

description
string

Free-form notes about what the case covers.

Maximum string length: 2000
Example:

"Full-time salaried user with two paystubs"

products
enum<string>[]

Products the scenario applies to. Payroll scenarios serve income, employment, deposit_switch and pll; document upload income and employment; financial accounts assets, transactions and the bank-income flows of income and employment; education education; insurance insurance. A scenario restricted to products its data source never serves never matches. Empty, the default, matches every product.

Available options:
income,
employment,
deposit_switch,
pll,
insurance,
transactions,
assets,
admin,
education
Example:
enabled
boolean
default:true

Whether the scenario takes part in resolution.

Example:

true

username
string | null

The login the user types, matched exactly. Null when the scenario does not set it.

Maximum string length: 255
Example:

"acme.salaried"

password
string | null

The password the user types. Null when the scenario matches on username alone.

Maximum string length: 255
Example:

"s4ndb0x"

provider_id
string | null

Narrows the match to one data provider. Payroll, financial accounts and insurance only. Null when the scenario does not set it.

Maximum string length: 64
Example:

null

company_domain
string | null

Narrows the match to one company. Payroll only. Null when the scenario does not set it.

Maximum string length: 128
Example:

null

is_refresh
boolean | null

true matches data refreshes only, false initial verifications only. Null, the default, matches both. Supported on every data source, but it does not count toward matching fields and cannot be the only field set. It breaks a tie only when matching fields are equal.

Example:

null

filenames
string[]

Uploaded filenames that select this case, compared without regard to case. Document upload only, so empty on other scenarios. Every name must be in your sandbox document library, and the scenario matches an upload that includes every one of them.

Maximum string length: 255
Example:
ssn_last4
string | null

Last four SSN digits that select this case. Education only, so null on other scenarios.

Maximum string length: 4
Example:

null

date_of_birth
string<date> | null

Date of birth that selects this case. Education only, so null on other scenarios.

Example:

null

behavior_error_message
string

Error message surfaced on a failing task. Empty on a scenario that succeeds.

Maximum string length: 500
Example:

""

behavior_duration_seconds
integer
default:0

Artificial delay before the task finishes.

Required range: 0 <= x <= 120
Example:

0

behavior_mfa
object

MFA screens replayed before the data is returned. Empty unless the scenario declares any, and always empty on docs and education scenarios.

Example:
behavior_status
enum<string>

Final task status. unable_to_reset is accepted but the payroll sandbox never acts on it. payload is empty only when this is not done.

Available options:
done,
error,
login_error,
account_locked,
mfa_error,
config_error,
no_data,
unavailable,
unable_to_reset,
not_supported
Example:

"done"

payload
Payroll · object

payload for a payroll scenario.

created_at
string<date-time>
read-only

Time when the scenario was created.

Example:

"2026-09-17T10:04:11.482913Z"

updated_at
string<date-time>
read-only

Time when the scenario was last updated.

Example:

"2026-09-17T10:04:11.482931Z"