node package manager


A node.js client for the Plaid API

plaid-node Circle CI npm version

A node.js client library for the Plaid API.

This module was recently refactored and released as version 1.0.x. The previous version, 0.1.1, is still available via npm.

Table of Contents


$ npm install plaid

Getting started

The module supports all Plaid API endpoints. For complete information about the API, head to the docs.

Public Endpoints

Public endpoints (category and institution information) require no authentication and can be accessed as follows:

var plaid = require('plaid');
plaid.getCategory(category_id, plaid_env, callback);
plaid.getCategories(plaid_env, callback);
plaid.getInstitution(institution_id, plaid_env, callback);
plaid.getInstitutions(plaid_env, callback);
plaid.searchInstitutions({id: institutionId}, env, callback);
plaid.searchInstitutions({product: plaidProduct, query: searchString}, env, callback);
plaid.searchAllInstitutions({id: institutionId}, env, callback);
plaid.searchAllInstitutions({product: plaidProduct, query: searchString}, env, callback);

plaid_env dictates which Plaid API environment you will access. Values are:

Environments are exported from the module, i.e.:

var plaid = require('plaid');

Authenticated Endpoints

Authenticated endpoints require a valid client_id and secret to access. You can use the sandbox client_id and secret for testing (test_id and test_secret).

All authenticated endpoints are accessible from an instance of a Plaid Client:

var plaid = require('plaid');
var plaidClient = new plaid.Client(client_id, secret, plaid_env);

The plaid_env parameter dictates which Plaid API environment you will access. Values are:

Once an instance of the client has been created you use the following methods:

var plaid = require('plaid');
// Initialize client 
var plaidClient = new plaid.Client(client_id, secret, plaid_env);
// addAuthUser(String, Object, Object?, Function) 
plaidClient.addAuthUser(institution_type, credentials, options, callback);
// stepAuthUser(String, String, Object?, Function) 
plaidClient.stepAuthUser(access_token, mfaResponse, options, callback);
// getAuthUser(String, Object?, Function) 
plaidClient.getAuthUser(access_token, options, callback);
// patchAuthUser(String, Object, Object? Function) 
plaidClient.patchAuthUser(access_token, credentials, options, callback);
// deleteAuthUser(String, Object?, Function) 
plaidClient.deleteAuthUser(access_token, options, callback);
// addConnectUser(String, Object, Object?, Function) 
plaidClient.addConnectUser(institution_type, credentials, options, callback);
// stepConnectUser(String, String, Object?, Function) 
plaidClient.stepConnectUser(access_token, mfaResponse, options, callback);
// getConnectUser(String, Object?, Function) 
plaidClient.getConnectUser(access_token, options, callback);
// patchConnectUser(String, Object, Object?, Function) 
plaidClient.patchConnectUser(access_token, credentials, options, callback);
// deleteConnectUser(String, Object?, Function) 
plaidClient.deleteConnectUser(access_token, options, callback);
// addIncomeUser(String, Object, Object?, Function) 
plaidClient.addIncomeUser(institution_type, credentials, options, callback);
// stepIncomeUser(String, String, Object, Function) 
plaidClient.stepIncomeUser(access_token, mfaResponse, options, callback);
// getIncomeUser(String, Object?, Function) 
plaidClient.getIncomeUser(access_token, options, callback);
// patchIncomeUser(String, Object, Object?, Function) 
plaidClient.patchIncomeUser(access_token, credentials, options, callback);
// deleteIncomeUser(String, Object?, Function) 
plaidClient.deleteIncomeUser(access_token, options, callback);
// addInfoUser(String, Object, Object?, Function) 
plaidClient.addInfoUser(institution_type, credentials, options, callback);
// stepInfoUser(String, String, Object, Function) 
plaidClient.stepInfoUser(access_token, mfaResponse, options, callback);
// getInfoUser(String, Object?, Function) 
plaidClient.getInfoUser(access_token, options, callback);
// patchInfoUser(String, Object, Object?, Function) 
plaidClient.patchInfoUser(access_token, credentials, options, callback);
// deleteInfoUser(String, Object?, Function) 
plaidClient.deleteInfoUser(access_token, options, callback);
// addRiskUser(String, Object, Object?, Function) 
plaidClient.addRiskUser(institution_type, credentials, options, callback);
// stepRiskUser(String, String, Object, Function) 
plaidClient.stepRiskUser(access_token, mfaResponse, options, callback);
// getRiskUser(String, Object?, Function) 
plaidClient.getRiskUser(access_token, options, callback);
// patchRiskUser(String, Object, Object?, Function) 
plaidClient.patchRiskUser(access_token, credentials, options, callback);
// deleteRiskUser(String, Object?, Function) 
plaidClient.deleteRiskUser(access_token, options, callback);
// getBalance(String, Function) 
plaidClient.getBalance(access_token, callback);
// upgradeUser(String, String, Object?, Function) 
plaidClient.upgradeUser(access_token, upgrade_to, options, callback);
// exchangeToken(String, Function) 
plaidClient.exchangeToken(public_token, callback);
// getLongtailInstitutions(Object, Function) 
plaidClient.getLongtailInstitutions(optionsObject, callback);
// getAllInstitutions(Object, Function) 
plaidClient.getAllInstitutions(optionsObject, callback);

