Create Sandbox test data
Use Sandbox accounts to create rich test data for Plaid products
Prefer to learn by watching? Check out this quick video guide to Custom Sandbox Users
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.
Limitations of the custom user account
Very large configuration objects (larger than approximately 55kb, or approximately 250 transactions) are not supported and may cause the Link attempt to fail.
Using more than ten accounts on a single custom user is not supported and will cause the Link attempt to fail.
If you are using Consumer Report by Plaid Check, to use a custom user, you must click "add new account" in the Link flow rather than using one of the existing banks. Using an existing bank in the Plaid Passport flow will skip the ability to enter a custom username.
At OAuth institutions, custom users may not work properly: certain less frequently used customized fields may be overridden by the default values after the Link flow has completed, or the login may fail. If this occurs, retry the configuration using a non-OAuth institution, such as First Gingham Credit Union or First Platypus Bank.
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.
Properties
versionstring
The version of the password schema to use, possible values are 1 or 2. The default value is 2. You should only specify 1 if you know it is necessary for your test suite.
seedstring
A seed, in the form of a string, that will be used to randomly generate account and transaction data, if this data is not specified using the
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 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[object]
An array of account overrides to configure the accounts for the Item. By default, if no override is specified, transactions and account data will be randomly generated based on the account type and subtype, and other products will have fixed or empty data.
typestring
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.
Possible values:
investment, credit, depository, loan, payroll, othersubtypestring
See the Account type schema for a full listing of account types and corresponding subtypes.
Possible values:
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 annuitystarting_balancenumber
If provided, the account will start with this amount as the current balance.
Format:
double force_availablenumber
If provided, the account will always have this amount as its available balance, regardless of current balance or changes in transactions over time.
Format:
double currencystring
ISO-4217 currency code. If provided, the account will be denominated in the given currency. Transactions will also be in this currency by default.
metaobject
Allows specifying the metadata of the test account
namestring
The account's name
official_namestring
The account's official name
limitnumber
The account's limit
Format:
double maskstring
The account's mask. Should be an empty string or a string of 2-4 alphanumeric characters. This allows you to model a mask which does not match the account number (such as with a virtual account number).
Pattern:
^$|^[A-Za-z0-9]{2,4}$ numbersobject
Account and bank identifier number data used to configure the test account. All values are optional.
accountstring
Will be used for the account number.
ach_routingstring
Must be a valid ACH routing number. To test
/transfer/capabilities/get, set this to 322271627 to force a true result.ach_wire_routingstring
Must be a valid wire transfer routing number.
eft_institutionstring
EFT institution number. Must be specified alongside
eft_branch.eft_branchstring
EFT branch number. Must be specified alongside
eft_institution.international_bicstring
Bank identifier code (BIC). Must be specified alongside
international_iban.international_ibanstring
International bank account number (IBAN). If no account number is specified via
account, will also be used as the account number by default. Must be specified alongside international_bic.bacs_sort_codestring
BACS sort code
transactions[object]
Specify the list of transactions on the account.
date_transactedstring
The date of the transaction, in ISO 8601 (YYYY-MM-DD) format. Transactions in Sandbox will move from pending to posted once their transaction date has been reached. If a
date_transacted is not provided by the institution, a transaction date may be available in the authorized_date field.Format:
date date_postedstring
The date the transaction posted, in ISO 8601 (YYYY-MM-DD) format. Posted dates in the past or present will result in posted transactions; posted dates in the future will result in pending transactions.
Format:
date amountnumber
The transaction amount. Can be negative.
Format:
double descriptionstring
The transaction description.
currencystring
The ISO-4217 format currency code for the transaction.
holdingsobject
Specify the holdings on the account.
institution_pricenumber
The last price given by the institution for this security
Format:
double institution_price_asstring
cost_basisnumber
The total cost basis of the holding (e.g., the total amount spent to acquire all assets currently in the holding).
Format:
double quantitynumber
The total quantity of the asset held, as reported by the financial institution.
Format:
double currencystring
Either a valid
iso_currency_code or unofficial_currency_codesecurityobject
Specify the security associated with the holding or investment transaction. When inputting custom security data to the Sandbox, Plaid will perform post-data-retrieval normalization and enrichment. These processes may cause the data returned by the Sandbox to be slightly different from the data you input. An ISO-4217 currency code and a security identifier (
ticker_symbol, cusip, or isin) are required.isinstring
12-character ISIN, a globally unique securities identifier. A verified CUSIP Global Services license is required to receive this data. This field will be null by default for new customers, and null for existing customers starting March 12, 2024. If you would like access to this field, please request ISIN/CUSIP access here.
cusipstring
9-character CUSIP, an identifier assigned to North American securities. A verified CUSIP Global Services license is required to receive this data. This field will be null by default for new customers, and null for existing customers starting March 12, 2024. If you would like access to this field, please request ISIN/CUSIP access here.
namestring
A descriptive name for the security, suitable for display.
ticker_symbolstring
The security’s trading symbol for publicly traded securities, and otherwise a short identifier if available.
currencystring
Either a valid
iso_currency_code or unofficial_currency_codeinvestmentobject
Specify the list of investments transactions on the account.
namestring
The institution's description of the transaction.
quantitynumber
The number of units of the security involved in this transaction. Must be positive if the type is a buy and negative if the type is a sell.
Format:
double pricenumber
The price of the security at which this transaction occurred.
Format:
double feesnumber
The combined value of all fees applied to this transaction.
Format:
double typestring
The type of the investment transaction. Possible values are:
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 transfercurrencystring
Either a valid
iso_currency_code or unofficial_currency_codesecurityobject
Specify the security associated with the holding or investment transaction. When inputting custom security data to the Sandbox, Plaid will perform post-data-retrieval normalization and enrichment. These processes may cause the data returned by the Sandbox to be slightly different from the data you input. An ISO-4217 currency code and a security identifier (
ticker_symbol, cusip, or isin) are required.isinstring
12-character ISIN, a globally unique securities identifier. A verified CUSIP Global Services license is required to receive this data. This field will be null by default for new customers, and null for existing customers starting March 12, 2024. If you would like access to this field, please request ISIN/CUSIP access here.
cusipstring
9-character CUSIP, an identifier assigned to North American securities. A verified CUSIP Global Services license is required to receive this data. This field will be null by default for new customers, and null for existing customers starting March 12, 2024. If you would like access to this field, please request ISIN/CUSIP access here.
namestring
A descriptive name for the security, suitable for display.
ticker_symbolstring
The security’s trading symbol for publicly traded securities, and otherwise a short identifier if available.
currencystring
Either a valid
iso_currency_code or unofficial_currency_codeidentityobject
Data about the owner or owners of an account. Any fields not specified will be filled in with default Sandbox information.
names[string]
A list of names associated with the account by the financial institution. These should always be the names of individuals, even for business accounts. Note that the same name data will be used for all accounts associated with an Item.
phone_numbers[object]
A list of phone numbers associated with the account.
emails[object]
A list of email addresses associated with the account.
addresses[object]
Data about the various addresses associated with the account.
dataobject
Data about the components comprising an address.
citystring
The full city name
regionstring
The region or state. In API versions 2018-05-22 and earlier, this field is called
state.
Example: "NC"streetstring
The full street address
Example:
"564 Main Street, APT 15"postal_codestring
The postal code. In API versions 2018-05-22 and earlier, this field is called
zip.countrystring
The ISO 3166-1 alpha-2 country code
primaryboolean
When
true, identifies the address as the primary address on an account.liabilityobject
Used to configure Sandbox test data for the Liabilities product
typestring
The type of the liability object, either
credit or student. Mortgages are not currently supported in the custom Sandbox.purchase_aprnumber
The purchase APR percentage value. For simplicity, this is the only interest rate used to calculate interest charges. Can only be set if
type is credit.Format:
double cash_aprnumber
The cash APR percentage value. Can only be set if
type is credit.Format:
double balance_transfer_aprnumber
The balance transfer APR percentage value. Can only be set if
type is credit.Format:
double special_aprnumber
The special APR percentage value. Can only be set if
type is credit.Format:
double last_payment_amountnumber
Override the
last_payment_amount field. Can only be set if type is credit.Format:
double minimum_payment_amountnumber
Override the
minimum_payment_amount field. Can only be set if type is credit or student.Format:
double is_overdueboolean
Override the
is_overdue fieldorigination_datestring
The date on which the loan was initially lent, in ISO 8601 (YYYY-MM-DD) format. Can only be set if
type is student.Format:
date principalnumber
The original loan principal. Can only be set if
type is student.Format:
double nominal_aprnumber
The interest rate on the loan as a percentage. Can only be set if
type is student.Format:
double interestnumber
If set, interest capitalization begins at the given number of months after loan origination. By default interest is never capitalized. Can only be set if
type is student.repayment_modelobject
Student loan repayment information used to configure Sandbox test data for the Liabilities product
typestring
The only currently supported value for this field is
standard.non_repayment_monthsnumber
Configures the number of months before repayment starts.
repayment_monthsnumber
Configures the number of months of repayments before the loan is paid off.
expected_payoff_datestring
Override the
expected_payoff_date field. Can only be set if type is student.Format:
date guarantorstring
Override the
guarantor field. Can only be set if type is student.is_federalboolean
Override the
is_federal field. Can only be set if type is student.loan_namestring
Override the
loan_name field. Can only be set if type is student.loan_statusobject
An object representing the status of the student loan
typestring
The status type of the student loan
Possible values:
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 idrpayment_referencestring
Override the
payment_reference_number field. Can only be set if type is student.repayment_planstring
Override the
repayment_plan.description field. Can only be set if type is student.repayment_plan_typestring
Override the
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_numberstring
Override the
sequence_number field. Can only be set if type is student.servicer_addressobject
A physical mailing address.
dataobject
Data about the components comprising an address.
citystring
The full city name
regionstring
The region or state. In API versions 2018-05-22 and earlier, this field is called
state.
Example: "NC"streetstring
The full street address
Example:
"564 Main Street, APT 15"postal_codestring
The postal code. In API versions 2018-05-22 and earlier, this field is called
zip.countrystring
The ISO 3166-1 alpha-2 country code
primaryboolean
When
true, identifies the address as the primary address on an account.inflow_modelobject
The
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.typestring
Inflow model. One of the following:
Note that account types supported by Liabilities will accrue interest in the Sandbox. The types impacted are account 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_amountnumber
Amount of income per month. This value is required if
type is monthly-income.Format:
double payment_day_of_monthnumber
Number between 1 and 28, or
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_namestring
The name of the income transaction. This field is required if
type is monthly-income, monthly-balance-payment or monthly-interest-only-payment.statement_day_of_monthstring
Number between 1 and 28, or
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.incomeobject
Specify payroll data on the account.
paystubs[object]
A list of paystubs associated with the account.
employerobject
The employer on the paystub.
employeeobject
The employee on the paystub.
namestring
The name of the employee.
marital_statusstring
Marital status of the employee - either
single or married.Possible values:
single, marriedtaxpayer_idobject
Taxpayer ID of the individual receiving the paystub.
net_payobject
An object representing information about the net pay amount on the paystub.
descriptionstring
Description of the net pay
currencystring
The ISO-4217 currency code of the net pay.
ytd_amountnumber
The year-to-date amount of the net pay
Format:
double deductionsobject
An object with the deduction information found on a paystub.
breakdown[object]
current_amountnumber
Raw amount of the deduction
Format:
double descriptionstring
Description of the deduction line item
currencystring
The ISO-4217 currency code of the line item.
ytd_amountnumber
The year-to-date amount of the deduction
Format:
double totalobject
An object representing the total deductions for the pay period
current_amountnumber
Raw amount of the deduction
Format:
double currencystring
The ISO-4217 currency code of the line item.
ytd_amountnumber
The year-to-date total amount of the deductions
Format:
double earningsobject
An object representing both a breakdown of earnings on a paystub and the total earnings.
breakdown[object]
canonical_descriptionstring
Commonly used term to describe the earning line item.
Possible values:
BONUS, COMMISSION, OVERTIME, PAID TIME OFF, REGULAR PAY, VACATION, BASIC ALLOWANCE HOUSING, BASIC ALLOWANCE SUBSISTENCE, OTHER, nullcurrent_amountnumber
Raw amount of the earning line item.
Format:
double descriptionstring
Description of the earning line item.
hoursnumber
Number of hours applicable for this earning.
currencystring
The ISO-4217 currency code of the line item.
ratenumber
Hourly rate applicable for this earning.
Format:
double ytd_amountnumber
The year-to-date amount of the deduction.
Format:
double totalobject
An object representing both the current pay period and year to date amount for an earning category.
hoursnumber
Total number of hours worked for this pay period
currencystring
The ISO-4217 currency code of the line item
ytd_amountnumber
The year-to-date amount for the total earnings
Format:
double pay_period_detailsobject
Details about the pay period.
check_amountnumber
The amount of the paycheck.
Format:
double distribution_breakdown[object]
account_namestring
Name of the account for the given distribution.
bank_namestring
The name of the bank that the payment is being deposited to.
current_amountnumber
The amount distributed to this account.
Format:
double currencystring
The ISO-4217 currency code of the net pay. Always
null if unofficial_currency_code is non-null.maskstring
The last 2-4 alphanumeric characters of an account's official account number.
typestring
Type of the account that the paystub was sent to (e.g. 'checking').
gross_earningsnumber
Total earnings before tax/deductions.
Format:
double pay_frequencystring
The frequency at which an individual is paid.
Possible values:
PAY_FREQUENCY_UNKNOWN, PAY_FREQUENCY_WEEKLY, PAY_FREQUENCY_BIWEEKLY, PAY_FREQUENCY_SEMIMONTHLY, PAY_FREQUENCY_MONTHLY, nullstart_datestring
w2s[object]
A list of w2s associated with the account.
employerobject
The employer on the paystub.
employeeobject
The employee on the paystub.
namestring
The name of the employee.
marital_statusstring
Marital status of the employee - either
single or married.Possible values:
single, marriedtaxpayer_idobject
Taxpayer ID of the individual receiving the paystub.
tax_yearstring
The tax year of the W2 document.
employer_id_numberstring
An employer identification number or EIN.
wages_tips_other_compstring
Wages from tips and other compensation.
federal_income_taxstring
Federal income tax withheld for the tax year.
social_security_wagesstring
Wages from social security.
social_security_taxstring
Social security tax withheld for the tax year.
medicare_wages_andstring
Wages and tips from medicare.
medicare_tax_withheldstring
Medicare tax withheld for the tax year.
social_security_tipsstring
Tips from social security.
allocated_tipsstring
Allocated tips.
box_9string
Contents from box 9 on the W2.
dependent_carestring
Dependent care benefits.
nonqualified_plansstring
Nonqualified plans.
statutory_employeestring
Statutory employee.
retirement_planstring
Retirement plan.
third_party_sick_paystring
Third party sick pay.
otherstring
Other.
state_and_local_wages[object]
statestring
State associated with the wage.
employer_state_idstring
State identification number of the employer.
state_wages_tipsstring
Wages and tips from the specified state.
state_income_taxstring
Income tax from the specified state.
local_wages_tipsstring
Wages and tips from the locality.
local_income_taxstring
Income tax from the locality.
locality_namestring
Name of the locality.
mfaobject
Specifies the multi-factor authentication settings to use with this test account
typestring
Possible values are
If value is
If value is
If value is
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_roundsnumber
Number of rounds of questions. Required if value of
type is questions.questions_per_roundnumber
Number of questions per round. Required if value of
type is questions. If value of type is selections, default value is 2.selection_roundsnumber
Number of rounds of selections, used if
type is selections. Defaults to 1.selections_pernumber
Number of available answers per question, used if
type is selection. Defaults to 2.recaptchastring
You may trigger a reCAPTCHA in Plaid Link in the Sandbox environment by using the recaptcha field. Possible values are
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_errorstring
An error code to force on Item creation. Possible values are:
"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}