Sandbox endpoints

API reference for Plaid Sandbox-specific endpoints

Introduction

The Sandbox environment provides a number of endpoints to enable testing workflows. These endpoints are unique to Sandbox and cannot be used in Development or Production. For more information on using these endpoints, see the Sandbox.

/sandbox/public_token/create

Create a test Item

Use the /sandbox/public_token/create endpoint to create a valid public_token for an arbitrary institution ID, initial products, and test credentials. The created public_token maps to a new Sandbox Item. You can then call /item/public_token/exchange to exchange the public_token for an access_token and perform all API actions. /sandbox/public_token/create can also be used with the user_custom test username to generate a test account with custom data.

sandbox/public_token/create

Request fields and example

client_idstring
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secretstring
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
institution_idrequiredstring
The ID of the institution the Item will be associated with
initial_productsrequired[string]
The products to initially pull for the Item. May be any products that the specified institution_id supports. This array may not be empty.
Min items: 1
Possible values: assets, auth, balance, identity, investments, liabilities, payment_initiation, transactions, credit_details, income, deposit_switch, standing_orders
optionsobject
An optional set of options to be used when configuring the Item. If specified, must not be null.
webhookstring
Specify a webhook to associate with the new Item.
override_usernamestring
Test username to use for the creation of the Sandbox Item. Default value is user_good.
Default: user_good
override_passwordstring
Test password to use for the creation of the Sandbox Item. Default value is pass_good.
Default: pass_good
transactionsobject
SandboxPublicTokenCreateRequestOptionsTransactions is an optional set of corresponding to transactions options.
start_datestring
The earliest date for which to fetch transaction history. Dates should be formatted as YYYY-MM-DD.
end_datestring
The most recent date for which to fetch transaction history. Dates should be formatted as YYYY-MM-DD.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
try {
const publicTokenResponse = await client.sandboxPublicTokenCreate(
institutionID,
initialProducts,
);
const publicToken = publicTokenResponse.public_token;
// The generated public_token can now be exchanged
// for an access_token
const exchangeTokenResponse = await client.exchangePublicToken(publicToken);
const accessToken = exchangeTokenResponse.access_token;
} catch (err) {
// handle error
}
sandbox/public_token/create

Response fields and example

public_tokenstring
A public token that can be exchanged for an access token using /item/public_token/exchange
request_idstring
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1
2
3
4
{
"public_token": "public-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d",
"request_id": "Aim3b"
}

/sandbox/item/reset_login

Force a Sandbox Item into an error state

/sandbox/item/reset_login/ forces an Item into an ITEM_LOGIN_REQUIRED state in order to simulate an Item whose login is no longer valid. This makes it easy to test Link's update mode flow in the Sandbox environment. After calling /sandbox/item/reset_login, You can then use Plaid Link update mode to restore the Item to a good state. An ITEM_LOGIN_REQUIRED webhook will also be fired after a call to this endpoint, if one is associated with the Item.
In the Sandbox, Items will transition to an ITEM_LOGIN_REQUIRED error state automatically after 30 days, even if this endpoint is not called.

sandbox/item/reset_login

Request fields and example

client_idstring
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secretstring
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
access_tokenrequiredstring
The access token associated with the Item data is being requested for.
1
2
3
4
5
6
7
8
9
10
11
12
const resetLoginResponse = await client.resetLogin(accessToken).catch((err) => {
// handle error
});
// create a public_token for the Item and use it to
// initialize Link in update mode.
const publicTokenResponse = await client
.createPublicToken(access_token)
.catch((err) => {
// handle error
});
const publicToken = publicTokenResponse.public_token;
sandbox/item/reset_login

Response fields and example

reset_loginboolean
true if the call succeeded
request_idstring
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1
2
3
4
{
"reset_login": true,
"request_id": "m8MDnv9okwxFNBV"
}

/sandbox/item/set_verification_status

Set verification status for Sandbox account

The /sandbox/item/set_verification_status endpoint can be used to change the verification status of an Item in in the Sandbox in order to simulate the Automated Micro-deposit flow.
Note that not all Plaid developer accounts are enabled for micro-deposit based verification by default. Your account must be enabled for this feature in order to test it in Sandbox. To enable this features or check your status, contact your account manager or submit a product access Support ticket.
For more information on testing Automated Micro-deposits in Sandbox, see Auth full coverage testing.

sandbox/item/set_verification_status

Request fields and example

client_idstring
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secretstring
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
access_tokenrequiredstring
The access token associated with the Item data is being requested for.
account_idrequiredstring
The account_id of the account whose verification status is to be modified
verification_statusrequiredstring
The verification status to set the account to.
Possible values: automatically_verified, verification_expired
1
2
3
4
5
6
7
8
9
10
11
12
13
const response = await client
.sandboxItemSetVerificationStatus(accessToken, accountID, verificationStatus)
.catch((err) => {
// handle error
});
// create a public_token for the Item and use it to
// initialize Link in update mode.
const publicTokenResponse = await client
.createPublicToken(accessToken)
.catch((err) => {
// handle error
});
sandbox/item/set_verification_status

