Overview

Introduction

With this quickstart guide, we’ve tried to make it as easy as possible to get up and running with Plaid.

We’ll start with an overview of Plaid and then jump start your integration with a step-by-step guide and code samples in Ruby, Python, and Node. If you’d like to follow along (and test it out!), clone the quickstart repository for the complete example apps. You’ll want to sign up for free API keys to get started.

Running the walkthrough app

Running the walkthrough app

Copy

          
git clone https://github.com/plaid/quickstart.git
cd quickstart/node
npm install

# Start the Quickstart with your API keys from the Dashboard
# https://dashboard.plaid.com/account/keys
PLAID_CLIENT_ID='CLIENT_ID' \
PLAID_SECRET='SECRET' \
PLAID_PUBLIC_KEY='PUBLIC_KEY' \
PLAID_ENV='sandbox' \
node index.js
# Go to http://localhost:8000
          
        

          
git clone https://github.com/plaid/quickstart.git
cd quickstart/ruby

# Install dependencies
bundle

# Start the Quickstart with your API keys from the Dashboard
# https://dashboard.plaid.com/account/keys
PLAID_CLIENT_ID='CLIENT_ID' \
PLAID_SECRET='SECRET' \
PLAID_PUBLIC_KEY='PUBLIC_KEY' \
PLAID_ENV='sandbox' \
ruby app.rb
# Go to http://localhost:4567
          
        

          
git clone https://github.com/plaid/quickstart.git
cd quickstart/python

# For virtualenv users
# virtualenv venv
# source venv/bin/activate

pip install -r requirements.txt

# Start the Quickstart with your API keys from the Dashboard
# https://dashboard.plaid.com/account/keys
PLAID_CLIENT_ID='CLIENT_ID' \
PLAID_SECRET='SECRET' \
PLAID_PUBLIC_KEY='PUBLIC_KEY' \
PLAID_ENV='sandbox' \
python server.py
# Go to http://localhost:5000
          
        

Platform Overview

To help you get oriented with Plaid’s API and what it can help you do, let’s start by defining some basics:

API Keys

Though client_id and public_key are the same across all environments, you have a unique secret for each API environment. Use our Sandbox and Development environments to build out and test your integration with simulated and live users, respectively. You’ll move over to our Production environment once you’re ready to go live!

API environments

• sandbox: Stateful sandbox environment; use test credentials and build out and test your integration
• development: Test your integration with live credentials; you will need to request access before you can access our Development environment
• production: Production API environment; all requests are billed

Item overview

Most API requests interact with an Item, a set of credentials (map of key value pairs) associated with a financial institution. A single end-user of your application might have accounts at different financial institutions, which means they would have multiple different Items.

Your user can have multiple Items, or sets of credentials

Each Item can have many associated accounts, which hold information such as balance, name, and account type

Credit and depository accounts may also have transactions associated with them.

Your users create Items through Link, a drop-in module that handles the credential and MFA validation process. Once an Item is created, Link passes a public_token that you exchange for an access_token from your backend app server.

That access_token and item_id uniquely identify the Item. You use the access_token along with your client_id and secret to access products available for an Item and make changes to it over time.

Read on for more information about each of our products and how you create and access data for an Item.

Plaid Products

Accessing data

Once you create an Item, you can then access data—such as transaction data and account and routing numbers—using our API endpoints. You access data for an Item using the Item’s access_token, which is specific to your API keys and cannot be shared or used by any other API keys. By default, an access_token never expires, but you can rotate it.

You can use the /item/get endpoint to inspect the status of an Item and see a list of all available products as well as the ones you're actively using. You can then call different product endpoints to retrieve data. Due to the complexity of communicating with financial institutions, the initial product data request may take some time.

Products overview

Institution coverage

As we noted above, an Item represents accounts at a given financial institution, bank, or credit union. Plaid supports thousands of different institutions, and we’re constantly working to add more. Though integration information does change, Link stays up-to-date with Plaid’s latest institution coverage at all times and makes it easy for users to find their intended institution.

