Create Sandbox test data

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

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

string

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.

seed

string

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.

type

string

investment: Investment account.
credit: Credit card
depository: Depository account
loan: Loan account
payroll: Payroll 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, payroll, other

subtype

string

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, crypto exchange, education savings account, ebt, fixed annuity, gic, health reimbursement arrangement, hsa, isa, ira, lif, life insurance, lira, lrif, lrsp, non-custodial wallet, 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 equity, loan, mortgage, overdraft, line of credit, student, cash management, keogh, mutual fund, recurring, rewards, safe deposit, sarsep, payroll, null

starting_balance

number

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

Format: double

force_available_balance

number

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

currency

string

ISO-4217 currency code. If provided, the account will be denominated in the given currency. Transactions will also be in this currency by default.

meta

object

Allows specifying the metadata of the test account

name

string

The account's name

official_name

string

The account's official name

limit

number

The account's limit

Format: double

mask

string

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}$

numbers

object

Account and bank identifier number data used to configure the test account. All values are optional.

account

string

Will be used for the account number.

ach_routing

string

Must be a valid ACH routing number.

ach_wire_routing

string

Must be a valid wire transfer routing number.

eft_institution

string

EFT institution number. Must be specified alongside eft_branch.

eft_branch

string

EFT branch number. Must be specified alongside eft_institution.

international_bic

string

Bank identifier code (BIC). Must be specified alongside international_iban.

international_iban

string

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_code

string

BACS sort code

transactions

[object]

Specify the list of transactions on the account.

date_transacted

string

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_posted

string

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

amount

number

The transaction amount. Can be negative.

Format: double

description

string

The transaction description.

currency

string

The ISO-4217 format currency code for the transaction.

holdings

object

Specify the holdings on the account.

institution_price

number

The last price given by the institution for this security

Format: double

institution_price_as_of

string

The date at which institution_price was current. Must be formatted as an ISO 8601 date.

Format: date

cost_basis

number

The total cost basis of the holding (e.g., the total amount spent to acquire all assets currently in the holding).

Format: double

quantity

number

The total quantity of the asset held, as reported by the financial institution.

Format: double

vested_quantity

number

The total quantity of vested assets held, as reported by the financial institution. Vested assets are only associated with equities.

Format: double

vested_value

number

The value of the vested holdings as reported by the institution.

Format: double

currency

string

Either a valid iso_currency_code or unofficial_currency_code

security

object

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, isin, or sedol) are required.

isin

string

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.

cusip

string

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.

sedol

string

7-character SEDOL, an identifier assigned to securities in the UK.

name

string

A descriptive name for the security, suitable for display.

ticker_symbol

string

The security’s trading symbol for publicly traded securities, and otherwise a short identifier if available.

currency

string

Either a valid iso_currency_code or unofficial_currency_code

investment_transactions

object

Specify the list of investments transactions on the account.

date

string

Posting date for the transaction. Must be formatted as an ISO 8601 date.

Format: date

name

string

The institution's description of the transaction.

quantity

number

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

price

number

The price of the security at which this transaction occurred.

Format: double

fees

number

The combined value of all fees applied to this transaction.

Format: double

type

string

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 transfer

currency

string

Either a valid iso_currency_code or unofficial_currency_code

security

object

isin

string

cusip

string

sedol

string

7-character SEDOL, an identifier assigned to securities in the UK.

name

string

A descriptive name for the security, suitable for display.

ticker_symbol

string

The security’s trading symbol for publicly traded securities, and otherwise a short identifier if available.

currency

string

Either a valid iso_currency_code or unofficial_currency_code

identity

object

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.

data

string

The phone number.

primary

boolean

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

type

string

The type of phone number.

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

emails

[object]

A list of email addresses associated with the account.

data

string

The email address.

primary

boolean

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

type

string

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.

data

object

Data about the components comprising an address.

city

string

The full city name

region

string

The region or state. In API versions 2018-05-22 and earlier, this field is called state. Example: "NC"

street

string

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

postal_code

string

The postal code. In API versions 2018-05-22 and earlier, this field is called zip.

country

string

The ISO 3166-1 alpha-2 country code

primary

boolean

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

liability

object

Used to configure Sandbox test data for the Liabilities product

type

string

The type of the liability object, either credit or student. Mortgages are not currently supported in the custom Sandbox.

purchase_apr

number

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_apr

number

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

Format: double

balance_transfer_apr

number

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

Format: double

special_apr

number

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

Format: double

last_payment_amount

number

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

Format: double

minimum_payment_amount

number

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

Format: double

is_overdue

boolean

Override the is_overdue field

origination_date

string

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

principal

number

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

Format: double

nominal_apr

number

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

Format: double

interest_capitalization_grace_period_months

number

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_model

object

Student loan repayment information used to configure Sandbox test data for the Liabilities product

type

string

The only currently supported value for this field is standard.

non_repayment_months

number

Configures the number of months before repayment starts.

repayment_months

number

Configures the number of months of repayments before the loan is paid off.

expected_payoff_date

string

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

Format: date

guarantor

string

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

is_federal

boolean

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

loan_name

string

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

loan_status

object

An object representing the status of the student loan

end_date

string

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

Format: date

type

string

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 idr

payment_reference_number

string

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

pslf_status

object

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_date

string

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

Format: date

payments_made

integer

The number of qualifying payments that have been made.

payments_remaining

integer

The number of qualifying payments remaining.

repayment_plan_description

string

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

repayment_plan_type

string

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", "standard", or "saving on a valuable education".

sequence_number

string

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

servicer_address

object

A physical mailing address.

data

object

Data about the components comprising an address.

city

string

The full city name

region

string

The region or state. In API versions 2018-05-22 and earlier, this field is called state. Example: "NC"