Response fields and example

request_idstring
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1
2
3
{
"request_id": "1vwmF5TBQwiqfwP"
}

/sandbox/item/fire_webhook

Fire a test webhook

The /sandbox/item/fire_webhook endpoint is used to test that code correctly handles webhooks. Calling this endpoint triggers a Transactions DEFAULT_UPDATE webhook to be fired for a given Sandbox Item. If the Item does not support Transactions, a SANDBOX_PRODUCT_NOT_ENABLED error will result.

sandbox/item/fire_webhook

Request fields and example

client_idstring
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secretstring
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
access_tokenrequiredstring
The access token associated with the Item data is being requested for.
webhook_coderequiredstring
The following values for webhook_code are supported:
  • DEFAULT_UPDATE

Possible values: DEFAULT_UPDATE
1
2
3
4
5
6
// Fire a DEFAULT_UPDATE webhook for an Item
const response = await client
.sandboxItemFireWebhook(accessToken, 'DEFAULT_UPDATE')
.catch((err) => {
// handle error
});
sandbox/item/fire_webhook

Response fields and example

webhook_firedboolean
Value is true if the test webhook_code was successfully fired.
request_idstring
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1
2
3
4
{
"webhook_fired": true,
"request_id": "1vwmF5TBQwiqfwP"
}

/sandbox/bank_transfer/simulate

Simulate a bank transfer event in Sandbox

Use the /sandbox/bank_transfer/simulate endpoint to simulate a bank transfer event in the Sandbox environment. Note that while an event will be simulated and will appear when using endpoints such as /bank_transfer/event/sync or /bank_transfer/event/list, no transactions will actually take place and funds will not move between accounts, even within the Sandbox.

sandbox/bank_transfer/simulate

Request fields and example

client_idstring
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secretstring
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
bank_transfer_idrequiredstring
Plaid’s unique identifier for a bank transfer.
event_typerequiredstring
The asynchronous event to be simulated. May be: posted, failed, or reversed.
An error will be returned if the event type is incompatible with the current transfer status. Compatible status --> event type transitions include:
pending --> failed
pending --> posted
posted --> reversed
failure_reasonobject
The failure reason if the type of this transfer is "failed" or "reversed". Null value otherwise.
ach_return_codestring
The ACH return code, e.g. R01. A return code will be provided if and only if the transfer status is reversed. For a full listing of ACH return codes, see Bank Transfers errors.
descriptionstring
A human-readable description of the reason for the failure or reversal.
1
2
3
4
5
6
const response = await client
.sandboxBankTransferSimulate(bank_transfer_id, event_type, failure_reason)
.catch((err) => {
// handle error
});
// empty response upon success
sandbox/bank_transfer/simulate

Response fields and example

request_idstring
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1
2
3
{
"request_id": "mdqfuVxeoza6mhu"
}

/sandbox/bank_transfer/fire_webhook

Manually fire a Bank Transfer webhook

Use the /sandbox/bank_transfer/fire_webhook endpoint to manually trigger a Bank Transfers webhook in the Sandbox environment.

sandbox/bank_transfer/fire_webhook

Request fields and example

client_idstring
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secretstring
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
webhookrequiredstring
The URL to which the webhook should be sent.
1
2
3
4
5
6
const response = await client
.sandboxBankTransferFireWebhook(webhookUrl)
.catch((err) => {
// handle error
});
// empty response upon success
sandbox/bank_transfer/fire_webhook

Response fields and example

request_idstring
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1
2
3
{
"request_id": "mdqfuVxeoza6mhu"
}

/sandbox/processor_token/create

Create a test Item and processor token

Use the /sandbox/processor_token/create endpoint to create a valid processor_token for an arbitrary institution ID and test credentials. The created processor_token corresponds to a new Sandbox Item. You can then use this processor_token with the /processor/ API endpoints in Sandbox. You can also use /sandbox/processor_token/create with the user_custom test username to generate a test account with custom data.

sandbox/processor_token/create

Request fields and example

client_idstring
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secretstring
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
institution_idrequiredstring
The ID of the institution the Item will be associated with
optionsobject
An optional set of options to be used when configuring the Item. If specified, must not be null.
override_usernamestring
Test username to use for the creation of the Sandbox Item. Default value is user_good.
Default: user_good
override_passwordstring
Test password to use for the creation of the Sandbox Item. Default value is pass_good.
Default: pass_good
1
2
3
4
5
6
7
8
9
10
11
const createResponse = await client
.sandboxProcessorTokenCreate(institutionID)
.catch((err) => {
// handle error
});
const processorToken = createResponse.processor_token;
// The generated processor_token can now be used to call
// processor endpoints. These endpoints are not currently
// accessible via the client libraries.
sandbox/processor_token/create

Response fields and example

processor_tokenstring
A processor token that can be used to call the /processor/ endpoints.
request_idstring
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1
2
3
4
{
"processor_token": "processor-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d",
"request_id": "Aim3b"
}