Because product coverage does vary by institution, we recommend initializing Link with all the products that your integration will need.

Creating Items with Link and the API

Now that you have API keys and know the basics of the Plaid API, it's time to integrate with Plaid Link, which will handle credential validation, multi-factor authentication, and error handling for each institution that we support. Link works across all modern browsers and platforms, including on iOS and Android.

You can also customize parts of Link's flow—including some copy elements, the institution select view, and the background color—and enable additional features like the Select Account view straight from the Dashboard. You can preview your changes in real-time and then publish them instantly once you're ready to go live.

Link allows your users to create Items and also update an Item if it goes into an error state, such as when they change their passwords or MFA information. You can initialize Link with multiple products, such as Transactions and Auth, making it easy to use multiple Plaid products right away.

Item creation flow

An end-to-end integration involves client-side and server-side configurations. Below is a brief overview of how you'll be creating Items with Link.

1

Your user creates an Item, returning a public_token

2

In the onSuccess callback, you send the public_token to your server

3

Your server exchanges the public_token for an access_token and item_id

Client-side Link configuration

Link’s integration is a pure JavaScript approach that you trigger via your own client-side code, and specify callbacks to handle the public_token after the user has authenticated and created an Item.

Using Link requires an understanding of how Plaid access_tokens and public_tokens work and should be used. Read on for a breakdown of the differences.

access_tokens and public_tokens

A public_token (which is returned in your Link onSuccess() callback) should be passed to your server, which will exchange it for an access_token. public_tokens are one-time use tokens and expire after 30 minutes. You can generate new public_tokens as needed via the /item/public_token/create endpoint.

An access_token is used to access product data for an Item. This should be stored securely, and never in client-side code. This is used to make authenticated requests to the Plaid API for the user. By default, access_tokens do not expire, though you can rotate them; if it winds up in an error state, the access_token will work again if the Item’s error is resolved. Each access_token is unique to a specific Item, and cannot be used to access other Items.

User authentication, Item creation, and the public_token

Once you’ve got your public_key from the Dashboard, the Link JavaScript integration is fairly straightforward.

Link allows you to create Items with multiple initial products. Link will only show the user institutions that support all of the products you specify. Valid initial products are transactions, auth, identity, income and assets.

In our example app, we’ll go ahead and open the 'Institution Select' view, so the user can choose which financial institution to authenticate. The global Plaid object has a .create({}) method, which we can customize to suit our needs.

We’ll use this to create an Item with transactions. You can still access other products for the Item later, even if you didn't initialize Link with it. Once the user has successfully authenticated, we’ll pass the public_token from our client-side code to the server.

Copy

<button id="link-button">Link Account</button>
<script src="https://cdnjs.cloudflare.com/ajax/libs/
  jquery/2.2.3/jquery.min.js"></script>
<script src="https://cdn.plaid.com/link/v2/
  stable/link-initialize.js">
  </script>
