API versioning and changelog

Keep track of changes and updates to the Plaid API

API changelog

This page covers backwards-incompatible, versioned API changes. For a list of all API updates, including non-versioned ones, see the API changelog.

API versioning

Whenever we make a backwards-incompatible change to a general availability, non-beta product, we release a new API version to avoid causing breakages for existing developers. You can then continue to use the old API version, or update your application to upgrade to the new Plaid API version. APIs for beta products are subject to breaking changes without versioning.

We consider the following changes to be backwards compatible:

  • Adding new API endpoints
  • Adding new options parameters to existing endpoints
  • Adding new data elements to existing response schemas
  • Adding new enum values, including error_types and error_codes
  • Adding new webhook_types and webhook_codes
  • Changing the length or content of any API identifier
How to set your API version

The default version of the API used in any requests you make can be configured in the Dashboard and will be used when version information is not otherwise specified. You can also manually set the Plaid-Version header to use a specific version for a given API request.

If using a Plaid client library, you will change API versions by either initializing the library with the version you wish to use (Python, Node) or use a specific release of the library that's pinned to a dated version of the API (Ruby, Java, Go).

1
2
3
4
5
6
7
8
9
10
const plaid = require('plaid');
const plaidClient = new plaid.Client(
PLAID_CLIENT_ID,
PLAID_SECRET,
process.env.PLAID_CLIENT_ID,
process.env.PLAID_SECRET,
plaid.environments.sandbox,
{ version: '2019-05-29' }, // specify API version
);

Version 2020-09-14

This version includes several changes to improve authentication, streamline and simplify the API, and improve international support.

  • To improve authentication, the public_key has been fully removed from the API. 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, as 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. The 2018-05-22 and 2019-05-29 API releases previously extended the response schema for /auth/get in order to support international accounts, but these changes were never extended to the /processor/auth/get endpoint. 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.

1
2
3
4
5
6
"numbers": [{
"account": "9900009606",
"account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
"routing": "011401533",
"wire_routing": "021000021"
}]
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
"numbers": {
"ach": [{
"account": "9900009606",
"account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
"routing": "011401533",
"wire_routing": "021000021"
}],
"eft":[{
"account": "111122223333",
"account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
"institution": "021",
"branch": "01140"
}],
"international":[{
"account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
"bic": "NWBKGB21"
"iban": "GB29NWBK60161331926819",
}],
"bacs":[{
"account": "31926819",
"account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
"sort_code": "601613"
}]
}

Version 2019-05-29

  • The Auth numbers schema has been extended to support BACS (UK) and other international (IBAN and BIC) account numbers used across the EU.
  • Renamed the zip field to postal_code and the state field to region in all Identity and Transactions responses to be more international friendly.
  • Identity objects in Identity responses are now embedded on the owners field of the corresponding account.
  • Address data fields for Identity responses are now nullable and are returned with a null value when they aren’t available rather than an empty string.
  • Added a ISO-3166-1 alpha-2 country field to all Identity and Transactions responses.
  • The account type brokerage has been renamed to investment.

These changes are meant to enable access to International institutions for Plaid’s launch in Europe and add support for investment accounts. Test in the Sandbox with the new API version to see the new Schema and enable support for International institutions from the Dashboard in order to create Items for these institutions.

Auth

Before, numbers only had fields for ach (US accounts) and eft (Canadian accounts) accounts numbers:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
"numbers": {
"ach": [{
"account": "9900009606",
"account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
"routing": "011401533",
"wire_routing": "021000021"
}],
"eft":[{
"account": "111122223333",
"account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
"institution": "021",
"branch": "01140"
}]
}

Now, the structure of numbers hasn’t changed, but it can have ach, eft, bacs (UK accounts), or international (currently EU accounts) numbers. Note that the schema for each of these numbers are different from one another. It is possible for multiple networks to be present in the response.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
"numbers": {
"ach": [{
"account": "9900009606",
"account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
"routing": "011401533",
"wire_routing": "021000021"
}],
"eft":[{
"account": "111122223333",
"account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
"institution": "021",
"branch": "01140"
}],
"international":[{
"account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
"bic": "NWBKGB21"
"iban": "GB29NWBK60161331926819",
}],
"bacs":[{
"account": "31926819",
"account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
"sort_code": "601613"
}]
}
Identity