All parameters except options are required.


For a request that could potentially return a MFA response, callbacks are in the form:

function callback(err, mfaResponse, response) {
  // err can be a network error or a Plaid API error (i.e. invalid credentials) 
  // mfaResponse can be any type of Plaid MFA flow 

All add, step, and patch related requests can return a MFA response. upgradeUser can also return MFA responses.

For delete, get, getBalance, and exchangeToken requests, callbacks are in the form:

function callback(err, response) {
  // err can be a network error or a Plaid API error (i.e. invalid credentials) 

Error Handling

The err argument passed to either callback style can either be an instance of Error or a Plaid API error object. An Error object is only passed back in the case of a HTTP connection error. The following code distinguishes between a Plaid error and a standard Error instance:

function callback(err, response) {
  if (err != null) {
    if (err.code != null) {
      // This is a Plaid error 
      console.log(err.code + '' + err.message);
    } else {
      // This is a connection error, an Error object 


Bank of America question-based MFA flow:

var plaid = require('plaid');
// Initialize a client 
var plaidClient = new plaid.Client('test_id', 'test_secret', plaid.environments.tartan);
// Add a BofA auth user going through question-based MFA 
plaidClient.addAuthUser('bofa', {
  username: 'plaid_test',
  password: 'plaid_good',
}, function(err, mfaResponse, response) {
  if (err != null) {
    // Bad request - invalid credentials, account locked, etc. 
  } else if (mfaResponse != null) {
    plaidClient.stepAuthUser(mfaResponse.access_token, 'tomato', {},
    function(err, mfaRes, response) {
  } else {
    // No MFA required - response body has accounts 

Chase device-based MFA flow, including using the list:true option to allow the user select the device to send their security code to:

// Add a Chase user using the list:true option 
plaidClient.addConnectUser('chase', {
  username: 'plaid_test',
  password: 'plaid_good',
}, {
  list: true,
}, function(err, mfaRes, response) {
  // mfaRes.mfa is a list of send_methods 
  plaidClient.stepConnectUser(mfaRes.access_token, null, {
    send_method: mfaRes.mfa[0],
  }, function(err, mfaRes, response) {
    // code was sent to the device we specified 
    plaidClient.stepConnectUser(mfaRes.access_token, '1234', function(err, mfaRes, res) {
      // We now have accounts and transactions 
      console.log('# transactions: ' + res.transactions.length);
      console.log('access token: ' + res.access_token);

Retrieve transactions for a connect user for the last thirty days:

plaidClient.getConnectUser(access_token, {
  gte: '30 days ago',
}, function(err, response) {
  console.log('You have ' + response.transactions.length +
              ' transactions from the last thirty days.');

Associate a new webhook with a connect user (webhook PATCH):

// Credentials are not required in this case 
plaidClient.patchConnectUser(access_token, {}, {
  webhook: '',
}, function(err, mfaResponse, response) {
  // The webhook URI should receive a code 4 "webhook acknowledged" webhook 

Exchange a public_token from Plaid Link for a Plaid access token and then retrieve account data:

plaidClient.exchangeToken(public_token, function(err, res) {
  var access_token = res.access_token;
  plaidClient.getAuthUser(access_token, function(err, res) {

Exchange a public_token and account_id from the Plaid + Stripe ACH integration for a Plaid access token and a Stripe bank account token:

plaidClient.exchangeToken(public_token, account_id, function(err, res) {
  var access_token = res.access_token;
  var stripe_token = res.stripe_bank_account_token;
  // Use the access_token to make make Plaid API requests. 
  // Use the Stripe token to make Stripe ACH API requests. 

Promise Support

You can "promisify" this library using a third-party Promise utility library such as Bluebird.

For example, using Bluebird's promisifyAll functionality, we can do:

var bluebird = require('bluebird');
var plaid = require('plaid');
// Promisify the plaid module 
var client = new plaid.Client('test_id', 'test_secret', plaid.environments.tartan);
// bluebird.promisifyAll(plaid) creates a promsified version of each method 
// in the client library suffixed with "Async" 
// i.e. getAuthUser's promsified counterpart is getAuthUserAsync 
client.getAuthUserAsync('test_chase').then(function(authResponse) {
  console.log('You have ' + authResponse.accounts.length + ' accounts!');
}).catch(function(err) {

Callbacks that expect more than one argument pose a challenge for Bluebird. For Plaid API functions that may return an mfa response, use the bluebird multiarg option to get an array.

var bluebird = require('bluebird');
var plaid = require('plaid');
var client = new plaid.Client('test_id', 'test_secret', plaid.environments.tartan);
var addAuthUserAsync = bluebird.promisify(client.addAuthUser, {context: client, multiArgs: true});
addAuthUserAsync('bofa', {
  username: 'plaid_test',
  password: 'plaid_good'
}).then(responses => {
  var mfaResponse = responses[0];
  var response = responses[1];


Open an issue!


$ make test

Code coverage information is written to /coverage.