<script type="text/javascript">
(function($) {
  var handler = Plaid.create({
    clientName: 'Plaid Quickstart',
    env: '<%= PLAID_ENV %>',
    key: '<%= PLAID_PUBLIC_KEY %>',
    product: ['transactions'],
    // Optional – use webhooks to get transaction and error updates
    webhook: 'https://requestb.in',
    onLoad: function() {
      // Optional, called when Link loads
    },
    onSuccess: function(public_token, metadata) {
      // Send the public_token to your app server.
      // The metadata object contains info about the institution the
      // user selected and the account ID or IDs, if the
      // Select Account view is enabled.
      $.post('/get_access_token', {
        public_token: public_token,
      });
    },
    onExit: function(err, metadata) {
      // The user exited the Link flow.
      if (err != null) {
        // The user encountered a Plaid API error prior to exiting.
      }
      // metadata contains information about the institution
      // that the user selected and the most recent API request IDs.
      // Storing this information can be helpful for support.
    },
    onEvent: function(eventName, metadata) {
      // Optionally capture Link flow events, streamed through
      // this callback as your users connect an Item to Plaid.
      // For example:
      // eventName = "TRANSITION_VIEW"
      // metadata  = {
      //   link_session_id: "123-abc",
      //   mfa_type:        "questions",
      //   timestamp:       "2017-09-14T14:42:19.350Z",
      //   view_name:       "MFA",
      // }
    }
  });

  $('#link-button').on('click', function(e) {
    handler.open();
  });
})(jQuery);
</script>

  
<button id="link-button">Link Account</button>
<script src="https://cdnjs.cloudflare.com/ajax/libs/jquery/2.2.3/jquery.min.js"></script&gt;
<script src="https://cdn.plaid.com/link/v2/stable/link-initialize.js"></script&gt;
<script type="text/javascript">
(function($) {
  var handler = Plaid.create({
    clientName: 'Plaid Quickstart',
    env: '<%= ENV["PLAID_ENV"] %>',
    key: '<%= ENV["PLAID_PUBLIC_KEY"] %>',
    product: ['transactions'],
    // Optional – use webhooks to get transaction and error updates
    webhook: 'https://requestb.in',
    onLoad: function() {
      // Optional, called when Link loads
    },
    onSuccess: function(public_token, metadata) {
      // Send the public_token to your app server.
      // The metadata object contains info about the institution the
      // user selected and the account ID or IDs, if the
      // Select Account view is enabled.
      $.post('/get_access_token', {
        public_token: public_token,
      });
    },
    onExit: function(err, metadata) {
      // The user exited the Link flow.
      if (err != null) {
        // The user encountered a Plaid API error prior to exiting.
      }
      // metadata contains information about the institution
      // that the user selected and the most recent API request IDs.
      // Storing this information can be helpful for support.
    },
    onEvent: function(eventName, metadata) {
      // Optionally capture Link flow events, streamed through
      // this callback as your users connect an Item to Plaid.
      // For example:
      // eventName = "TRANSITION_VIEW"
      // metadata  = {
      //   link_session_id: "123-abc",
      //   mfa_type:        "questions",
      //   timestamp:       "2017-09-14T14:42:19.350Z",
      //   view_name:       "MFA",
      // }
    }
  });

  $('#link-button').on('click', function(e) {
    handler.open();
  });
})(jQuery);
</script>
  

  
<button id="link-button">Link Account</button>
<script src="https://cdnjs.cloudflare.com/ajax/libs/jquery/2.2.3/jquery.min.js"></script&gt;
<script src="https://cdn.plaid.com/link/v2/stable/link-initialize.js"></script&gt;
<script type="text/javascript">
(function($) {
  var handler = Plaid.create({
    clientName: 'Plaid Quickstart',
    env: '{{ plaid_environment }}',
    key: '{{ plaid_public_key }}',
    product: ['transactions'],
    // Optional – use webhooks to get transaction and error updates
    webhook: 'https://requestb.in',
    onLoad: function() {
      // Optional, called when Link loads
    },
    onSuccess: function(public_token, metadata) {
      // Send the public_token to your app server.
      // The metadata object contains info about the institution the
      // user selected and the account ID or IDs, if the
      // Select Account view is enabled.
      $.post('/get_access_token', {
        public_token: public_token,
      });
    },
    onExit: function(err, metadata) {
      // The user exited the Link flow.
      if (err != null) {
        // The user encountered a Plaid API error prior to exiting.
      }
      // metadata contains information about the institution
      // that the user selected and the most recent API request IDs.
      // Storing this information can be helpful for support.
    },
    onEvent: function(eventName, metadata) {
      // Optionally capture Link flow events, streamed through
      // this callback as your users connect an Item to Plaid.
      // For example:
      // eventName = "TRANSITION_VIEW"
      // metadata  = {
      //   link_session_id: "123-abc",
      //   mfa_type:        "questions",
      //   timestamp:       "2017-09-14T14:42:19.350Z",
      //   view_name:       "MFA",
      // }
    }
  });

  $('#link-button').on('click', function(e) {
    handler.open();
  });
})(jQuery);
</script>
  

