Welcome to version 4 (v4) of the Plaid API Documentation. This documentation will help you get started with the Plaid API.
The Plaid API allows developers to access and interact with banking and other financial data. Some common use cases include:
Accessing financial data: Developers can access financial data from banks, credit card companies, and other financial institutions.
Initiating transactions: Developers can initiate transactions such as money transfers.
Plaid API uses the HTTP protocol, and requests are made using the appropriate HTTP methods. The data is typically sent and received in JSON format.
The next few sections of this introductory page will guide you on obtaining the necessary credentials to start experimenting with the PLAID API.
API Versioning 🔢
This is the 4th and latest version of the Plaid API, known as version 2020-09-14.
This version includes several changes to improve authentication, streamline and simplify the API, and improve international support.
Below are a complete list of changes that have been added to this version.
Key Changes
Details
The public_key has been fully removed from the API to improve authentication.
Endpoints that previously accepted a public_key for authentication, namely /institutions/get_by_id and /institutions/search, now require a client_id and secret for authentication instead.
/item/remove no longer returns a removed boolean.
This field created developer confusion, because it was never possible for it to return false. A failed /item/remove call will result in an error being returned instead.
Several undocumented and unused fields have been removed.
from the institution object returned by the institutions endpoints /institutions/get, /institutions/get_by_id, and /institutions/search. The removed fields are: input_spec, credentials, include_display_data, has_mfa, mfa, and mfa_code_type.
The institutions endpoints /institutions/get, /institutions/get_by_id, and /institutions/search now require the use of a country_codes parameter and no longer use US as a default value if country_codes is not specified.
This behavior caused confusion and unexpected behavior for non-US developers. As part of this change, the country_codes parameter has been moved out of the options object and is now a top-level parameter.
To support international payments, the response schema for the partner-only /processor/auth/get endpoint has changed.
This release brings the response for /processor/auth/get in line with the /auth/get response, allowing Plaid partners to extend support for using non-ACH payment methods, such as EFT payments (Canada) or SEPA credit and direct debit (Europe). Accommodating this change does not require any code changes from Plaid developers who use partnership integrations, only from the Plaid partners themselves.
To see a complete log of the previous versions, please see the changelog section of the general Plaid documentation.
Obtaining credentials 🔑
Client_id and Secret
Before using the API, you need to obtain an API key. Plaid has three environments:
Sandbox: Supports only test items.
Development: Supports up to 100 live items using real data.
Production: Where all activity is billed.
This documentation is focused on the Sandbox environment where you can test and experiment with free data.
Below is a step-by-step guide on how to obtain your Sandbox Credentials
Fill in your data in the required fields, then verify your account to log in to your dashboard.
On your dashboard, navigate to your account at the top-right corner and click to select the "keys" option.
You'll be asked to do a 2-factor authentication. You can either authenticate with your mobile number or with an authentication app.
Once you've authenticated successfully, your Sandbox Credentials will be displayed like so:
Copy your_client_id_and_secret_, and ensure to keep them safe. You'll always need to authenticate with them to access the Plaid APIs.
account_id
To access some part of the APIs, you'll also need an access_token credential. To create an access_token, kindly follow the steps below:
Create a public token using the /sandbox/public_token/create endpoint
The endpoint in step one will require your client_id and secret credentials, with two additional parameters: institution_id and initial_products
To obtain these parameters above, log in to your dashboard, and navigate to Activity on the sidebar.
In the drop-down menu that appears, click on status. This will display a list of institutions.
Select any institution of your choice. In the page containing the institution details, copy the institution_id and supported products for your institution_id and initial_products parameters.
Once your public token has been created, you'll have to exchange it using the /item/public_token/exchange endpoint for an access token. The request requires your client_id, secret, and public_token for authentication.
If your request is successful, it will return an access_token which you will use to make requests to other endpoints.
The next section will guide you on how to authenticate with your credentials.
Authentication 🔒
To Authenticate with your Sandbox credentials, you'll need to include your client_id and secret in your request headers or body, like so:
Plaid returns data as JSON, therefore you will also have to set Content-Type to application/json in your request Header.
Error and Status Codes ⚠️
Plaid API returns standard HTTP status codes to indicate the outcome of a request. Additionally, the response body may include an error object with more details.
Here are some standard error status codes and their meanings:
General HTTP Status Codes
Status Code
Status Name
Meaning
200
Request Successful!
The intended action was carried out successfully
201
Okay
The resource was successfully created.
400
Bad Request
The request contains invalid parameters
401
Unauthorized
The request lacks valid credentials.
404
Not Found
The requested resource was not found.
Plaid-Specific Status Codes
Error Code
Error Type
Meaning
INVALID_ACCESS_TOKEN
INVALID_INPUT
Could not find matching access token.
INVALID_PRODUCT
INVALID_INPUT
some products cannot be included in initial_products:
MISSING_FIELDS
INVALID_REQUEST
The following required fields are missing.
INSTITUTION_NOT_AVAILABLE
INSTITUTION_ERROR
The Institution is not currently responding to this request
SANDBOX_PRODUCT_NOT_ENABLED
SANDBOX_ERROR
The product is not enabled on this item
Rate Limits ⏳
To help manage the volume of requests made by thousands of developers daily, Plaid places limits on the number of requests that can be made. These limits help to provide reliable and scalable APIs for developers.
Rate limits are applied based on which Plaid environment credentials you use. When these limits are exceeded, an error is returned.
To learn about these errors please see the table below for an overview of Rate limits for the sandbox environment.