Versioning

We periodically release new, dated versions of the API whenever we make breaking changes. The current version is 2019-05-29.

Our client libraries make it easy to move between versions. You will either initialize the library with the version you wish to use (Python and Node) or use a specific release of the the library that's pinned to a dated version of the API (Ruby and Java).

API Versions

var plaid = require('plaid');

var plaidClient = new plaid.Client(PLAID_CLIENT_ID, PLAID_SECRET, PLAID_PUBLIC_KEY, plaid.environments.sandbox, {version: '2019-05-29'});

          
require 'plaid'

client = Plaid::Client.new(env: :sandbox,
                           client_id: PLAID_CLIENT_ID,
                           secret: PLAID_SECRET,
                           public_key: PLAID_PUBLIC_KEY)
          
        
          
// Use builder to create a client
PlaidClient plaidClient = PlaidClient.newBuilder()
  .clientIdAndSecret(PLAID_CLIENT_ID, PLAID_SECRET)
  .publicKey(PLAID_PUBLIC_KEY)
  .sandboxBaseUrl()
  .build();
          
        

curl -X POST https://sandbox.plaid.com/auth/get \
  -H 'Content-Type: application/json' \
  -H 'Plaid-Version: 2019-05-29'
  ...

          
from plaid import Client

client = Client(client_id=PLAID_CLIENT_ID, secret=PLAID_SECRET, public_key=PLAID_PUBLIC_KEY, environment='sandbox', api_version='2019-05-29')
          
        

You can also manually set the Plaid-Version header to use a specific version for a given API request.

Version changelog

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 embeded 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

Previous Auth response (2018-05-22 version)

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

  
"numbers": {
  "ach": [{
    "account": "9900009606",
    "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
    "routing": "011401533",
    "wire_routing": "021000021"
  }],
  "eft":[{
    "account": "111122223333",
    "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
    "institution": "01140",
    "branch": "021"
  }]
}

Current Auth response (2019-05-29 version)

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.

  
"numbers": {
  "ach": [{
    "account": "9900009606",
    "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
    "routing": "011401533",
    "wire_routing": "021000021"
  }],
  "eft":[{
    "account": "111122223333",
    "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
    "institution": "01140",
    "branch": "021"
  }],
  "international":[{
    "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
    "bic": "NWBKGB21"
    "iban": "GB29NWBK60161331926819",
  }],
  "bacs":[{
    "account": "31926819",
    "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
    "sort_code": "601613"
  }]
}
Identity

Previous Identity response (2018-05-22 version)

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.

  
"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
  }],
  ...
}

Current Identity response (2019-05-29 version)

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.

  
"accounts": [{
  ...
  "owners": [{
    "addresses": [{
      "data": {
        "city": "Malakoff",
        "region": "NY",
        "street": "2992 Cameron Road",
        "postal_code": "14236",
        "country": "US",
      },
      "primary": true
    }]
  }],
  ...
}]
Transactions

The same changes to Identity were also made to Transactions.

Previous Transactions response (2018-05-22 version)

  
"transactions": {
  ...
  "location": {
    "address": "300 Post St",
    "city": "San Francisco",
    "state": "CA",
    "zip": "94108",
    "lat": null,
    "lon": null
  },
  ...
}

Current Transactions response (2019-05-29 version)

  
"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

Previous Institution response (2018-05-22 version)

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

  
"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}
}

Current Institution response (2019-05-29 version)

The current response includes an array of ISO-3166-1 alpha-2 country codes supported for an institution.

  
"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}
}

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

Previous Auth response (2017-03-08 version)

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

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

ACH numbers

  
"numbers": {
   "ach": [{
    "account": "9900009606",
    "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
    "routing": "011401533",
    "wire_routing": "021000021"
   }],
   "eft": []
}

EFT numbers

  
"numbers": {
   "ach":[],
   "eft":[{
    "account": "111122223333",
    "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
    "institution": "01140",
    "branch": "021"
   }]
}

2017-03-08

The 2017-03-08 version was the initial release of the API. See the 2017-03-08 docs for more.