Once a user goes through this flow, an Item will be created with Transactions information, and the onSuccess() callback will pass the public_token back to the server. The server handles the exchange of the public_token for the access_token. This is also where your client_id and secret come into play.

Exchanging the public token for an access token

The next step is to exchange our public_token for an access_token and item_id. The access_token will allow us to make authenticated calls to the Plaid API. Doing so is as easy as calling the /item/public_token/exchange endpoint from our server-side handler. The item_id is used to identify Items in webhooks. We'll use a client library to make the API call.

Save the access_token and item_id in a secure datastore, as they’re used to access Item data and identify webhooks, respectively. A public_token is a one-time use token, so there is no need to store it.

Copy

          
'use strict';

var util = require('util');

var envvar = require('envvar');
var express = require('express');
var bodyParser = require('body-parser');
var moment = require('moment');
var plaid = require('plaid');

var APP_PORT = envvar.number('APP_PORT', 8000);
var PLAID_CLIENT_ID = envvar.string('PLAID_CLIENT_ID');
var PLAID_SECRET = envvar.string('PLAID_SECRET');
var PLAID_PUBLIC_KEY = envvar.string('PLAID_PUBLIC_KEY');
var PLAID_ENV = envvar.string('PLAID_ENV', 'sandbox');

// We store the access_token in memory
// In production, store it in a secure persistent data store
var ACCESS_TOKEN = null;
var PUBLIC_TOKEN = null;
var ITEM_ID = null;

// Initialize the Plaid client
var client = new plaid.Client(
  PLAID_CLIENT_ID,
  PLAID_SECRET,
  PLAID_PUBLIC_KEY,
  plaid.environments[PLAID_ENV],
  {version: '2018-05-22'}
);

var app = express();
app.use(express.static('public'));
app.set('view engine', 'ejs');
app.use(bodyParser.urlencoded({
  extended: false
}));
app.use(bodyParser.json());

app.get('/', function(request, response, next) {
  response.render('index.ejs', {
    PLAID_PUBLIC_KEY: PLAID_PUBLIC_KEY,
    PLAID_ENV: PLAID_ENV,
  });
});

app.post('/get_access_token', function(request, response, next) {
  PUBLIC_TOKEN = request.body.public_token;
  client.exchangePublicToken(PUBLIC_TOKEN, function(error, tokenResponse) {
    if (error != null) {
      var msg = 'Could not exchange public_token!';
      console.log(msg + '\n' + JSON.stringify(error));
      return response.json({
        error: msg
      });
    }
    ACCESS_TOKEN = tokenResponse.access_token;
    ITEM_ID = tokenResponse.item_id;
    prettyPrintResponse(tokenResponse);
    response.json({
      access_token: ACCESS_TOKEN,
      item_id: ITEM_ID,
      error: false
    });
  });
});
          
        

          
require 'date'
require 'json'
require 'plaid'
require 'sinatra'

set :public_folder, File.dirname(FILE) + '/static'

client = Plaid::Client.new(env: ENV['PLAID_ENV'],
                           client_id: ENV['PLAID_CLIENT_ID'],
                           secret: ENV['PLAID_SECRET'],
                           public_key: ENV['PLAID_PUBLIC_KEY'])

access_token = nil

get '/' do
  erb :index
end

post '/get_access_token' do
  exchange_token_response =
    client.item.public_token.exchange(params['public_token'])
  access_token = exchange_token_response['access_token']
  pretty_print_response(exchange_token_response)

  content_type :json
  exchange_token_response.to_json
end
          
        

          
import os
import datetime
import plaid
import json
from flask import Flask
from flask import render_template
from flask import request
from flask import jsonify

app = Flask(name)

