Create Sandbox test data

Learn how to use Sandbox accounts to create rich test data for Plaid products

Customize Sandbox account data

In addition to the basic Sandbox credentials, 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, Liabilities, and Transactions products. You can also simulate an account with regular income or that makes regular loan payments. For Link testing, custom accounts support multi-factor authentication, reCAPTCHA, and Link error flows.

Configuring the custom user account

Custom user accounts can be configured and accessed in one of two ways. The easiest, and recommended, method is to use the Sandbox Users tool, located on the Dashboard under the Team menu. Set the username and configuration object on the Dashboard, then use any non-empty password when logging in to Sandbox with the username. Alternatively, you can log in to Sandbox with the username user_custom and provide the configuration object as the password when logging in.

Configuration object schema

Custom test accounts are configured with a JSON configuration object formulated according to the schema below. All fields are optional. Sending an empty object as a configuration will result in an account configured with random balances and transaction history.

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 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 card
depository: Depository account
loan: Loan account
other: Non-specified account type
See the Account type schema for a full listing of account types and corresponding subtypes.

Possible values: investment, credit, depository, loan, other

subtypestring

See the Account type schema for a full listing of account types and corresponding subtypes.

Possible values: 401a, 401k, 403B, 457b, 529, brokerage, cash isa, education savings account, ebt, gic, health reimbursement arrangement, hsa, isa, ira, lif, life insurance, lira, lrif, lrsp, non-taxable brokerage account, other, other insurance, other annuity, prif, rdsp, resp, rlif, rrif, pension, profit sharing plan, retirement, roth, roth 401k, rrsp, sep ira, simple ira, sipp, stock plan, thrift savings plan, tfsa, trust, ugma, utma, variable annuity, credit card, paypal, cd, checking, savings, money market, prepaid, auto, business, commercial, construction, consumer, home, home equity, loan, mortgage, overdraft, line of credit, student, cash management, keogh, mutual fund, recurring, rewards, safe deposit, sarsep, null

starting_balancenumber

If provided, the account will start with this amount as the current balance.

force_available_balancenumber

If provided, the account will always have this amount as its available balance, regardless of current balance or changes in transactions over time.

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

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.

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 ISO8601 (YYYY-MM-DD) format. Transaction dates in the past or present will result in posted transactions; transaction dates in the future will result in pending transactions. Transactions in Sandbox will move from pending to posted once their transaction date has been reached.

date_postedstring

The date the transaction posted, in ISO8601 (YYYY-MM-DD) format

amountnumber

The transaction amount. Can be negative.

descriptionstring

The transaction description.

currencystring

The ISO-4217 format currency code for the transaction.

identityobject

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.

datastring

The phone number.

primaryboolean

When true, identifies the phone number as the primary number on an account.

typestring

The type of phone number.

Possible values: home, work, office, mobile, mobile1, other

emails[object]

A list of email addresses associated with the account.

datastring

The email address.

primaryboolean

When true, identifies the email address as the primary email on an account.

typestring

The type of email account as described by the financial institution.

Possible values: primary, secondary, other

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 Example: "NC"

streetstring

The full street address Example: "564 Main Street, APT 15"

postal_codestring

The postal code

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.

cash_aprnumber

The cash APR percentage value. Can only be set if type is credit.

balance_transfer_aprnumber

The balance transfer APR percentage value. Can only be set if type is credit. Can only be set if type is credit.

special_aprnumber

The special APR percentage value. Can only be set if type is credit.

last_payment_amountnumber

Override the last_payment_amount field. Can only be set if type is credit.

minimum_payment_amountnumber

Override the minimum_payment_amount field. Can only be set if type is credit or student.

is_overdueboolean

Override the is_overdue field

origination_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.

principalnumber

The original loan principal. Can only be set if type is student.

nominal_aprnumber

The interest rate on the loan as a percentage. Can only be set if type is student.

interest_capitalization_grace_period_monthsnumber

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.

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

end_datestring

The date until which the loan will be in its current status. Dates are returned in an ISO 8601 format (YYYY-MM-DD).

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

payment_reference_numberstring

Override the payment_reference_number field. Can only be set if type is student.

pslf_statusobject

Information about the student's eligibility in the Public Service Loan Forgiveness program. This is only returned if the institution is Fedloan (ins_116527).

estimated_eligibility_datestring

The estimated date borrower will have completed 120 qualifying monthly payments. Returned in ISO 8601 format (YYYY-MM-DD).

payments_madenumber

The number of qualifying payments that have been made.

payments_remainingnumber

The number of qualifying payments remaining.

repayment_plan_descriptionstring

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", "interest only", "other", "pay as you earn", "revised pay as you earn", or "standard".

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 Example: "NC"

streetstring

The full street address Example: "564 Main Street, APT 15"

postal_codestring

The postal code

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:
none: No income monthly-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 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.

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.

mfaobject

Specifies the multi-factor authentication settings to use with this test account

typestring

Possible values are 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_per_questionnumber

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" "PRODUCTS_NOT_SUPPORTED" "USER_SETUP_REQUIRED"

 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
{
  "override_accounts": [
    {
      "type": "depository",
      "subtype": "checking",
      "transactions": [
        {
          "date_transacted": "2019-10-01",
          "date_posted": "2019-10-03",
          "currency": "USD",
          "amount": 100,
          "description": "1 year Netflix subscription"
        },
        {
          "date_transacted": "2019-10-01",
          "date_posted": "2019-10-02",
          "currency": "USD",
          "amount": 100,
          "description": "1 year mobile subscription"
        }
      ]
    },
    {
      "type": "loan",
      "subtype": "student",
      "liability": {
        "type": "student",
        "origination_date": "2020-01-01",
        "principal": 10000,
        "nominal_apr": 6.25,
        "loan_name": "Plaid Student Loan",
        "repayment_model": {
          "type": "standard",
          "non_repayment_months": 12,
          "repayment_months": 120
        }
      }
    },
    {
      "type": "credit",
      "subtype": "credit card",
      "starting_balance": 10000,
      "inflow_model": {
        "type": "monthly-interest-only-payment",
        "payment_day_of_month": 15,
        "statement_day_of_month": 13,
        "transaction_name": "Interest Payment"
      },
      "liability": {
        "type": "credit",
        "purchase_apr": 12.9,
        "balance_transfer_apr": 15.24,
        "cash_apr": 28.45,
        "special_apr": 0,
        "last_payment_amount": 500,
        "minimum_payment_amount": 10
      }
    }
  ]
}