The previous version of Identity had US specific field names and did not include a country as part of the location. Furthermore, the identity data was not scoped to a specific account.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
"identity": {
"addresses": [{
"accounts": [
"Plaid Checking 0000",
"Plaid Saving 1111",
"Plaid CD 2222"
],
"data": {
"city": "Malakoff",
"state": "NY",
"street": "2992 Cameron Road",
"zip": "14236"
},
"primary": true
}],
...
}

Now, identity has international friendly field names of region and postal_code instead of zip and state as well as a ISO-3166-1 alpha-2 country field. Address data fields (city, region, street, postal_code, and country) are now nullable and are returned with a null value when they aren’t available rather than as an empty string. The identity object is now available on the "owners" key of the account, which represents ownership of specific accounts.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
"accounts": [{
...
"owners": [{
"addresses": [{
"data": {
"city": "Malakoff",
"region": "NY",
"street": "2992 Cameron Road",
"postal_code": "14236",
"country": "US",
},
"primary": true
}]
}],
...
}]
Transactions

When no transactions are returned from a request, the transactions object will now be null rather than an empty array.

In addition, the same changes to Identity were also made to Transactions.

1
2
3
4
5
6
7
8
9
10
11
12
"transactions": [{
...
"location": {
"address": "300 Post St",
"city": "San Francisco",
"state": "CA",
"zip": "94108",
"lat": null,
"lon": null
},
...
]}
1
2
3
4
5
6
7
8
9
10
11
12
13
"transactions": [{
...
"location": {
"address": "300 Post St",
"city": "San Francisco",
"region": "CA",
"postal_code": "94108",
"country": "US",
"lat": null,
"lon": null
},
...
]}
Institutions

Changes to the institutions schema effects responses from all of the institutions API endpoints:

  • POST /institutions/search
  • POST /institutions/get
  • POST /institutions/get_by_id

The previous version of the Institution schema did not include the country of the institution as part of the response.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
"institution": {
"credentials": [{
"label": "User ID",
"name": "username",
"type": "text"
}, {
"label": "Password",
"name": "password",
"type": "password"
}],
"has_mfa": true,
"institution_id": "ins_109512",
"mfa": [
"code",
"list",
"questions",
"selections"
],
"name": "Houndstooth Bank",
"products": [
"auth",
"balance",
"identity",
"transactions"
],
// included when options.include_status is true
"status": {object}
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
"institution": {
"country_codes": ["US"],
"credentials": [{
"label": "User ID",
"name": "username",
"type": "text"
}, {
"label": "Password",
"name": "password",
"type": "password"
}],
"has_mfa": true,
"institution_id": "ins_109512",
"mfa": [
"code",
"list",
"questions",
"selections"
],
"name": "Houndstooth Bank",
"products": [
"auth",
"balance",
"identity",
"transactions"
],
// included when options.include_status is true
"status": {object}
}

Version 2018-05-22

  • The Auth numbers schema has changed to support ACH (US-based) and EFT (Canadian-based) account numbers
  • Added the iso_currency_code and unofficial_currency_code fields to all Accounts and Transactions responses

Enable support for Canadian institutions from the Dashboard and then test in the Sandbox using the test Canadian institution, Tartan-Dominion Bank of Canada (institution ID ins_43).

Before, numbers was a list of objects, each one representing the account and routing number for an ACH-eligible US checking or savings account:

1
2
3
4
5
6
"numbers": [{
"account": "9900009606",
"account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
"routing": "011401533",
"wire_routing": "021000021"
}]

New Auth response (2018-05-22 version)

Now, numbers can have either ach (US accounts) or eft (Canadian accounts) numbers. Note that the schema for ach numbers and eft numbers are different from one another.

1
2
3
4
5
6
7
8
9
"numbers": {
"ach": [{
"account": "9900009606",
"account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
"routing": "011401533",
"wire_routing": "021000021"
}],
"eft": []
}
1
2
3
4
5
6
7
8
9
"numbers": {
"ach":[],
"eft":[{
"account": "111122223333",
"account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
"institution": "021",
"branch": "01140"
}]
}

Version 2017-03-08

The 2017-03-08 version was the first versioned release of the API.