PLAID_CLIENT_ID = os.getenv('PLAID_CLIENT_ID')
PLAID_SECRET = os.getenv('PLAID_SECRET')
PLAID_PUBLIC_KEY = os.getenv('PLAID_PUBLIC_KEY')
# Use 'sandbox' to test with Plaid's Sandbox environment (username: user_good,
# password: pass_good)
# Use development to test with live users and credentials and production
# to go live
PLAID_ENV = os.getenv('PLAID_ENV', 'sandbox')


client = plaid.Client(client_id = PLAID_CLIENT_ID, secret=PLAID_SECRET,
                      public_key=PLAID_PUBLIC_KEY, environment=PLAID_ENV, api_version='2018-05-22')

@app.route('/')
def index():
  return render_template('index.ejs', plaid_public_key=PLAID_PUBLIC_KEY, plaid_environment=PLAID_ENV)

access_token = None

@app.route('/get_access_token', methods=['POST'])
def get_access_token():
  global access_token
  public_token = request.form['public_token']
  exchange_response = client.Item.public_token.exchange(public_token)
  access_token = exchange_response['access_token']

  pretty_print_response(exchange_response)

  return jsonify(exchange_response)

          
        

At this point, you’ve successfully walked a user through creating an Item, gotten the public_token from Link, and exchanged it for an access_token and item_id.

Note that we need to persist the access_token and item_id somewhere. A public_token is required if the user needs to update the credentials in the future, but one can be generated with the Item's access_token, so there is no need to store the public_token.

Now that we have the Item's access_token, we can access Transaction and Auth information. Below, we’ll show how to fetch this data.

Accessing Item Data

Pulling Auth data

By posting to the /auth/get endpoint, we’ll see high-level account information for all available accounts and account numbers for checking and savings accounts.

Let’s add another server-side handler to our example app that will retrieve Auth data for the Item by using its access_token:

/auth/get request

Copy

          
// Retrieve ACH or EFT Auth data for an Item's accounts
// https://plaid.com/docs/#auth
app.get('/auth', function(request, response, next) {
  client.getAuth(ACCESS_TOKEN, function(error, authResponse) {
    if (error != null) {
      prettyPrintResponse(error);
      return response.json({
        error: error,
      });
    }
    prettyPrintResponse(authResponse);
    response.json({error: null, auth: authResponse});
  });
});
          
        

          
# Retrieve ACH or EFT account numbers for an Item
# https://plaid.com/docs/#auth
get '/auth' do
  begin
    product_response = client.auth.get(access_token)
    pretty_print_response(product_response)
    content_type :json
    { auth: product_response }.to_json
  rescue Plaid::PlaidAPIError => e
    error_response = format_error(e)
    pretty_print_response(error_response)
    content_type :json
    error_response.to_json
  end
end
          
        

          
# Retrieve ACH or EFT account numbers for an Item
# https://plaid.com/docs/#auth
@app.route('/auth', methods=['GET'])
def get_auth():
  try:
    auth_response = client.Auth.get(access_token)
  except plaid.errors.PlaidError as e:
    return jsonify({'error': {'display_message': e.display_message, 'error_code': e.code, 'error_type': e.type } })
  pretty_print_response(auth_response)
  return jsonify({'error': None, 'auth': auth_response})
          
        

Auth data comes back like the following:

{
  "accounts": [
    {
      "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
      "balances": {
        "available": 100,
        "current": 110,
        "limit": null,
        "iso_currency_code": "USD",
        "unofficial_currency_code": null,
      },
      "mask": "0000",
      "name": "Plaid Checking",
      "official_name": "Plaid Gold Standard 0% Interest Checking",
      "subtype": "checking",
      "type": "depository"
    },
    ...
  ],
  "numbers": {
    "ach": [{
      "account": "9900009606",
      "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
      "routing": "011401533",
      "wire_routing": "021000021"
    }],
    "eft": [],
    ...
  }
}

One thing to note is that not all accounts calculate the available balance. For instance, mortgages or student loans may not necessarily store an available balance. In such cases, Plaid will return an available balance of null.

Pulling Transaction data