street

string

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

postal_code

string

The postal code. In API versions 2018-05-22 and earlier, this field is called zip.

country

string

The ISO 3166-1 alpha-2 country code

primary

boolean

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

inflow_model

object

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.

type

string

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 impacted are account type credit with subtype credit or paypal, and account type loan with subtype student or mortgage.

income_amount

number

Amount of income per month. This value is required if type is monthly-income.

Format: double

payment_day_of_month

number

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_name

string

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_month

string

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.

income

object

Specify payroll data on the account.

paystubs

[object]

A list of paystubs associated with the account.

employer

object

The employer on the paystub.

name

string

The name of the employer.

employee

object

The employee on the paystub.

name

string

The name of the employee.

address

object

The address of the employee.

city

string

The full city name.

region

string

The region or state Example: "NC"

street

string

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

postal_code

string

5 digit postal code.

country

string

The country of the address.

income_breakdown

[object]

type

string

The type of income. Possible values include: "regular": regular income "overtime": overtime income "bonus": bonus income

Possible values: bonus, overtime, regular, null

rate

number

The hourly rate at which the income is paid.

Format: double

hours

number

The number of hours logged for this income for this pay period.

total

number

The total pay for this pay period.

Format: double

pay_period_details

object

Details about the pay period.

check_amount

number

The amount of the paycheck.

Format: double

distribution_breakdown

[object]

account_name

string

Name of the account for the given distribution.

bank_name

string

The name of the bank that the payment is being deposited to.

current_amount

number

The amount distributed to this account.

Format: double

currency

string

The ISO-4217 currency code of the net pay. Always null if unofficial_currency_code is non-null.

mask

string

The last 2-4 alphanumeric characters of an account's official account number.

type

string

Type of the account that the paystub was sent to (e.g. 'checking').

end_date

string

The pay period end date, in ISO 8601 format: "yyyy-mm-dd".

Format: date

gross_earnings

number

Total earnings before tax/deductions.

Format: double

pay_date

string

The date on which the paystub was issued, in ISO 8601 format ("yyyy-mm-dd").

Format: date

pay_frequency

string

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, null

pay_day

deprecatedstring

The date on which the paystub was issued, in ISO 8601 format ("yyyy-mm-dd").

Format: date

start_date

string

The pay period start date, in ISO 8601 format: "yyyy-mm-dd".

Format: date

mfa

object

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

type

string

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_rounds

number

Number of rounds of questions. Required if value of type is questions.

questions_per_round

number

Number of questions per round. Required if value of type is questions. If value of type is selections, default value is 2.

selection_rounds

number

Number of rounds of selections, used if type is selections. Defaults to 1.

selections_per_question

number

Number of available answers per question, used if type is selection. Defaults to 2.

recaptcha

string

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_error

string

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{
"seed": "my-seed-string-3",
"override_accounts": [
  {
    "type": "depository",
    "subtype": "checking",
    "identity": {
      "names": [
        "John Doe"
      ],
      "phone_numbers": [
        {
          "primary": true,
          "type": "home",
          "data": "4673956022"
        }
      ],
      "emails": [
        {
          "primary": true,
          "type": "primary",
          "data": "accountholder0@example.com"
        }
      ],
      "addresses": [
        {
          "primary": true,
          "data": {
            "city": "Malakoff",
            "region": "NY",
            "street": "2992 Cameron Road",
            "postal_code": "14236",
            "country": "US"
          }
        }
      ]
    },
    "transactions": [
      {
        "date_transacted": "2023-10-01",
        "date_posted": "2023-10-03",
        "currency": "USD",
        "amount": 100,
        "description": "1 year Netflix subscription"
      },
      {
        "date_transacted": "2023-10-01",
        "date_posted": "2023-10-02",
        "currency": "USD",
        "amount": 100,
        "description": "1 year mobile subscription"
      }
    ]
  },
  {
    "type": "loan",
    "subtype": "student",
    "liability": {
      "type": "student",
      "origination_date": "2023-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
    }
  },
  {
    "type": "investment",
    "subtype": "brokerage",
    "investment_transactions": [
      {
        "date": "2023-07-01",
        "name": "buy stock",
        "quantity": 10,
        "price": 10,
        "fees": 20,
        "type": "buy",
        "currency": "USD",
        "security": {
          "ticker_symbol": "PLAID",
          "currency": "USD"
        }
      }
    ],
    "holdings": [
      {
        "institution_price": 10,
        "institution_price_as_of": "2023-08-01",
        "cost_basis": 10,
        "quantity": 10,
        "currency": "USD",
        "security": {
          "ticker_symbol": "PLAID",
          "currency": "USD"
        }
      }
    ]
  },
  {
    "type": "payroll",
    "subtype": "payroll",
    "income": {
      "paystubs": [
        {
          "employer": {
            "name": "Heartland Toy Company"
          },
          "employee": {
            "name": "Chip Hazard",
            "address": {
              "city": "Burbank",
              "region": "CA",
              "street": "411 N Hollywood Way",
              "postal_code": "91505",
              "country": "US"
            }
          },
          "income_breakdown": [
            {
              "type": "regular",
              "rate": 20,
              "hours": 40,
              "total": 800
            },
            {
              "type": "overtime",
              "rate": 30,
              "hours": 6.68,
              "total": 200.39
            }
          ],
          "pay_period_details": {
            "start_date": "2021-05-04",
            "end_date": "2021-05-18",
            "gross_earnings": 1000.39,
            "check_amount": 499.28
          }
        }
      ]
    }
  }
]
167}

Create Sandbox test data

Use Sandbox accounts to create rich test data for Plaid products

Customize Sandbox account data

Configuring the custom user account

Configuration object schema

Was this helpful?