Direct Transition Guide

Overview

Transitioning

Transitioning to Plaid’s updated API is easy. This guide walks through what has changed and how to update your integration to take advantage of the updated API.

Looking for legacy API docs? Head here.

Notable changes

  • Product, endpoint, and API environment names and URLs have changed
  • Existing users can be transitioned to the updated API without having them re-authenticate
  • Items can be created with multiple initial products
  • Client libraries and docs are updated with the new endpoints -- legacy libraries are also available
  • Stateful Sandbox - test MFA flows, errors, webhooks, and more

API Environments

New Environment Legacy environment
Sandbox
https://sandbox.plaid.com
N/A
Development
https://development.plaid.com
Tartan
https://tartan.plaid.com
Production
https://production.plaid.com
API
https://api.plaid.com

Your existing API keys will work across all three new API environments as well as the legacy API.

If you want to disable legacy API access, please open a case from your Dashboard.

Server-side integration

Creating new items

Plaid’s API endpoint names have changed. We’ve reorganized the API to make it easier to use, provide more information about your user’s Items, and made it simpler to access multiple products. All of our official client libraries (Node, Python, Ruby, and Java) have been updated to support these new endpoints. This guide provides an overview and reference for the changes. All API endpoints have documented, consistent request and response schemas.

Previous endpoint Notable changes
/:product Now a single endpoint, /item/create
/:product/step Now a single endpoint, /item/mfa
/upgrade Removed, there is no need to use /upgrade before accessing a product endpoint.
/connect/get Now /transactions/get, The endpoint is now paginated by default but still supports searching by date ranges. Pending transactions are returned by default.
/auth/get No change
/info/get Now /identity/get
/exchange_token Now /item/public_token/exchange, public_tokens are now one-time use and expire after 30 minutes.
/institutions/all/search Now /institutions/search

We’ve also introduced a few new endpoints to make it easier to work with the API and your Items:

Endpoint Notes
/item/credentials/update Update the credentials associated with an Item. Analogous to legacy PATCH.
/item/webhook/update Update the webhook associated with an Item. Triggers an acknowledgement webhook in response.
/item/get Retrieve information about an Item, including the institution type, error status, available and billed products, and webhook information.

Transitioning existing Items

You can transition your users’ existing Items via the /item/access_token/update_version endpoint. A new access_token will be generated for the Item that can be used with our updated API. The previous access_token will still be valid in our legacy API environment.

Note: You’ll begin receiving updated webhooks and stop receiving legacy API webhooks as soon as you generate an updated access_token for an Item.

Update access_token version request

curl -X POST https://sandbox.plaid.com/item/access_token/update_version \
 -H 'content-type: application/json' \
 -d '{
   "client_id": String,
   "secret": String,
   "access_token": String
 }'

Update access_token version response

http code 200
{
   "access_token": "access-sandbox-x9v2d345-as9c-461f",
   "request_id": "c92aB"
}

Other updates

Institutions

In the updated API, all institutions IDs observe a consistent schema: numeric identifiers prefixed with ins_. Short hand institution codes (such as chase, bofa, and wells) are no longer supported. We suggest using Link, which is always up-to-date, or using our Institution API endpoints to stay up-to-date with the latest institution data.

Errors

The schema for errors have changed, and we’ve reduced the total number of error types.

Field Nullable? Description
error_type
String
No A broad categorization of the error. One of: INVALID_REQUEST, INVALID_INPUT, RATE_LIMIT_EXCEEDED, API_ERROR, or ITEM.
Safe for programmatic use.
error_code
String
No The particular error code. Each error_type has a specific set of error_codes.
Safe for programmatic use.
error_message
String
No A developer-friendly representation of the error message.
This may change over time and is not safe for programmatic use.
display_message
String
Yes A user-friendly representation of the error message. null if the error is not related to user action.
Not safe for programmatic use.

Below are some of the most common errors:

Error code Explanation
ITEM_LOGIN_REQUIRED Indicates that the user must provide updated authentication in order for Plaid to continue updating the Item. This can happen when a user changes a password, MFA information, or if the account is locked. Use Link’s update mode to resolve this.
ITEM_NOT_SUPPORTED Indicates that Plaid is unable to support the Item. This is rare but can happen for some users with restrictions on their accounts at the institution.
MFA_NOT_SUPPORTED Indicates that the Item requires a type of MFA that Plaid does not support. In some cases, a user can disable the unsupported type of MFA.
NO_ACCOUNTS Indicates that there are no longer any accounts associated with the Item.
PRODUCT_NOT_READY Indicates that the requested product is not yet ready - Plaid is still working to pull the information from the financial institution. Retry the request later or use webhooks to determine when the products is ready.

Webhooks

There are a few key changes with webhooks:

  • Schema updated
  • New field: webhook_type is a high-level categorization of the webhook
  • item_id replaces access_token in the payload as the identifier

See the docs for more webhook payload examples.

Legacy format webhook
{
 "message": "Initial transaction pull finished",
 "access_token": "xxxxx",
 "total_transactions": 123,
 "code": 0
}
Default Transaction Webhook
{
 "webhook_type": "TRANSACTIONS",
 "webhook_code": "DEFAULT_UPDATE",
 "item_id": "wz666MBjYWTp2PDzzggYhM6oWWmBb",
 "error": null,
 "new_transactions": 3
}
Error Webhook Example
{
 "webhook_type": "ITEM",
 "webhook_code": "ERROR",
 "item_id": "wz666MBjYWTp2PDzzggYhM6oWWmBb",
 "error": {
   "display_message": "The provided credentials were not correct. Please try again.",
   "error_code": "ITEM_LOGIN_REQUIRED",
   "error_message": "the provided credentials were not correct",
   "error_type": "ITEM_ERROR",
   "status": 400
 }
}

Sandbox

The API Sandbox environment is now a stateful testing environment, allowing you to test errors, webhooks, MFA, Link update mode, and more. Head to the docs for more info.

username: user_good, password: pass_good

You can trigger any type of MFA flow that Plaid supports when creating an Item. Do so by using username user_good and modifying the password:

Password Notes
mfa_device
Device MFA
Code for all devices: 1234
mfa_questions_<n>_<m>
Questions MFA
n-rounds of m-questions per round; answer_<i>_<j>, for j-th question in i-th round.
0 < i, j <= 9
mfa_selections
Selections MFA
Answers: ['tomato', 'ketchup']

You can trigger any ITEM_ERROR when creating an Item. Do so by using username user_good and modifying the password:

error_[ERROR_CODE]

For example, the password error_ITEM_LOCKED allows you to simulate an ITEM_LOCKED error.