Once the Item is created with Transactions, Plaid automatically starts the transaction retrieval and cleansing process. You can make a request to the /transactions/get endpoint to retrieve this data. Transaction webhooks can notify you about new transactions as they become available.

The first transaction pull, the initial pull, pulls in 30 days of transaction data and takes between 30 and 240 seconds. Once the initial pull is completed, Plaid will begin the historical pull, which retrieves as much data as is available. From there, we’ll update the Item's data at set intervals throughout the day to collect all of the most recent transactions.

Note: We work hard to provide as much historical data as possible. However, there are limiting factors in the amount of information an institution holds and the length of time a user has had an account.

Transaction data with webhooks

Transaction data can be retrieved as it becomes available by calling the /transactions/get API endpoint—but you'll want to make sure Plaid actually has new data before doing so. Webhooks allow you to react when new data is available, rather than continuously polling for changes. With webhooks, you'll be notified of new transactions and can then retrieve the data as necessary.

Transaction notifications are posted as JSON to your webhook, and they might appear in a few different forms:

Initial transaction update

Always fired, usually within 30-240 seconds of the Item being created (if transactions is an initial product). The initial pull fetches 30 days of transaction data.

  
{
  "webhook_type": "TRANSACTIONS",
  "webhook_code": "INITIAL_UPDATE",
  "item_id": "wz666MBjYWTp2PDzzggYhM6oWWmBb",
  "error": null,
  "new_transactions": 19
}
  

Historical transaction update

Always fired, for historical transaction data beyond the initial pull.

  
{
  "webhook_type": "TRANSACTIONS",
  "webhook_code": "HISTORICAL_UPDATE",
  "item_id": "wz666MBjYWTp2PDzzggYhM6oWWmBb",
  "error": null,
  "new_transactions": 231
}
  

Default transaction pulls

Only fired when new transaction data is available as Plaid performs its regular updates of the Item.

  
{
  "webhook_type": "TRANSACTIONS",
  "webhook_code": "DEFAULT_UPDATE",
  "item_id": "wz666MBjYWTp2PDzzggYhM6oWWmBb",
  "error": null,
  "new_transactions": 3
}

Removed transactions

In some cases, an institution may remove a transaction (for instance, a temporary hold), and Plaid will react accordingly. You'll receive a webhook notification similar to the following:

   
  "webhook_type": "TRANSACTIONS",
  "webhook_code": "TRANSACTIONS_REMOVED",
  "removed_transactions": [
    "yBVBEwrPyJs8GvR77N7QTxnGg6wG74H7dEDN6",
    "kgygNvAVPzSX9KkddNdWHaVGRVex1MHm3k9no"
  ],
  "error": null,
  "item_id": "wz666MBjYWTp2PDzzggYhM6oWWmBb"
}

The item_id is passed with each webhook so you can match it with user records on your side. Once you've received a notification that transaction data is available, you can call the /transactions/get endpoint to retrieve it:

Copy

          
// Retrieve Transactions for an Item
// https://plaid.com/docs/#transactions
app.get('/transactions', function(request, response, next) {
  // Pull transactions for the Item for the last 30 days
  var startDate = moment().subtract(30, 'days').format('YYYY-MM-DD');
  var endDate = moment().format('YYYY-MM-DD');
  client.getTransactions(ACCESS_TOKEN, startDate, endDate, {
    count: 250,
    offset: 0,
  }, function(error, transactionsResponse) {
    if (error != null) {
      prettyPrintResponse(error);
      return response.json({
        error: error
      });
    } else {
      prettyPrintResponse(transactionsResponse);
      response.json({error: false, transactions: transactionsResponse});
    }
  });
});
          
        

          
# Retrieve Transactions for an Item
# https://plaid.com/docs/#transactions
get '/transactions' do
  now = Date.today
  thirty_days_ago = (now - 30)
  begin
    product_response =
      client.transactions.get(access_token, thirty_days_ago, now)
    pretty_print_response(product_response)
    content_type :json
    { transactions => product_response }.to_json
  rescue Plaid::PlaidAPIError => e
    error_response = format_error(e)
    pretty_print_response(error_response)
    content_type :json
    error_response.to_json
  end
