A node.js client for the Plaid API


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.

$ npm install plaid

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

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_env dictates which Plaid API environment you will access. Values are:

  • plaid.environments.tartan - use for integration development and testing, creates users on
  • plaid.environments.production - production use, creates users on

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

var plaid = require('plaid');

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:

  • plaid.environments.tartan - use for integration development and testing, creates users on
  • plaid.environments.production - production use, creates users on

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);
// 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);
// 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);

All parameters except options are required.

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

function callback(errmfaResponseresponse) {
  // 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(errresponse) {
  // err can be a network error or a Plaid API error (i.e. invalid credentials) 

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(errresponse) {
  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(errmfaResponseresponse) {
  if (err != null) {
    // Bad request - invalid credentials, account locked, etc. 
  } else if (mfaResponse != null) {
    plaidClient.stepAuthUser(mfaResponse.access_token, 'tomato', {},
    function(errmfaResresponse) {
  } 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(errmfaResresponse) {
  // mfaRes.mfa is a list of send_methods 
  plaidClient.stepConnectUser(mfaRes.access_token, null, {
    send_method: mfaRes.mfa[0],
  }, function(errmfaResresponse) {
    // code was sent to the device we specified 
    plaidClient.stepConnectUser(mfaRes.access_token, '1234', function(errmfaResres) {
      // 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(errresponse) {
  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(errmfaResponseresponse) {
  // 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(errres) {
  var access_token = res.access_token;
  plaidClient.getAuthUser(access_token, function(errres) {

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

Open an issue!

$ make test

Code coverage information is written to /coverage.