API versioning and changelog

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

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, with 30 days notice.

We consider the following changes to be backwards compatible:

• Adding new API endpoints
• Adding new optional parameters to existing endpoints
• Adding new data elements to existing response schemas or webhooks
• Adding new enum values, including error_types and error_codes
• Subdividing existing error_codes into more precise errors, and changing the http response code as necessary, as long as the error cannot be resolved via developer action (such as retries) during runtime. For example, changing PRODUCT_NOT_READY errors to a different error_code would be a breaking change, since that error can be resolved by retrying later, but converting an existing INTERNAL_SERVER_ERROR to a more specific error would not be.
• Adding new webhook_types and webhook_codes
• Changing the length or content of any API identifier

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 you're using one of the Plaid client libraries, they should all be pinned to the latest version of the API at the time when they were released. This means that you can change the API version you're using by updating to a newer version of the client library.

1const { Configuration, PlaidApi, PlaidEnvironments } = require('plaid');
2
3const configuration = new Configuration({
4  basePath: PlaidEnvironments[process.env.PLAID_ENV],
5  baseOptions: {
6    headers: {
7      'PLAID-CLIENT-ID': process.env.PLAID_CLIENT_ID,
8      'PLAID-SECRET': process.env.PLAID_SECRET,
9      'Plaid-Version': '2020-09-14',
10    },
11  },
12});
13
14const client = new PlaidApi(configuration);

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"numbers": [{
2  "account": "9900009606",
3  "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
4  "routing": "011401533",
5  "wire_routing": "021000021"
6}]

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

• 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.

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

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

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

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

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

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"transactions": [{
2  ...
3  "location": {
4    "address": "300 Post St",
5    "city": "San Francisco",
6    "state": "CA",
7    "zip": "94108",
8    "lat": null,
9    "lon": null
10  },
11  ...
12]}

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

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

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

• 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"numbers": [{
2  "account": "9900009606",
3  "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
4  "routing": "011401533",
5  "wire_routing": "021000021"
6}]

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"numbers": {
2   "ach": [{
3    "account": "9900009606",
4    "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
5    "routing": "011401533",
6    "wire_routing": "021000021"
7   }],
8   "eft": []
9}

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

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