end
          
        

          
# Retrieve Transactions for an Item
# https://plaid.com/docs/#transactions
@app.route('/transactions', methods=['GET'])
def get_transactions():
  # Pull transactions for the last 30 days
  start_date = '{:%Y-%m-%d}'.format(datetime.datetime.now() + datetime.timedelta(-30))
  end_date = '{:%Y-%m-%d}'.format(datetime.datetime.now())
  try:
    transactions_response = client.Transactions.get(access_token, start_date, end_date)
  except plaid.errors.PlaidError as e:
    return jsonify({'error': {'display_message': e.display_message, 'error_code': e.code, 'error_type': e.type } })
  pretty_print_response(transactions_response)
  return jsonify({'error': None, 'transactions': transactions_response})
          
        

Returned transaction data would look like the following. (For a full overview of what each field means, visit our transaction data overview.

  
{
  "transactions": [
    {
      "account_id": "XA96y1wW3xS7wKyEdbRzFkpZov6x1ohxMXwep",
      "amount": 78.5,
      "iso_currency_code": "USD",
      "unofficial_currency_code": null,
      "category": null,
      "category_id": null,
      "date": "2017-01-29",
      "location": {
        "street": "100 Market Street",
        "city": "San Francisco",
        "state": "CA",
        "zip": "94110"
      },
      "name": "Touchstone Climbing",
      "payment_meta": {},
      "pending": false,
      "pending_transaction_id": null,
      "transaction_id": "4WPD9vV5A1cogJwyQ5kVFB3vPEmpXPS3qvjXQ",
      "transaction_type": "unresolved"
    },
    ...
  ]
}

Handling Item Errors

Sometimes, a user might change a password with an institution, or they might lock themselves out of the account. When this happens, an Item enters an error state, at which point all data retrieval calls to the API for the Item will return an error code. You can still make requests to /item/get endpoint, even when an Item is in an error state.

The most common error is ITEM_LOGIN_REQUIRED, which means that the user needs to provide updated credentials and possibly MFA. It’s straightforward to flag and repair these scenarios using Link and the API.

Error webhooks

Webhooks go beyond transaction data: They can also be used to communicate certain errors, such as invalid credentials or a locked item. In the event this happens, you’ll receive a notification with an ITEM_LOGIN_REQUIRED error:

  
{
  "error": {
    "display_message": null,
    "error_code": "ITEM_LOGIN_REQUIRED",
    "error_message": "the login details of this item have changed and a user login is required to update this information.",
    "error_type": "ITEM_ERROR",
    "status": 400
  },
  "item_id": "wz666MBjYWTp2PDzzggYhM6oWWmBb",
  "webhook_code": "ERROR",
  "webhook_type": "ITEM"
}

Though the most common error is ITEM_LOGIN_REQUIRED, you may run into a few others. For all possible error_codes, see the docs, or read on for a description of the most common errors:

Using Link to resolve an Item error

Plaid Link makes it easy for your user to update their credentials as necessary, through what we call update mode. Update mode enables an end-user to re-authenticate an Item, at which point Plaid will resolve that Item into a functioning state. Once an Item has been updated, data access will be restored and transaction updates, if you're using them, will automatically resume. Check out an overivew of the process below.

1

Plaid sends an Item error webhook to your app server

2

You make a request with an access_token to create a temporary public_token

3

You send the public_token to your client and have the user re-authenticate with Plaid

4

The onSuccess callback will indicate that the user has successfully re-authenticated

Attempting to initialize Link in update mode for an Item that is not in an error state will result in an ITEM_NO_ERROR error. You can use the /sandbox/item/reset_login endpoint to put an Item into an error state in the Sandbox.

To configure update mode, generate a public_token for the Item server-side and then use that public_token to initialize Link. The Item’s access_token will not change.

Resolve an Item error

Copy

          
// Create a one-time use public_token for the Item.
// This public_token can be used to initialize Link
// in update mode for the user
app.get('/create_public_token', function(request, response, next) {
  client.createPublicToken(ACCESS_TOKEN, function(err, res) {
    if(error != null) {
      console.log(msg + "\n" + JSON.stringify(err));
      response.json({error: JSON.stringify(err)}):
    } else {
      // Use the public_token to initialize Link
      var PUBLIC_TOKEN = res.public_token;
      response.json({public_token: PUBLIC_TOKEN});
    }
  });
});
          
        

          
# Create a one-time use public_token for the Item.
# This public_token can be used to initialize Link
# in update mode for the user.
get '/create_public_token' do
  public_token_response = client.item.public_token.create(access_token)
  content_type :json
  public_token_response.to_json
end
          
        

          
@app.route("/create_public_token", methods=['GET'])
def create_public_token():
  global access_token
  # Create a one-time use public_token for the Item.
  # This public_token can be used to initialize Link
  # in update mode for the user.
  response = client.Item.public_token.create(access_token)
  return jsonify(response)
          
        

Then initialize Link client-side with the newly generated public_token:

Copy

          
var handler = Plaid.create({
  clientName: 'Plaid Quickstart',
  env: 'sandbox',
  product: ['transactions'],
  key: 'PUBLIC_KEY',
  token: 'CREATED_PUBLIC_TOKEN',
  onSuccess: function(public_token, metadata) {},
  onExit: function(err, metadata) {},
  onEvent: function(eventName, metadata) {}
});
          
        

          
var handler = Plaid.create({
  clientName: 'Plaid Quickstart',
  env: 'sandbox',
  product: ['transactions'],
  key: 'PUBLIC_KEY',
  token: 'CREATED_PUBLIC_TOKEN',
  onSuccess: function(public_token, metadata) {},
  onExit: function(err, metadata) {},
  onEvent: function(eventName, metadata) {}
});
          
        

          
var handler = Plaid.create({
  clientName: 'Plaid Quickstart',
  env: 'sandbox',
  product: ['transactions'],
  key: 'PUBLIC_KEY',
  token: 'CREATED_PUBLIC_TOKEN',
  onSuccess: function(public_token, metadata) {},
  onExit: function(err, metadata) {},
  onEvent: function(eventName, metadata) {}
});
          
        

Link automatically handles the necessary API calls to update the Item. As we’ve noted, the Item's access_token does not change unless you explicitly rotate it. While you’re free to redo the storing and exchange token call, there’s no need to: The end-user has re-authenticated with the institution, and API product access calls should resume operating successfully.

To test Link’s update mode, you may want a to simulate putting an Item into an error state.

To do so, use the /sandbox/item/reset_login endpoint:

Copy

          
client.resetLogin(access_token,
  function(err, reset_login_response) {
  // Handle err
  // create a public_token for the Item
  client.createPublicToken(access_token,
  function(err, public_token_response) {
    // Handle err
    // Use the generated public_token to initialize Link
    // in update mode
  });
});
          
        

          
# Force a Sandbox Item into an error state
client.sandbox.sandbox_item.reset_login(access_token)
# create a public_token for the Item and use it to initialize Link
# in update mode.
public_token_response =
  client.item.public_token.create(access_token)
          
        

          
# Force a Sandbox Item into an error state
client.Sandbox.item.reset_login(access_token)
# create a public_token for the Item and use it to initialize Link
# in update mode.
public_token_response =
  client.Item.public_token.create(access_token)
          
        

Moving Forward

Migrating to production

Keep building your integration out in our Sandbox and Development API environments. When you're ready to go to Production, request access from the Dashboard. While you’re at it, be sure to also take a look at our Privacy Policy.

Getting help

Find answers to common integration and product questions at our Help Center. You can find all the code for this quickstart guide, including runnable sample apps, on GitHub.

We can’t wait to see what you build!