Create Sandbox test data
Use Sandbox accounts to create rich test data for Plaid products
Customize Sandbox account data
In addition to a set of pre-populated Sandbox test users, the Sandbox environment also provides the ability to create custom user accounts, which can be used in conjunction with /sandbox/public_token/create
or Plaid Link to generate custom Sandbox data, or in conjunction with Plaid Link to test Link flows in the Sandbox.
Using these accounts, you can create your own testing data for the Assets, Auth, Balance, Identity, Investments, Liabilities, and Transactions products. You can also simulate an account with regular income or one that makes regular loan payments. For Link testing, custom accounts support multi-factor authentication, reCAPTCHA, and Link error flows.
To customize testing data for Document Income, see Testing Document Income.
Configuring the custom user account
Custom user accounts can be configured and accessed in two ways. The easiest (and recommended) method is by using the Sandbox Users tool, located in the Plaid Dashboard under Developers -> Sandbox. Set the username and configuration object in the Dashboard, then go through the Link flow on Sandbox with that username and any non-empty password. You can also use /sandbox/public_token/create
with options.override_username
and options.override_password
to create a public token for a custom user account while bypassing Link. Alternatively, you can log into Sandbox with the username user_custom
and provide the configuration object as the password.
To aid in testing, Plaid maintains a GitHub repo of pre-created custom user accounts that some users have found helpful.
Very large configuration objects (larger than approximately 55kb, or approximately 250 transactions) are not currently supported and may cause the Link attempt to fail.
At OAuth institutions, certain less frequently used customized fields may be overridden by the default values after the Link flow has completed. If this occurs, retry the configuration using a non-OAuth institution.
Configuration object schema
Custom test accounts are configured with a JSON configuration object formulated according to the schema below. All top level fields are optional. Sending an empty object as a configuration will result in an account configured with random balances and transaction history.
version
seed
override_accounts
argument. If no seed is specified, the randomly generated data will be different each time.Note that transactions data is generated relative to the Item's creation date. Different Items created on different dates with the same seed for transactions data will have different dates for the transactions. The number of days between each transaction and the Item creation will remain constant. For example, an Item created on December 15 might show a transaction on December 14. An Item created on December 20, using the same seed, would show that same transaction occurring on December 19.
override_accounts
type
investment:
Investment account.credit:
Credit carddepository:
Depository accountloan:
Loan accountpayroll:
Payroll accountother:
Non-specified account typeSee the Account type schema for a full listing of account types and corresponding subtypes.
investment
, credit
, depository
, loan
, payroll
, other
subtype
401a
, 401k
, 403B
, 457b
, 529
, auto
, brokerage
, business
, cash isa
, cash management
, cd
, checking
, commercial
, construction
, consumer
, credit card
, crypto exchange
, ebt
, education savings account
, fixed annuity
, gic
, health reimbursement arrangement
, home equity
, hsa
, isa
, ira
, keogh
, lif
, life insurance
, line of credit
, lira
, loan
, lrif
, lrsp
, money market
, mortgage
, mutual fund
, non-custodial wallet
, non-taxable brokerage account
, other
, other insurance
, other annuity
, overdraft
, paypal
, payroll
, pension
, prepaid
, prif
, profit sharing plan
, rdsp
, resp
, retirement
, rlif
, roth
, roth 401k
, rrif
, rrsp
, sarsep
, savings
, sep ira
, simple ira
, sipp
, stock plan
, student
, thrift savings plan
, tfsa
, trust
, ugma
, utma
, variable annuity
starting_balance
double
force_available _balance
double
currency
meta
name
official_name
limit
double
mask
^$|^[A-Za-z0-9]{2,4}$
numbers
account
ach_routing
/transfer/capabilities/get
, set this to 322271627 to force a true
result.ach_wire_routing
eft_institution
eft_branch
.eft_branch
eft_institution
.international_bic
international_iban
.international_iban
account
, will also be used as the account number by default. Must be specified alongside international_bic
.bacs_sort_code
transactions
date_transacted
date_transacted
is not provided by the institution, a transaction date may be available in the authorized_date
field.date
date_posted
date
amount
double
description
currency
holdings
institution_price
double
institution_price_as _of
cost_basis
double
quantity
double
currency
iso_currency_code
or unofficial_currency_code
security
ticker_symbol
, cusip
, isin
, or sedol
) are required.isin
cusip
sedol
name
ticker_symbol
currency
iso_currency_code
or unofficial_currency_code
investment _transactions
name
quantity
double
price
double
fees
double
type
buy
: Buying an investment
sell
: Selling an investment
cash
: Activity that modifies a cash position
fee
: A fee on the account
transfer
: Activity that modifies a position, but not through buy/sell activity e.g. options exercise, portfolio transfercurrency
iso_currency_code
or unofficial_currency_code
security
ticker_symbol
, cusip
, isin
, or sedol
) are required.isin
cusip
sedol
name
ticker_symbol
currency
iso_currency_code
or unofficial_currency_code
identity
names
phone_numbers
emails
addresses
data
city
region
state
.
Example: "NC"
street
"564 Main Street, APT 15"
postal_code
zip
.country
primary
true
, identifies the address as the primary address on an account.liability
type
credit
or student
. Mortgages are not currently supported in the custom Sandbox.purchase_apr
type
is credit
.double
cash_apr
type
is credit
.double
balance_transfer_apr
type
is credit
.double
special_apr
type
is credit
.double
last_payment_amount
last_payment_amount
field. Can only be set if type
is credit
.double
minimum_payment_amount
minimum_payment_amount
field. Can only be set if type
is credit
or student
.double
is_overdue
is_overdue
fieldorigination_date
type
is student
.date
principal
type
is student
.double
nominal_apr
type
is student
.double
interest _capitalization_grace _period_months
type
is student
.repayment_model
type
standard
.non_repayment_months
repayment_months
expected_payoff_date
expected_payoff_date
field. Can only be set if type
is student
.date
guarantor
guarantor
field. Can only be set if type
is student
.is_federal
is_federal
field. Can only be set if type
is student
.loan_name
loan_name
field. Can only be set if type
is student
.loan_status
type
cancelled
, charged off
, claim
, consolidated
, deferment
, delinquent
, discharged
, extension
, forbearance
, in grace
, in military
, in school
, not fully disbursed
, other
, paid in full
, refunded
, repayment
, transferred
, pending idr
payment_reference _number
payment_reference_number
field. Can only be set if type
is student
.repayment_plan _description
repayment_plan.description
field. Can only be set if type
is student
.repayment_plan_type
repayment_plan.type
field. Can only be set if type
is student
. Possible values are: "extended graduated"
, "extended standard"
, "graduated"
, "income-contingent repayment"
, "income-based repayment"
, "income-sensitive repayment"
, "interest only"
, "other"
, "pay as you earn"
, "revised pay as you earn"
, "standard"
, or "saving on a valuable education"
.sequence_number
sequence_number
field. Can only be set if type
is student
.servicer_address
data
city
region
state
.
Example: "NC"
street
"564 Main Street, APT 15"
postal_code
zip
.country
primary
true
, identifies the address as the primary address on an account.inflow_model
inflow_model
allows you to model a test account that receives regular income or make regular payments on a loan. Any transactions generated by the inflow_model
will appear in addition to randomly generated test data or transactions specified by override_accounts
.type
none
: No incomemonthly-income
: Income occurs once per month monthly-balance-payment
: Pays off the balance on a liability account at the given statement day of month.monthly-interest-only-payment
: Makes an interest-only payment on a liability account at the given statement day of month.Note that account types supported by Liabilities will accrue interest in the Sandbox. The types impacted are account type
credit
with subtype credit
or paypal
, and account type loan
with subtype student
or mortgage
.income_amount
type
is monthly-income
.double
payment_day_of_month
last
meaning the last day of the month. The day of the month on which the income transaction will appear. The name of the income transaction. This field is required if type
is monthly-income
, monthly-balance-payment
or monthly-interest-only-payment
.transaction_name
type
is monthly-income
, monthly-balance-payment
or monthly-interest-only-payment
.statement_day_of_month
last
meaning the last day of the month. The day of the month on which the balance is calculated for the next payment. The name of the income transaction. This field is required if type
is monthly-balance-payment
or monthly-interest-only-payment
.income
paystubs
employer
employee
name
marital_status
single
or married
.single
, married
taxpayer_id
net_pay
description
currency
ytd_amount
double
deductions
breakdown
current_amount
double
description
currency
ytd_amount
double
total
current_amount
double
currency
ytd_amount
double
earnings
breakdown
canonical_description
BONUS
, COMMISSION
, OVERTIME
, PAID TIME OFF
, REGULAR PAY
, VACATION
, BASIC ALLOWANCE HOUSING
, BASIC ALLOWANCE SUBSISTENCE
, OTHER
, null
current_amount
double
description
hours
currency
rate
double
ytd_amount
double
total
hours
currency
ytd_amount
double
pay_period_details
check_amount
double
distribution_breakdown
account_name
bank_name
current_amount
double
currency
null
if unofficial_currency_code
is non-null.mask
type
gross_earnings
double
pay_frequency
PAY_FREQUENCY_UNKNOWN
, PAY_FREQUENCY_WEEKLY
, PAY_FREQUENCY_BIWEEKLY
, PAY_FREQUENCY_SEMIMONTHLY
, PAY_FREQUENCY_MONTHLY
, null
start_date
w2s
employer
employee
name
marital_status
single
or married
.single
, married
taxpayer_id
tax_year
employer_id_number
wages_tips_other_comp
federal_income_tax _withheld
social_security_wages
social_security_tax _withheld
medicare_wages_and _tips
medicare_tax_withheld
social_security_tips
allocated_tips
box_9
dependent_care _benefits
nonqualified_plans
statutory_employee
retirement_plan
third_party_sick_pay
other
state_and_local_wages
state
employer_state_id _number
state_wages_tips
state_income_tax
local_wages_tips
local_income_tax
locality_name
mfa
type
device
, selections
, or questions
.If value is
device
, the MFA answer is 1234
.If value is
selections
, the MFA answer is always the first option.If value is
questions
, the MFA answer is answer_<i>_<j>
for the j-th question in the i-th round, starting from 0. For example, the answer to the first question in the second round is answer_1_0
.question_rounds
type
is questions
.questions_per_round
type
is questions
. If value of type is selections
, default value is 2.selection_rounds
type
is selections
. Defaults to 1.selections_per _question
type
is selection
. Defaults to 2.recaptcha
good
or bad
. A value of good
will result in successful Item creation and bad
will result in a RECAPTCHA_BAD
error to simulate a failed reCAPTCHA. Both values require the reCAPTCHA to be manually solved within Plaid Link.force_error
"INSTITUTION_NOT_RESPONDING"
"INSTITUTION_NO_LONGER_SUPPORTED"
"INVALID_CREDENTIALS"
"INVALID_MFA"
"ITEM_LOCKED"
"ITEM_LOGIN_REQUIRED"
"ITEM_NOT_SUPPORTED"
"INVALID_LINK_TOKEN"
"MFA_NOT_SUPPORTED"
"NO_ACCOUNTS"
"PLAID_ERROR"
"USER_INPUT_TIMEOUT"
"USER_SETUP_REQUIRED"
1{2 "seed": "my-seed-string-3",3 "override_accounts": [4 {5 "type": "depository",6 "subtype": "checking",7 "identity": {8 "names": [9 "John Doe"10 ],11 "phone_numbers": [12 {13 "primary": true,14 "type": "home",15 "data": "4673956022"16 }17 ],18 "emails": [19 {20 "primary": true,21 "type": "primary",22 "data": "accountholder0@example.com"23 }24 ],25 "addresses": [26 {27 "primary": true,28 "data": {29 "city": "Malakoff",30 "region": "NY",31 "street": "2992 Cameron Road",32 "postal_code": "14236",33 "country": "US"34 }35 }36 ]37 },38 "transactions": [39 {40 "date_transacted": "2023-10-01",41 "date_posted": "2023-10-03",42 "currency": "USD",43 "amount": 100,44 "description": "1 year Netflix subscription"45 },46 {47 "date_transacted": "2023-10-01",48 "date_posted": "2023-10-02",49 "currency": "USD",50 "amount": 100,51 "description": "1 year mobile subscription"52 }53 ]54 },55 {56 "type": "loan",57 "subtype": "student",58 "liability": {59 "type": "student",60 "origination_date": "2023-01-01",61 "principal": 10000,62 "nominal_apr": 6.25,63 "loan_name": "Plaid Student Loan",64 "repayment_model": {65 "type": "standard",66 "non_repayment_months": 12,67 "repayment_months": 12068 }69 }70 },71 {72 "type": "credit",73 "subtype": "credit card",74 "starting_balance": 10000,75 "inflow_model": {76 "type": "monthly-interest-only-payment",77 "payment_day_of_month": 15,78 "statement_day_of_month": 13,79 "transaction_name": "Interest Payment"80 },81 "liability": {82 "type": "credit",83 "purchase_apr": 12.9,84 "balance_transfer_apr": 15.24,85 "cash_apr": 28.45,86 "special_apr": 0,87 "last_payment_amount": 500,88 "minimum_payment_amount": 1089 }90 },91 {92 "type": "investment",93 "subtype": "brokerage",94 "investment_transactions": [95 {96 "date": "2023-07-01",97 "name": "buy stock",98 "quantity": 10,99 "price": 10,100 "fees": 20,101 "type": "buy",102 "currency": "USD",103 "security": {104 "ticker_symbol": "PLAID",105 "currency": "USD"106 }107 }108 ],109 "holdings": [110 {111 "institution_price": 10,112 "institution_price_as_of": "2023-08-01",113 "cost_basis": 10,114 "quantity": 10,115 "currency": "USD",116 "security": {117 "ticker_symbol": "PLAID",118 "currency": "USD"119 }120 }121 ]122 },123 {124 "type": "payroll",125 "subtype": "payroll",126 "income": {127 "paystubs": [128 {129 "employer": {130 "name": "Heartland Toy Company"131 },132 "employee": {133 "name": "Chip Hazard",134 "address": {135 "city": "Burbank",136 "region": "CA",137 "street": "411 N Hollywood Way",138 "postal_code": "91505",139 "country": "US"140 }141 },142 "income_breakdown": [143 {144 "type": "regular",145 "rate": 20,146 "hours": 40,147 "total": 800148 },149 {150 "type": "overtime",151 "rate": 30,152 "hours": 6.68,153 "total": 200.39154 }155 ],156 "pay_period_details": {157 "start_date": "2021-05-04",158 "end_date": "2021-05-18",159 "gross_earnings": 1000.39,160 "check_amount": 499.28161 }162 }163 ]164 }165 }166 ]167}