Plaid logo
Docs
ALL DOCS

API

  • Overview
  • Libraries
  • API versioning
  • Postman Collection
  • Webhooks
Product API reference
  • Transactions
  • Auth
  • Balance
  • Identity
  • Assets
  • Investments
  • Liabilities
  • Payment Initiation
  • Transfer (beta)
  • Income
  • Identity Verification (early access)
  • Monitor (early access)
Other API reference
  • Item endpoints and webhooks
  • Account endpoints and schemas
  • Institution endpoints
  • Token flow and endpoints
  • Processor and partner endpoints
  • Sandbox endpoints
Plaid logo
Docs
Plaid.com
Get API keys
Open nav

Sandbox endpoints

API reference for Sandbox endpoints

Introduction

Plaid's Sandbox environment provides a number of endpoints that can be used to configure testing scenarios. These endpoints are unique to the Sandbox environment and cannot be used in Development or Production. For more information on these endpoints, see 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 cannot be used with OAuth institutions.

sandbox/public_token/create

Request fields and example

client_id
string
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.
secret
string
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_id
requiredstring
The ID of the institution the Item will be associated with
initial_products
required[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, employment, identity, income_verification, investments, liabilities, payment_initiation, standing_orders, transactions, transfer
options
object
An optional set of options to be used when configuring the Item. If specified, must not be null.
webhook
string
Specify a webhook to associate with the new Item.
override_username
string
Test username to use for the creation of the Sandbox Item. Default value is user_good.

Default: user_good
override_password
string
Test password to use for the creation of the Sandbox Item. Default value is pass_good.

Default: pass_good
transactions
object
An optional set of parameters corresponding to transactions options.
start_date
string
The earliest date for which to fetch transaction history. Dates should be formatted as YYYY-MM-DD.

Format: date
end_date
string
The most recent date for which to fetch transaction history. Dates should be formatted as YYYY-MM-DD.

Format: date
user_token
string
The user token associated with the User data is being requested for.
Select group for content switcher
Select Language
Copy
1const publicTokenRequest: SandboxPublicTokenCreateRequest = {
2 institution_id: institutionID,
3 initial_products: initialProducts,
4};
5try {
6 const publicTokenResponse = await client.sandboxPublicTokenCreate(
7 publicTokenRequest,
8 );
9 const publicToken = publicTokenResponse.data.public_token;
10 // The generated public_token can now be exchanged
11 // for an access_token
12 const exchangeRequest: ItemPublicTokenExchangeRequest = {
13 public_token: publicToken,
14 };
15 const exchangeTokenResponse = await client.itemPublicTokenExchange(
16 exchangeRequest,
17 );
18 const accessToken = exchangeTokenResponse.data.access_token;
19} catch (error) {
20 // handle error
21}
sandbox/public_token/create

Response fields and example

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

/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_id
string
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.
secret
string
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_token
requiredstring
The access token associated with the Item data is being requested for.
Select group for content switcher
Select Language
Copy
1const request: SandboxItemResetLoginRequest = {
2 access_token: accessToken,
3};
4try {
5 const response = await plaidClient.sandboxItemResetLogin(request);
6 // create a public_token for the Item and use it to
7 // initialize Link in update mode.
8 const pt_request: itemPublicTokenCreateRequest = {
9 access_token: accessToken,
10 };
11 const pt_response = await plaidClient.itemCreatePublicToken(pt_request);
12 const publicToken = pt_response.public_token;
13} catch (error) {
14 // handle error
15}
sandbox/item/reset_login

Response fields and example

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

/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_id
string
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.
secret
string
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_token
requiredstring
The access token associated with the Item data is being requested for.
account_id
requiredstring
The account_id of the account whose verification status is to be modified
verification_status
requiredstring
The verification status to set the account to.

Possible values: automatically_verified, verification_expired
Select group for content switcher
Select Language
Copy
1const request: SandboxItemSetVerificationStatusRequest = {
2 access_token: accessToken,
3 account_id: accountID,
4 verification_status: 'automatically_verified',
5};
6try {
7 const response = await plaidClient.sandboxItemSetVerificationStatus(request);
8} catch (error) {
9 // handle error
10}
sandbox/item/set_verification_status

Response fields and example

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

/sandbox/item/fire_webhook

Fire a test webhook

The /sandbox/item/fire_webhook endpoint is used to test that code correctly handles webhooks. This endpoint can trigger the following webhooks:
DEFAULT_UPDATE: Transactions 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.
NEW_ACCOUNTS_AVAILABLE: Webhook to be fired for a given Sandbox Item created with Account Select v2.
AUTH_DATA_UPDATE: Webhook to be fired for a given Sandbox Item created with Auth as an enabled product.
Note that this endpoint is provided for developer ease-of-use and is not required for testing webhooks; webhooks will also fire in Sandbox under the same conditions that they would in Production or Development'

sandbox/item/fire_webhook

Request fields and example

client_id
string
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.
secret
string
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_token
requiredstring
The access token associated with the Item data is being requested for.
webhook_type
string
The webhook types that can be fired by this test endpoint.

Possible values: AUTH, HOLDINGS, INVESTMENTS_TRANSACTIONS, ITEM, LIABILITIES, TRANSACTIONS
webhook_code
requiredstring
The webhook codes that can be fired by this test endpoint.

Possible values: DEFAULT_UPDATE, NEW_ACCOUNTS_AVAILABLE, AUTH_DATA_UPDATE
Select group for content switcher
Select Language
Copy
1// Fire a DEFAULT_UPDATE webhook for an Item
2const request: SandboxItemFireWebhookRequest = {
3 access_token: accessToken
4 webhook_code: 'DEFAULT_UPDATE'
5};
6try {
7 const response = await plaidClient.sandboxItemFireWebhook(request);
8} catch (error) {
9 // handle error
10}
sandbox/item/fire_webhook

Response fields and example

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

/sandbox/transfer/fire_webhook

Manually fire a Transfer webhook

Use the /sandbox/transfer/fire_webhook endpoint to manually trigger a Transfer webhook in the Sandbox environment.

sandbox/transfer/fire_webhook

Request fields and example

client_id
string
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.
secret
string
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.
webhook
requiredstring
The URL to which the webhook should be sent.
Select Language
Copy
1const request: SandboxTransferFireWebhookRequest = {
2 webhook: 'https://www.example.com',
3};
4try {
5 const response = await plaidClient.sandboxTransferFireWebhook(request);
6 // empty response upon success
7} catch (error) {
8 // handle error
9}
sandbox/transfer/fire_webhook

Response fields and example

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

/sandbox/transfer/simulate

Simulate a transfer event in Sandbox

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

sandbox/transfer/simulate

Request fields and example

client_id
string
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.
secret
string
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.
transfer_id
requiredstring
Plaid’s unique identifier for a transfer.
event_type
requiredstring
The asynchronous event to be simulated. May be: posted, failed, or returned.
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 --> returned
failure_reason
object
The failure reason if the event type for a transfer is "failed" or "returned". Null value otherwise.
ach_return_code
string
The ACH return code, e.g. R01. A return code will be provided if and only if the transfer status is returned. For a full listing of ACH return codes, see Transfer errors.
description
string
A human-readable description of the reason for the failure or reversal.
Select Language
Copy
1const request: SandboxTransferSimulateRequest = {
2 transfer_id,
3 event_type: 'posted',
4 failure_reason: failureReason,
5};
6try {
7 const response = await plaidClient.sandboxTransferSimulate(request);
8 // empty response upon success
9} catch (error) {
10 // handle error
11}
sandbox/transfer/simulate

Response fields and example

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

/sandbox/transfer/sweep/simulate

Simulate creating a sweep

Use the /sandbox/transfer/sweep/simulate endpoint to create a sweep and associated events in the Sandbox environment. Upon calling this endpoint, all posted or pending transfers with a sweep status of unswept will become swept, and all returned transfers with a sweep status of swept will become return_swept.

sandbox/transfer/sweep/simulate

Request fields and example

client_id
string
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.
secret
string
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.
Select Language
Copy
1const request: SandboxTransferSweepSimulateRequest = {
2 client_id,
3 secret,
4};
5try {
6 const response = await plaidClient.sandboxTransferSweepSimulate(request);
7 const sweep = response.data.sweep;
8} catch (error) {
9 // handle error
10}
sandbox/transfer/sweep/simulate

Response fields and example

sweep
nullable object
Describes a sweep of funds to / from the sweep account.
A sweep is associated with many sweep events (events of type swept or return_swept) which can be retrieved by invoking the /transfer/event/list endpoint with the corresponding sweep_id.
swept events occur when the transfer amount is credited or debited from your sweep account, depending on the type of the transfer. return_swept events occur when a transfer is returned and Plaid undoes the credit or debit.
The total sum of the swept and return_swept events is equal to the amount of the sweep Plaid creates and matches the amount of the entry on your sweep account ledger.
id
string
Identifier of the sweep.
created
string
The datetime when the sweep occurred, in RFC 3339 format.

Format: date-time
amount
string
Signed decimal amount of the sweep as it appears on your sweep account ledger (e.g. "-10.00")
If amount is not present, the sweep was net-settled to zero and outstanding debits and credits between the sweep account and Plaid are balanced.
iso_currency_code
string
The currency of the sweep, e.g. "USD".
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
Copy
1{
2 "sweep": {
3 "id": "d5394a4d-0b04-4a02-9f4a-7ca5c0f52f9d",
4 "created": "2020-08-06T17:27:15Z",
5 "amount": "12.34",
6 "iso_currency_code": "USD"
7 },
8 "request_id": "mdqfuVxeoza6mhu"
9}
Was this helpful?

/sandbox/income/fire_webhook

Manually fire an Income webhook

Use the /sandbox/income/fire_webhook endpoint to manually trigger an Income webhook in the Sandbox environment.

sandbox/income/fire_webhook

Request fields and example

client_id
string
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.
secret
string
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.
item_id
requiredstring
The Item ID associated with the verification.
user_id
string
The Plaid user_id of the User associated with this webhook, warning, or error.
webhook
requiredstring
The URL to which the webhook should be sent.
verification_status
requiredstring
VERIFICATION_STATUS_PROCESSING_COMPLETE: The income verification status processing has completed. If the user uploaded multiple documents, this webhook will fire when all documents have finished processing. Call the /income/verification/paystubs/get endpoint and check the document metadata to see which documents were successfully parsed.
VERIFICATION_STATUS_PROCESSING_FAILED: A failure occurred when attempting to process the verification documentation.
VERIFICATION_STATUS_PENDING_APPROVAL: The income verification has been sent to the user for review.


Possible values: VERIFICATION_STATUS_PROCESSING_COMPLETE, VERIFICATION_STATUS_PROCESSING_FAILED, VERIFICATION_STATUS_PENDING_APPROVAL
Select group for content switcher
Select Language
Copy
1const request: SandboxIncomeFireWebhookRequest = {
2 income_verification_id: '4b58120d-159b-42d2-9967-d87e93c2a005',
3 item_id: 'Rn3637v1adCNj5Dl1LG6idQBzqBLwRcRZLbgM',
4 webhook: 'https://webhook.com/',
5 verification_status: 'VERIFICATION_STATUS_PROCESSING_COMPLETE',
6};
7try {
8 const response = await plaidClient.sandboxIncomeFireWebhook(request);
9 // empty response upon success
10} catch (error) {
11 // handle error
12}
sandbox/income/fire_webhook

Response fields and example

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

/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_id
string
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.
secret
string
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_id
requiredstring
The ID of the institution the Item will be associated with
options
object
An optional set of options to be used when configuring the Item. If specified, must not be null.
override_username
string
Test username to use for the creation of the Sandbox Item. Default value is user_good.

Default: user_good
override_password
string
Test password to use for the creation of the Sandbox Item. Default value is pass_good.

Default: pass_good
Select group for content switcher
Select Language
Copy
1const request: SandboxProcessorTokenCreateRequest = {
2 institution_id: institutionID,
3};
4try {
5 const response = await plaidClient.sandboxProcessorTokenCreate(request);
6 const processorToken = response.data.processor_token;
7} catch (error) {
8 // handle error
9}
sandbox/processor_token/create

Response fields and example

processor_token
string
A processor token that can be used to call the /processor/ endpoints.
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
Copy
1{
2 "processor_token": "processor-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d",
3 "request_id": "Aim3b"
4}
Was this helpful?
Developer community
Github logo
Github logo
StackOverflow logo
StackOverflow logo
Twitter logo
Twitter logo