Overview

Introduction

Welcome to Plaid! Here you’ll find comprehensive information for integrating with Link and our API endpoints. We’ve tried to make this documentation user-friendly and example-filled, but if you have any questions, please head to our Help Center. If you’re planning to use our API in Production, take a look at our Privacy Policy. The fastest way to get your integration up and running is to use our Quickstart guide, which walks through your entire Plaid integration step-by-step. You’ll integrate Plaid Link into your site or app and then use one of our client libraries to retrieve the data you need from our API.

Product
endpoint
Auth POST /auth/get
Transactions POST /transactions/get
Identity POST /identity/get
Income POST /income/get
Balance POST /accounts/balance/get
Assets POST /asset_report/get

Glossary

  • Item: A set of credentials at a financial institution; each Item can have many Accounts, and some Accounts have Transactions associated with them
  • client_id and secret: Two private API keys; used in conjunction with an access_token to access data for an Item
  • public_key: A public API identifier; used to initialize Link and identify Items you create or update via Link
  • access_token: A rotatable token unique to a single Item; used to access data for that Item
  • public_token: A short-lived token that can be exchanged for an access_token or used to initialize Link in update mode for an Item

API keys and access

To gain access to the Plaid API, please create an account on our Dashboard. Once you’ve completed the signup process and acknowledged our terms, we’ll provide a live client_id, secret, and public_key via the Dashboard.

API protocols

The Plaid API uses POST requests to communicate and HTTP response codes to indicate status and errors. All responses come in standard JSON. The Plaid API is served over HTTPS TLS v1.1+ to ensure data privacy; HTTP and HTTPS with TLS versions below 1.1 are not supported. All requests must include a Content-Type of application/json and the body must be valid JSON.

API host

The Sandbox environment is unrestricted and supports only test Items. The Development environment supports up to 100 live Items. All testing should be done in the Sandbox and Development environments. All activity in the Production environment will be billed. When you’re getting ready to launch into Production, please request Production API access via the Dashboard.

Endpoints

Link /item/public_token/exchange
/item/public_token/create
Item management /accounts/get
/item/get
/item/webhook/update
/item/access_token/invalidate
/item/access_token/update_version
/item/remove
Product access /auth/get
/transactions/get
/accounts/balance/get
/identity/get
/income/get
/asset_report/get
/asset_report/pdf/get
Report management /asset_report/create
/asset_report/remove
/asset_report/audit_copy/create
/asset_report/audit_copy/remove
Institutions /institutions/get
/institutions/get_by_id
/institutions/search
Categories /categories/get

Versioning

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

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

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

Plaid Version
          
var plaid = require('plaid');

var plaidClient = new plaid.Client(PLAID_CLIENT_ID, PLAID_SECRET, PLAID_PUBLIC_KEY, plaid.environments.sandbox, {version: '2018-05-22'});
          
        
          
curl -X POST https://sandbox.plaid.com/auth/get \
  -H 'Content-Type: application/json' \
  -H 'Plaid-Version: 2018-05-22'
  ...
          
        
          
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();
          
        
          
from plaid import Client

client = Client(client_id=PLAID_CLIENT_ID, secret=PLAID_SECRET, public_key=PLAID_PUBLIC_KEY, environment='sandbox', version='2018-05-22')
          
        

See the API upgrade guide to see what's changed between versions and find out how to upgrade your integration.

If no API version is specified either when initializing a client library or manually as a request header, the API will default to the version that was live when you first signed up for Plaid API keys.

Breaking changes

We strive to avoid making any breaking changes to our API, but we do make changes over time that may result in changes to the data that you pull from Plaid.

We consider the following changes to be backwards compatible:
  • Adding new API endpoints
  • Adding new options parameters to existing endpoints
  • Adding new data elements to existing response schemas
  • Adding new error_types and error_codes
  • Adding new webhook_types and webhook_codes
  • Changing the length or content of any API identifier

Storing Plaid API indentifiers

It’s important to properly handle Plaid identifiers returned by Link and direct API endpoints. Plaid identifiers let you associate API and Institution events with your requests, and will help our Support team resolve your issues faster and more accurately. Here are some best practices for handling our API identifiers.

Store access_tokens and item_ids in your application database

access_tokens and item_ids are the core identifiers that map your end-users to their financial institutions. You should persist these securely and associate them with users of your application. Make sure, however, that these identifiers are never exposed client-side. Keep in mind that one user can create multiple Items if they have accounts with multiple financial institutions.

access_token

Included in any response that successfully creates an Item.

“access_token”: “access-sandbox-5cd6e1b1-1b5b-459d-9284-366e2da89755” item_id

Included in successful responses for an existing access_token, and specifically for requests to retrieve an Item.

"item_id": "Jv785paMV8hRGWNBRjbjUybw8N9B3yTBDdkwV"
asset_report_token

Included in any response that successfully creates an Asset Report.

"asset_report_token": "assets-sandbox-6f12f5bb-22dd-4855-b918-f47ec439198a"
asset_report_id

Included in successful responses for an existing asset_report_token, and specifically for requests to retrieve an Asset Report.

"asset_report_id": "1f414183-220c-44f5-b0c8-bc0e6d4053bb"
Log API request identifiers

Plaid returns a unique request_id in all server-side responses and Link callbacks. A link_session_id is also returned in Link callbacks. These values can be used for identifying the specific network request or Link session for a user, and associating that request or session with other events in your application. You should log these identifiers as you would other API response metadata.

request_id

Included in all Plaid API success and error responses.

"request_id": "m8MDnv9okwxFNBV"

Included in the onExit, onEvent, and onSuccess callback of a Link integration.

"link_session_id": "f6e63556-7ed9-4d98-b6b1-bfc9f0473593"
Retrieve transaction or account ids

Plaid assigns a unique transaction_id and account_id to the transactions and accounts for each access_token. Please ensure you can easily fetch transaction_ids and account_ids using an access_token, as these identifiers are required to troubleshoot certain support issues. You do not need to persist these identifiers. Note, two access tokens for the same underlying account will produce distinct transaction_ids and account_ids.

account_id

Included in all successful responses for all Plaid products except Income.

"account_id": "yL8je73GrjTZogRqZLrLHLaX3Kb8a1s5z6Jlg"
transaction_id

Included in successful responses for Plaid’s Transactions product.

"transaction_id": "ZXmN54gvBNIJq1aPJrGrFjGg8VJB36IzeWayW"

image of Link service

Plaid Link is a drop-in module that provides a secure, elegant authentication flow for each institution that Plaid supports. Link makes it secure and easy for users to connect their bank accounts to Plaid.

Explore some sample apps or tinker with the demo to see Link in action.

Client-side Link integration
          
<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: 'sandbox',
    // Replace with your public_key from the Dashboard
    key: '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>
<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: 'sandbox',
    // Replace with your public_key from the Dashboard
    key: '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>
<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: 'sandbox',
    // Replace with your public_key from the Dashboard
    key: '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>
<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: 'sandbox',
    // Replace with your public_key from the Dashboard
    key: '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>
<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: 'sandbox',
    // Replace with your public_key from the Dashboard
    key: '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>
        
Server-side Link handler
          
npm install express body-parser plaid
node server.js
          
        
          
gem install sinatra plaid
ruby server.rb
          
        
          
npm install express body-parser plaid
node server.js
          
        
          
npm install express body-parser plaid
node server.js
          
        
          
pip install plaid-python flask
python server.py
          
        
          
var bodyParser = require('body-parser');
var express = require('express');
var plaid = require('plaid');

// 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 client = new plaid.Client(
  'PLAID_CLIENT_ID',
  'PLAID_SECRET',
  'PLAID_PUBLIC_KEY',
  plaid.environments.sandbox
);

// Accept the public_token sent from Link
var app = express();
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) {
      console.log('Could not exchange public_token!' + '\n' + error);
      return response.json({error: msg});
    }
    ACCESS_TOKEN = tokenResponse.access_token;
    ITEM_ID = tokenResponse.item_id;
    console.log('Access Token: ' + ACCESS_TOKEN);
    console.log('Item ID: ' + ITEM_ID);
    response.json({'error': false});
  });
});
app.listen(8000);
          
        
          
require 'sinatra'
require 'plaid'

set :public_folder, File.dirname(FILE) + '/public'
set :port, 8000

client = Plaid::Client.new(env: :sandbox,
                           client_id: 'PLAID_CLIENT_ID',
                           secret: 'PLAID_SECRET',
                           public_key: 'PLAID_PUBLIC_KEY')

access_token = nil

post '/get_access_token' do
  exchange_token_response = client.item.public_token.exchange(params['public_token'])
  access_token = exchange_token_response['access_token']
  item_id = exchange_token_response['item_id']
  puts "access token: #{access_token}"
  puts "item ID: #{item_id}"
  content_type :json
  exchange_token_response.to_json
end
          
        
          
import plaid
from flask import Flask
from flask import render_template
from flask import request
from flask import jsonify

app = Flask(name)

client = plaid.Client('PLAID_CLIENT_ID',
                      'PLAID_SECRET',
                      'PLAID_PUBLIC_KEY',
                      'sandbox')

access_token = None
public_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)
  print 'access token: ' + exchange_response['access_token']
  print 'item ID: ' + exchange_response['item_id']

  return jsonify(exchange_response)

if name == "main":
  app.run(port=8000)
          
        

See the Link parameter reference below for complete documentation on possible configurations.

Plaid.create accepts one argument, a configuration Object, and returns an Object with two functions, open and exit. Calling open will display the "Institution Select" view and calling exit will close Link.

Parameter reference

Parameter Description
clientName
required
Displayed once a user has successfully linked their Item.
product
required
A list of Plaid product(s) you wish to use. Valid products are: transactions, auth, identity, income, and assets. Only institutions that support all requested products will be shown. In Production, you will be billed for each product that you specify when initializing Link.

Example: ['auth', 'transactions']
key
required
The public_key associated with your account; available from the Dashboard.
env
required
The Plaid API environment on which to create user accounts. For Development and Sandbox, use development or sandbox, respectively. For Production use, use production.

Note: all Production requests are billed.
onSuccess
required
A function that is called when a user has successfully onboarded an Item. The function should expect two arguments, the public_token and a metadata object.
onExit
optional
A function that is called when a user has specifically exited the Link flow. The function should expect two arguments, a nullable error object and a metadata object. See onExit.
onEvent
optional
A function that is called when a user reaches certain points in the Link flow. The function should expect two arguments, an eventName string and a metadata object. See onEvent.
onLoad
optional
A function that is called when the Link module has finished loading. Calls to plaidLinkHandler.open() prior to the onLoad callback will be delayed until the module is fully loaded.
webhook
optional
Specify a webhook to associate with an Item. Plaid fires a webhook when the Item requires updated credentials or when new data is available.
token
optional
Specify a public_token to launch Link in update mode for a particular Item. This will cause Link to open directly to the authentication step for that Item's institution.

Use the /item/public_token/create endpoint to generate a public_token for an Item.
isWebview
optional
Set to true if launching Link within a WebView.

Note: Control whether or not your Link integration uses the Select Account view from the Dashboard.

onSuccess callback

The onSuccess callback should take two arguments, the public_token and a metadata object. The metadata object provides the following information:

Parameter Description
link_session_id
String
A unique identifier associated with a user's actions and events through the Link flow. Include this identifier when opening a support ticket for faster turnaround.
institution
Object
An object with two properties: - name: The full institution name, such as 'Bank of America'. - institution_id: The institution ID, such as ins_100000.
accounts
Object
A list of objects with the following properties:
  • id: the id of the selected account
  • name: the name of the selected account
  • mask: the last four digits of the selected account
  • type: the account type
  • subtype: the account subtype
Checkout the Accounts section for more detailed documentation. To collect accounts data, you must enable the Select Account view via the Plaid Dashboard.
onSuccess Example

Plaid.create({
  ...,
  onSuccess: function(public_token, metadata) {
    // public_token = "public-sandbox-5c224a01-8314-4491-a06f..."
    // metadata = {
    //  link_session_id: "123-abc",
    //  institution: {
    //    name: "Wells Fargo",
    //    institution_id: "ins_4"
    //  },
    //  accounts: [{
    //    id: "QPO8Jo8vdDHMepg41PBwckXm4KdK1yUdmXOwK",
    //    name: "Plaid Checking",
    //    mask: "0000",
    //    type: "depository",
    //    subtype: "checking"
    //  }]
    // }

    // Send the public_token to an internal server
    // and exchange it for an access_token.
    fetch("/get_access_token", {
      method: "POST",
      body: {
        public_token: public_token,
        accounts: metadata.accounts,
        institution: metadata.institution,
        link_session_id: metadata.link_session_id,
      },
    });
  },
})
          
Plaid.create({
  ...,
  onSuccess: function(public_token, metadata) {
    // public_token = "public-sandbox-5c224a01-8314-4491-a06f..."
    // metadata = {
    //  link_session_id: "123-abc",
    //  institution: {
    //    name: "Wells Fargo",
    //    institution_id: "ins_4"
    //  },
    //  accounts: [{
    //    id: "QPO8Jo8vdDHMepg41PBwckXm4KdK1yUdmXOwK",
    //    name: "Plaid Checking",
    //    mask: "0000",
    //    type: "depository",
    //    subtype: "checking"
    //  }]
    // }

    // Send the public_token to an internal server
    // and exchange it for an access_token.
    fetch("/get_access_token", {
      method: "POST",
      body: {
        public_token: public_token,
        accounts: metadata.accounts,
        institution: metadata.institution,
        link_session_id: metadata.link_session_id,
      },
    });
  },
})
          
        
          
Plaid.create({
  ...,
  onSuccess: function(public_token, metadata) {
    // public_token = "public-sandbox-5c224a01-8314-4491-a06f..."
    // metadata = {
    //  link_session_id: "123-abc",
    //  institution: {
    //    name: "Wells Fargo",
    //    institution_id: "ins_4"
    //  },
    //  accounts: [{
    //    id: "QPO8Jo8vdDHMepg41PBwckXm4KdK1yUdmXOwK",
    //    name: "Plaid Checking",
    //    mask: "0000",
    //    type: "depository",
    //    subtype: "checking"
    //  }]
    // }

    // Send the public_token to an internal server
    // and exchange it for an access_token.
    fetch("/get_access_token", {
      method: "POST",
      body: {
        public_token: public_token,
        accounts: metadata.accounts,
        institution: metadata.institution,
        link_session_id: metadata.link_session_id,
      },
    });
  },
})
          
        
          
Plaid.create({
  ...,
  onSuccess: function(public_token, metadata) {
    // public_token = "public-sandbox-5c224a01-8314-4491-a06f..."
    // metadata = {
    //  link_session_id: "123-abc",
    //  institution: {
    //    name: "Wells Fargo",
    //    institution_id: "ins_4"
    //  },
    //  accounts: [{
    //    id: "QPO8Jo8vdDHMepg41PBwckXm4KdK1yUdmXOwK",
    //    name: "Plaid Checking",
    //    mask: "0000",
    //    type: "depository",
    //    subtype: "checking"
    //  }]
    // }

    // Send the public_token to an internal server
    // and exchange it for an access_token.
    fetch("/get_access_token", {
      method: "POST",
      body: {
        public_token: public_token,
        accounts: metadata.accounts,
        institution: metadata.institution,
        link_session_id: metadata.link_session_id,
      },
    });
  },
})
          
        
          
Plaid.create({
  ...,
  onSuccess: function(public_token, metadata) {
    // public_token = "public-sandbox-5c224a01-8314-4491-a06f..."
    // metadata = {
    //  link_session_id: "123-abc",
    //  institution: {
    //    name: "Wells Fargo",
    //    institution_id: "ins_4"
    //  },
    //  accounts: [{
    //    id: "QPO8Jo8vdDHMepg41PBwckXm4KdK1yUdmXOwK",
    //    name: "Plaid Checking",
    //    mask: "0000",
    //    type: "depository",
    //    subtype: "checking"
    //  }]
    // }

    // Send the public_token to an internal server
    // and exchange it for an access_token.
    fetch("/get_access_token", {
      method: "POST",
      body: {
        public_token: public_token,
        accounts: metadata.accounts,
        institution: metadata.institution,
        link_session_id: metadata.link_session_id,
      },
    });
  },
})
          
        
Metadata schema

{
  "link_session_id": String,
  "institution": {
    "name": String,
    "institution_id": String
  },
  "accounts": [
    {
      "id": String,
      "name": String,
      "mask": String,
      "type": String,
      "subtype": String
    },
    ...
  ]
}

onExit callback

The onExit callback is called when a user exits the Link flow. It takes two arguments, a nullable error object and a metadata object.

Parameter Description
error
Object
A nullable object that contains the error type, code, and message of the error that was last encountered by the user. If no error was encountered, error will be null.
metadata
Object
An object containing information about the last error encountered by the user (if any), institution selected by the user, and the most recent API request ID, and the Link session ID.

The metadata parameter is always present, though some values may be null.

Metadata status

The value of the status key indicates the point at which the user exited the Link flow. status may be one of the following values:

Status Description
requires_questions User prompted to answer security question(s)
requires_selections User prompted to answer multiple choice question(s)
requires_code User prompted to provide a one-time passcode
choose_device User prompted to select a device on which to receive a one-time passcode
requires_credentials User prompted to provide credentials for the selected financial institution or has not yet selected a financial institution
institution_not_found User exited the Link flow after unsuccessfully (no results returned) searching for a financial institution

The arguments in the onExit function are meant to help you guide your users after they have exited Link. We recommend storing the error and metadata information server-side in a way that can be associated with the user. You’ll also need to include this and any other relevant info in Plaid Support requests for the user.

onExit Example
onExit Example

Plaid.create({
  ...,
  onExit: function(error, metadata) {
    // error = {
    //  display_message: "The credentials were ...",
    //  error_code: "INVALID_CREDENTIALS",
    //  error_message: "the credentials were ...",
    //  error_type: "ITEM_ERROR",
    // }
    // metadata = {
    //  link_session_id: "dc21685c-192e-4969-b4e9-bab890daae31",
    //  institution: {
    //   name: "Wells Fargo",
    //   institution_id: "ins_4"
    //  },
    //  status: "requires_credentials"
    // }

    // Save data from the onExit handler
    supportHandler.report({
      error: error,
      institution: metadata.institution,
      link_session_id: metadata.link_session_id,
      status: metadata.status,
    });
  },
})

Plaid.create({
  ...,
  onExit: function(error, metadata) {
    // error = {
    //  display_message: "The credentials were ...",
    //  error_code: "INVALID_CREDENTIALS",
    //  error_message: "the credentials were ...",
    //  error_type: "ITEM_ERROR",
    // }
    // metadata = {
    //  link_session_id: "dc21685c-192e-4969-b4e9-bab890daae31",
    //  institution: {
    //   name: "Wells Fargo",
    //   institution_id: "ins_4"
    //  },
    //  status: "requires_credentials"
    // }

    // Save data from the onExit handler
    supportHandler.report({
      error: error,
      institution: metadata.institution,
      link_session_id: metadata.link_session_id,
      status: metadata.status,
    });
  },
})

Plaid.create({
  ...,
  onExit: function(error, metadata) {
    // error = {
    //  display_message: "The credentials were ...",
    //  error_code: "INVALID_CREDENTIALS",
    //  error_message: "the credentials were ...",
    //  error_type: "ITEM_ERROR",
    // }
    // metadata = {
    //  link_session_id: "dc21685c-192e-4969-b4e9-bab890daae31",
    //  institution: {
    //   name: "Wells Fargo",
    //   institution_id: "ins_4"
    //  },
    //  status: "requires_credentials"
    // }

    // Save data from the onExit handler
    supportHandler.report({
      error: error,
      institution: metadata.institution,
      link_session_id: metadata.link_session_id,
      status: metadata.status,
    });
  },
})

Plaid.create({
  ...,
  onExit: function(error, metadata) {
    // error = {
    //  display_message: "The credentials were ...",
    //  error_code: "INVALID_CREDENTIALS",
    //  error_message: "the credentials were ...",
    //  error_type: "ITEM_ERROR",
    // }
    // metadata = {
    //  link_session_id: "dc21685c-192e-4969-b4e9-bab890daae31",
    //  institution: {
    //   name: "Wells Fargo",
    //   institution_id: "ins_4"
    //  },
    //  status: "requires_credentials"
    // }

    // Save data from the onExit handler
    supportHandler.report({
      error: error,
      institution: metadata.institution,
      link_session_id: metadata.link_session_id,
      status: metadata.status,
    });
  },
})

Plaid.create({
  ...,
  onExit: function(error, metadata) {
    // error = {
    //  display_message: "The credentials were ...",
    //  error_code: "INVALID_CREDENTIALS",
    //  error_message: "the credentials were ...",
    //  error_type: "ITEM_ERROR",
    // }
    // metadata = {
    //  link_session_id: "dc21685c-192e-4969-b4e9-bab890daae31",
    //  institution: {
    //   name: "Wells Fargo",
    //   institution_id: "ins_4"
    //  },
    //  status: "requires_credentials"
    // }

    // Save data from the onExit handler
    supportHandler.report({
      error: error,
      institution: metadata.institution,
      link_session_id: metadata.link_session_id,
      status: metadata.status,
    });
  },
})
Error object schema

{
  "display_message": String,
  "error_code": String,
  "error_message": String,
  "error_type": String
}
Metadata schema

{
  "link_session_id": String,
  "request_id": String,
  "institution": {
    "name": String,
    "institution_id": String
  },
  "status": String
}

onEvent callback

The onEvent callback is called at certain points in the Link flow. It takes two arguments, an eventName string and a metadata object.

Parameter Description
eventName
String
A string representing the event that has just occurred in the Link flow.
metadata
Object
An object containing information about the event.

The metadata parameter is always present, though some values may be null. Please note that new event names, metadata keys, or view names may be added without notice.

Event names
Event Description
ERROR A recoverable error occurred in the Link flow, see the error_code metadata.
EXIT The user has exited without completing the Link flow and the onExit callback is fired.
HANDOFF The user has completed the Link flow and the onSuccess callback is fired.
OPEN The user has opened Link.
SEARCH_INSTITUTION The user has searched for an institution.
SELECT_INSTITUTION The user selected an institution.
TRANSITION_VIEW The TRANSITION_VIEW event indicates that the user has moved from one view to the next.
Metadata Reference
Field Description
error_code The error code that the user encountered. Emitted by: ERROR, EXIT.
error_message The error message that the user encountered. Emitted by: ERROR, EXIT.
error_type The error type that the user encountered. Emitted by: ERROR, EXIT.
exit_status The status key indicates the point at which the user exited the Link flow. Emitted by: EXIT.
institution_id The ID of the selected institution. Emitted by: all events.
institution_name The name of the selected institution. Emitted by: all events.
institution_search_query The query used to search for institutions. Emitted by: SEARCH_INSTITUTION.
request_id The request ID for the last request made by Link. This can be shared with Plaid Support to expedite investigation. Emitted by: all events.
link_session_id The link_session_id is a unique identifier for a single session of Link. It's always available and will stay constant throughout the flow. Emitted by: all events.
mfa_type If set, the user has encountered one of the following MFA types: code, device, questions, selections. Emitted by: TRANSITION_VIEW when view_name is MFA.
view_name The name of the view that is being transitioned to. Emitted by: TRANSITION_VIEW.
timestamp An ISO 8601 representation of when the event occurred. For example 2017-09-14T14:42:19.350Z. Emitted by: all events.
Metadata view_name
View Displayed when
CONNECTED The user has connected their account.
CREDENTIAL Asking the user for their account credentials.
ERROR An error has occurred.
EXIT Confirming if the user wishes to close Link.
LOADING Link is making a request to our servers.
MFA The user is asked by the institution for additional MFA authentication.
SELECT_ACCOUNT We ask the user to choose an account.
SELECT_INSTITUTION We ask the user to choose their institution.
onEvent Example
onEvent Example

Plaid.create({
  ...,
  onEvent: function(eventName, metadata) {
    // eventName = "TRANSITION_VIEW"
    // metadata  = {
    //   link_session_id: "1dc21685c-192e-4969-b4e9-bab890daae31",
    //   mfa_type:        "questions",
    //   timestamp:       "2017-09-14T14:42:19.350Z",
    //   view_name:       "MFA",
    // }
    // send the event and data to your own analytics service
    analytics.send(eventName, metadata);
  },
})

Plaid.create({
  ...,
  onEvent: function(eventName, metadata) {
    // eventName = "TRANSITION_VIEW"
    // metadata  = {
    //   link_session_id: "1dc21685c-192e-4969-b4e9-bab890daae31",
    //   mfa_type:        "questions",
    //   timestamp:       "2017-09-14T14:42:19.350Z",
    //   view_name:       "MFA",
    // }
    // send the event and data to your own analytics service
    analytics.send(eventName, metadata);
  },
})

Plaid.create({
  ...,
  onEvent: function(eventName, metadata) {
    // eventName = "TRANSITION_VIEW"
    // metadata  = {
    //   link_session_id: "1dc21685c-192e-4969-b4e9-bab890daae31",
    //   mfa_type:        "questions",
    //   timestamp:       "2017-09-14T14:42:19.350Z",
    //   view_name:       "MFA",
    // }
    // send the event and data to your own analytics service
    analytics.send(eventName, metadata);
  },
})

Plaid.create({
  ...,
  onEvent: function(eventName, metadata) {
    // eventName = "TRANSITION_VIEW"
    // metadata  = {
    //   link_session_id: "1dc21685c-192e-4969-b4e9-bab890daae31",
    //   mfa_type:        "questions",
    //   timestamp:       "2017-09-14T14:42:19.350Z",
    //   view_name:       "MFA",
    // }
    // send the event and data to your own analytics service
    analytics.send(eventName, metadata);
  },
})

Plaid.create({
  ...,
  onEvent: function(eventName, metadata) {
    // eventName = "TRANSITION_VIEW"
    // metadata  = {
    //   link_session_id: "1dc21685c-192e-4969-b4e9-bab890daae31",
    //   mfa_type:        "questions",
    //   timestamp:       "2017-09-14T14:42:19.350Z",
    //   view_name:       "MFA",
    // }
    // send the event and data to your own analytics service
    analytics.send(eventName, metadata);
  },
})
EventNames Enum

enum (
  "ERROR"
  "EXIT"
  "HANDOFF"
  "OPEN"
  "SEARCH_INSTITUTION"
  "SELECT_INSTITUTION"
  "TRANSITION_VIEW"
)
Metadata schema

{
  "error_code": String,
  "error_message": String,
  "error_type": String,
  "exit_status": String,
  "institution_id": String,
  "institution_name": String,
  "institution_search_query": String,
  "link_session_id": String,
  "mfa_type": String,
  "request_id": String,
  "timestamp": String,
  "view_name": String
}

open() function

Calling open will display the "Institution Select" view to your user, starting the Link flow. Once open is called, you will begin receiving events via the onEvent callback.

Open to the Select Institution view

Open Link to the Select Institution view Link will handle the whole flow for connecting your users' bank.


// Configure link
var linkHandler = Plaid.create(...)

// Open Link
linkHandler.open();

// Configure link
var linkHandler = Plaid.create(...)

// Open Link
linkHandler.open();

// Configure link
var linkHandler = Plaid.create(...)

// Open Link
linkHandler.open();

// Configure link
var linkHandler = Plaid.create(...)

// Open Link
linkHandler.open();

// Configure link
var linkHandler = Plaid.create(...)

// Open Link
linkHandler.open();

exit() function

The exit function allows you to programmatically close Link. Calling exit will trigger either the onExit or onSuccess callbacks.

The exit function takes a single, optional argument, a configuration Object. The configuration options are:

Option Description
force
Boolean
If true, Link will exit immediately. If false, or the option is not provided, an exit confirmation screen may be presented to the user.

exit() works on desktop and mobile but isn’t supported for WebView integrations. To exit Link in a WebView, you must programmatically close the iOS or Android WebView.

.exit() example

// Initialize Link
var linkHandler = Plaid.create(...)

// Force exit - Link exits immediately
linkHandler.exit({ force: true })

// Graceful exit - Link may display a confirmation screen
// depending on how far the user is in the flow
linkHandler.exit()

// This is equivalent to the above:
linkHandler.exit({ force: false })

// Initialize Link
var linkHandler = Plaid.create(...)

// Force exit - Link exits immediately
linkHandler.exit({ force: true })

// Graceful exit - Link may display a confirmation screen
// depending on how far the user is in the flow
linkHandler.exit()

// This is equivalent to the above:
linkHandler.exit({ force: false })

// Initialize Link
var linkHandler = Plaid.create(...)

// Force exit - Link exits immediately
linkHandler.exit({ force: true })

// Graceful exit - Link may display a confirmation screen
// depending on how far the user is in the flow
linkHandler.exit()

// This is equivalent to the above:
linkHandler.exit({ force: false })

// Initialize Link
var linkHandler = Plaid.create(...)

// Force exit - Link exits immediately
linkHandler.exit({ force: true })

// Graceful exit - Link may display a confirmation screen
// depending on how far the user is in the flow
linkHandler.exit()

// This is equivalent to the above:
linkHandler.exit({ force: false })

// Initialize Link
var linkHandler = Plaid.create(...)

// Force exit - Link exits immediately
linkHandler.exit({ force: true })

// Graceful exit - Link may display a confirmation screen
// depending on how far the user is in the flow
linkHandler.exit()

// This is equivalent to the above:
linkHandler.exit({ force: false })

Exchange Token flow

Exchange a Link public_token for an API access_token. Link hands off the public_token client-side via the onSuccess callback once a user has successfully created an Item. The public_token is ephemeral and expires after 30 minutes. A public_token becomes invalidated once it has been successfully exchanged for an access_token.

The response also includes an item_id that should be stored with the access_token. The item_id is used to identify an Item in a webhook. The item_id can also be retrieved by making an /item/get request.

Field Required?
client_id
String
yes
secret
String
yes
public_token
String
yes
Exchange Token
POST /item/public_token/exchange
Exchange token request

plaidClient.exchangePublicToken(public_token, function(err, apiResponse) {
  var accessToken = apiResponse.access_token;
  var itemId = apiResponse.item_id;
});

curl -X POST https://sandbox.plaid.com/item/public_token/exchange \
  -H 'Content-Type: application/json' \
  -d '{
    "client_id": String,
    "secret": String,
    "public_token": "public-sandbox-5c224a01-8314-4491-a06f-39e193d5cddc"
  }'

response = client.item.public_token.exchange(public_token)
access_token = response['access_token']
item_id = response['item_id']
          
Response response =
  client()
  .service()
  .itemPublicTokenExchange(new ItemPublicTokenExchangeRequest(publicToken))
  .execute();
String accessToken = response.body().getAccessToken();
          
        
          
response = client.Item.public_token.exchange(public_token)
access_token = response['access_token']
item_id = response['item_id']
          
        
Exchange Token response

http code 200
{
  "access_token": "access-sandbox-de3ce8ef-33f8-452c-a685-8671031fc0f6",
  "item_id": "M5eVJqLnv3tbzdngLDp9FL5OlDNxlNhlE55op",
  "request_id": "Aim3b"
}

http code 200
{
  "access_token": "access-sandbox-de3ce8ef-33f8-452c-a685-8671031fc0f6",
  "item_id": "M5eVJqLnv3tbzdngLDp9FL5OlDNxlNhlE55op",
  "request_id": "Aim3b"
}

http code 200
{
  "access_token": "access-sandbox-de3ce8ef-33f8-452c-a685-8671031fc0f6",
  "item_id": "M5eVJqLnv3tbzdngLDp9FL5OlDNxlNhlE55op",
  "request_id": "Aim3b"
}

http code 200
{
  "access_token": "access-sandbox-de3ce8ef-33f8-452c-a685-8671031fc0f6",
  "item_id": "M5eVJqLnv3tbzdngLDp9FL5OlDNxlNhlE55op",
  "request_id": "Aim3b"
}

http code 200
{
  "access_token": "access-sandbox-de3ce8ef-33f8-452c-a685-8671031fc0f6",
  "item_id": "M5eVJqLnv3tbzdngLDp9FL5OlDNxlNhlE55op",
  "request_id": "Aim3b"
}

Creating Public Tokens

A public_token is one-time use and expires after 30 minutes. You use a public_token to initialize Link in update mode for a particular Item.

If you need your user to take action to restore or resolve an error associated with an Item, generate a public token with the POST /item/public_token/create endpoint and then initialize Link with that public_token.

You can generate a public_token for an Item even if you did not use Link to create the Item originally.

Field Required?
client_id
String
yes
secret
String
yes
access_token
String
yes
Create Public Token
POST /item/public_token/create
Create Public Token request

// Create a public_token for use with Plaid Link's update mode
client.createPublicToken(ACCESS_TOKEN, (err, result) => {
  // Handle err
  // Use the generated public_token to initialize Plaid Link in update
  // mode for a user's Item so that they can provide updated credentials
  // or MFA information
  const publicToken = result.public_token;
});

curl -X POST https://sandbox.plaid.com/item/public_token/create \
  -H 'Content-Type: application/json' \
  -d '{
    "client_id": String,
    "secret": String,
    "access_token": "access-sandbox-de3ce8ef-33f8-452c-a685-8671031fc0f6"
  }'

# create a public_token for use with Plaid Link's update mode
response = client.item.public_token.create(access_token)
# use the generated public_token to initialize Plaid Link in update
# mode for a user's Item so that they can provide updated credentials
# or MFA information
public_token = response['public_token']
          
// Create a public_token for use with Plaid Link's update mode
Response<ItemPublicTokenCreateResponse> response =
  client().service().itemPublicTokenCreate(
   new ItemPublicTokenCreateRequest("ACCESS_TOKEN")).execute();
String publicToken;
if (response.isSuccessful()) {
  // Use the generated public_token to initialize Plaid Link in update
  // mode for a user's Item so that they can provide updated credentials
  // or MFA information
  publicToken = response.body().getPublicToken();
}
          
        
          
# create a public_token for use with Plaid Link's update mode
create_response = client.Item.public_token.create(access_token)
# use the generated public_token to initialize Plaid Link in update
# mode for a user's Item so that they can provide updated credentials
# or MFA information
public_token = response['public_token']
          
        
Create Public Token response

http code 200
{
  "public_token": "public-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d",
  "request_id": "Aim3b"
}

http code 200
{
  "public_token": "public-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d",
  "request_id": "Aim3b"
}

http code 200
{
  "public_token": "public-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d",
  "request_id": "Aim3b"
}

http code 200
{
  "public_token": "public-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d",
  "request_id": "Aim3b"
}

http code 200
{
  "public_token": "public-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d",
  "request_id": "Aim3b"
}

Over time, Items may need to refresh authentication information. This can happen if the user changes a password, if MFA requirements change, or if the login becomes locked. Link’s update mode makes the reauthentication process secure and painless.

To use update mode for an Item, initialize Link with a public_token for the Item that you wish to update. Link auto-detects the appropriate institution and handles the credential and multi-factor authentication process, if needed.

An Items access_token does not change when using Link in update mode, so there is no need to repeat the exchange token process.

Link will automatically detect the institution ID associated with the public_token and present the appropriate credential view to your user.

iOS bindings

Plaid Link WebView example

Plaid Link for iOS is a native SDK for iOS 8+ that brings the same features and functionality that exist with Link on the web to iOS. Best of all, Plaid Link for iOS requires zero changes to your backend integration.

Looking to get started right away?
github icon

Jump to the iOS examples for complete sample apps in Swift and Objective-C that use the embeddable LinkKit.framework to manage the details of linking an account with Plaid.

Check out example apps


Consult the documentation to learn about the details on how to integrate Plaid Link for iOS in your application.

Read the iOS integration guide

WebView integration

Plaid Link WebView example Link is optimized to work within WebViews, including on iOS and Android. The Link initialization URL that’s optimized for WebViews is:
Link WebView initialization URL

The Link configuration options for a WebView integration are passed via querystring rather than via a client-side Javascript call. See the parameter reference for complete documentation. Read on for example WebView initialization URls for common Link use cases.

Looking to get started right away?

Jump to the WebView examples for sample apps for iOS WKWebView and Android WebView! The sample code includes examples to initialize Link and process events communicated from Link to your app.

Check out example apps

Communication between the WebView and your app is handled by HTTP redirects rather than client-side JavaScript callbacks. These redirects should be intercepted by your app. The example apps include sample code to do this.

All redirect URLs have the scheme plaidlink. The event type is communicated via the URL host and data is passed via the querystring. There are two supported events, connected and exit, which are documented below.

connected event

The connected event is analogous to the onSuccess callback and is sent when the user completes the Link flow. The following information is available from the querystring:

Field Description
public_token Link public_token that is exchanged for an API access_token
accounts JSON-stringified representation of the account(s) selected by the user in the shape of [Object].

Enable the Select Account view to collect this data.
institution_id The institution ID, such as 'ins_100000'
institution_name The full institution name, such as 'Bank of America'
connected event example

plaidlink://connected
  ?public_token=public-sandbox-fb7cca4a-82e6-4707
  &accounts='[{"name":"Plaid Savings","id":"QPO8Jo8vdDHMepg41PBwckXm4KdK1yUdmXOwK"}]'
  &institution_id=ins_3
  &institution_name=Chase
exit event

The exit event is analogous to the onExit callback and is sent when the user exits the Link flow. The following information is available from the querystring:

Field Description
status The user’s status in the Link flow when they exited. See the possible values
error_code The error code that the user encountered
error_message The error message that the user encountered
institution_id The institution ID, such as 'ins_100000'
institution_name The full institution name, such as 'Bank of America'
link_session_id A unique identifier for a single session of Link. It's always available and will stay constant throughout the flow
exit event example

plaidlink://exit
  ?status=requires_credentials
  &error_code=ITEM_LOGIN_REQUIRED
  &error_display_message=The%20provided%20credentials%20were%20not%20correct.%20Please%20try%20again.
  &error_message=the%20provided%20credentials%20were%20not%20correct
  &error_type=ITEM_ERROR
  &institution_id=ins_3
  &institution_name=Chase
  &request_id=m8MDnv9okwxFNBV
event event

The event event is analogous to the onEvent callback and is called as the user moves through the Link flow. The querystring will always contain all possible keys though not all keys will have values. The event_name will dictate which keys are populated (see the onEvent callback to understand when each key is guaranteed to have a value).

Field Description
event_name A string representing the event that has just occurred in the Link flow
view_name The Link view that the user navigated to.
error_code The error code that the user encountered
error_message The error message that the user encountered
error_type The error type that the user encountered
institution_id The institution ID, such as 'ins_100000'
institution_name The full institution name, such as 'Bank of America'
link_session_id A unique identifier for a single session of Link. It's always available and will stay constant throughout the flow
event event example

plaidlink://event
  ?error_code
  &error_message
  &error_type
  &event_name=SELECT_INSTITUTION
  &exit_status
  &institution_id=ins_13
  &institution_name=PNC
  &institution_search_query
  &link_session_id=821f45a8-854a-4dbb-8e5f-73f75350e7e7
  &mfa_type
  &request_id
  &timestamp=2018-10-05T15%3A22%3A50.542Z
  &view_name
WebView examples

To get your Link WebView integration started, check out our example apps, available for iOS and Android.

Each example app is runnable (on both simulators and devices) and includes code to initialize Link and process events sent from Link to your app via HTTP redirects.


https://cdn.plaid.com/link/v2/stable/link.html
  ?isWebview=true
  &key=[PUBLIC_KEY]
  &env=sandbox
  &product=transactions,auth
  &clientName=Plaid%20Demo

https://cdn.plaid.com/link/v2/stable/link.html
  ?isWebview=true
  &key=[PUBLIC_KEY]
  ...
  &token=[GENERATED_PUBLIC_TOKEN]

Browser support

Desktop
chrome Fully supported
firefox Fully supported
safari Fully supported
ie10 10    Fully supported
Mobile

Modern mobile browsers are supported, including most iPhone and Android devices. If you encounter any inconsistencies, head to the Help Center.


Item product access

Auth

The /auth/get endpoint allows you to retrieve the bank account and routing numbers associated with an Item’s checking and savings accounts, along with high-level account data and balances.

The Auth product performs two crucial functions. It translates bank access credentials (username and password) into an account and routing number. No input of account or routing number is necessary. This eliminates the need for micro-deposits or any other secondary authentication.

Note: This request may take some time to complete if auth was not specified as an initial product when creating the Item. This is because Plaid must communicate directly with the institution to retrieve the data.

Field Required?
client_id
String
yes
secret
String
yes
access_token
String
yes
options
Object
no
Field Default Description
account_ids
[String]
null A list of account_ids to retrieve for the Item.

Note: An error will be returned if a provided account_id is not associated with the Item.
Retrieve Auth
POST /auth/get
Retrieve Auth request

// Use Auth and pull account numbers for an Item
client.getAuth(accessToken, {}, (err, results) => {
  // Handle err
  var accountData = results.accounts;
  if (results.numbers.ach.length > 0) {
    // Handle ACH numbers (US accounts)
    var achNumbers = results.numbers.ach;
  } else if (results.numbers.eft.length > 0) {
    // Handle EFT numbers (Canadian accounts)
    var eftNumbers = results.numbers.eft;
  }
});

curl -X POST https://sandbox.plaid.com/auth/get \
-H 'Content-Type: application/json' \
-d '{
  "client_id": String,
  "secret": String,
  "access_token": String
}'

# Use Auth and pull account numbers for an Item
response = @client.auth.get(@access_token)
numbers = response[:numbers]
if numbers[:ach].length > 0
  # Handle ACH numbers (US accounts)
  achNumbers = numbers[:ach]
elsif numbers[:eft].length > 0
  # Handle EFT numbers (Canadian accounts)
  eftNumbers = numbers[:eft]
end

// Use Auth and pull account numbers for an Item
Response<AuthGetResponse> response =
  client().service().authGet(new AuthGetRequest("ACCESS_TOKEN")).execute();
if (response.body().getNumbers().getACH().length() > 0) {
  // Handle ACH numbers (US accounts)
  for (AuthGetResponse.NumberACH numberACH : response.body().getNumbers().getACH()) { ... }
} else if (esponse.body().getNumbers().getEFT().length() > 0) {
  // Handle EFT numbers (Canadian accounts)
  for (AuthGetResponse.NumberEFT numberEFT : response.body().getNumbers().getEFT()) { ... }
}

# Use Auth and pull account numbers for an Item
response = client.Auth.get(access_token)
numbers = response['numbers']
if len(numbers['ach']) > 0:
  # Handle ACH numbers (US accounts)
  achNumbers = numbers['ach']
elif len(numbers['eft']) > 0:
  # Handle EFT numbers (Canadian accounts)
  eftNumbers = numbers['eft']
Retrieve Auth Response - ACH numbers

http code 200
{
  "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 Checking",
    "subtype": "checking",
    "type": "depository"
  }],
  "numbers": {
     "ach": [{
      "account": "9900009606",
      "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
      "routing": "011401533",
      "wire_routing": "021000021"
     }],
     "eft": []
  },
  "item": {Object},
  "request_id": "45QSn"
}

http code 200
{
  "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 Checking",
    "subtype": "checking",
    "type": "depository"
  }],
  "numbers": {
     "ach": [{
      "account": "9900009606",
      "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
      "routing": "011401533",
      "wire_routing": "021000021"
     }],
     "eft": []
  },
  "item": {Object},
  "request_id": "45QSn"
}

http code 200
{
  "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 Checking",
    "subtype": "checking",
    "type": "depository"
  }],
  "numbers": {
     "ach": [{
      "account": "9900009606",
      "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
      "routing": "011401533",
      "wire_routing": "021000021"
     }],
     "eft": []
  },
  "item": {Object},
  "request_id": "45QSn"
}

http code 200
{
  "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 Checking",
    "subtype": "checking",
    "type": "depository"
  }],
  "numbers": {
     "ach": [{
      "account": "9900009606",
      "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
      "routing": "011401533",
      "wire_routing": "021000021"
     }],
     "eft": []
  },
  "item": {Object},
  "request_id": "45QSn"
}

http code 200
{
  "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 Checking",
    "subtype": "checking",
    "type": "depository"
  }],
  "numbers": {
     "ach": [{
      "account": "9900009606",
      "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
      "routing": "011401533",
      "wire_routing": "021000021"
     }],
     "eft": []
  },
  "item": {Object},
  "request_id": "45QSn"
}
Retrieve Auth Response - EFT numbers

http code 200
{
  "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 Checking",
    "subtype": "checking",
    "type": "depository"
  }],
  "numbers": {
     "ach": [],
     "eft": [{
      "account": "111122223333",
      "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
      "institution": "01140",
      "branch": "021"
     }]
  },
  "item": {Object},
  "request_id": "45QSn"
}

http code 200
{
  "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 Checking",
    "subtype": "checking",
    "type": "depository"
  }],
  "numbers": {
     "ach": [],
     "eft": [{
      "account": "111122223333",
      "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
      "institution": "01140",
      "branch": "021"
     }]
  },
  "item": {Object},
  "request_id": "45QSn"
}

http code 200
{
  "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 Checking",
    "subtype": "checking",
    "type": "depository"
  }],
  "numbers": {
     "ach": [],
     "eft": [{
      "account": "111122223333",
      "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
      "institution": "01140",
      "branch": "021"
     }]
  },
  "item": {Object},
  "request_id": "45QSn"
}

http code 200
{
  "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 Checking",
    "subtype": "checking",
    "type": "depository"
  }],
  "numbers": {
     "ach": [],
     "eft": [{
      "account": "111122223333",
      "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
      "institution": "01140",
      "branch": "021"
     }]
  },
  "item": {Object},
  "request_id": "45QSn"
}

http code 200
{
  "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 Checking",
    "subtype": "checking",
    "type": "depository"
  }],
  "numbers": {
     "ach": [],
     "eft": [{
      "account": "111122223333",
      "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
      "institution": "01140",
      "branch": "021"
     }]
  },
  "item": {Object},
  "request_id": "45QSn"
}

Transactions

The /transactions/get endpoint allows developers to receive user-authorized transaction data for credit and depository-type Accounts. Transaction data is standardized across financial institutions, and in many cases transactions are linked to a clean name, entity type, location, and category. Similarly, account data is standardized and returned with a clean name, number, balance, and other meta information where available.

Transaction data elements
Key Description
transaction_id
String
The unique ID of the transaction.
account_id
String
The ID of the account in which this transaction occurred.
category
[String], nullable
A hierarchical array of the categories to which this transaction belongs. See Categories.
category_id
String, nullable
The ID of the category to which this transaction belongs. See Categories.
transaction_type
String
digital: transactions that took place online.
place: transactions that were made at a physical location.
special: transactions that relate to banks, e.g. fees or deposits.
unresolved: transactions that do not fit into the other three types.
name
String
The merchant name or transaction description.
amount
Number
The settled dollar value. Positive values when money moves out of the account; negative values when money moves in. For example, purchases are positive; credit card payments, direct deposits, refunds are negative.
iso_currency_code
String, nullable
The ISO currency code of the transaction, either USD or CAD. Always null if unofficial_currency_code is non-null.
unofficial_currency_code
String, nullable
The unofficial currency code associated with the transaction. Always null if iso_currency_code is non-null.
date
String
For pending transactions, Plaid returns the date the transaction occurred; for posted transactions, Plaid returns the date the transaction posts. Both dates are returned in an ISO 8601 format (YYYY-MM-DD).
location
Object
Information about where the transaction occurred. The location key will always be an Object, but no location data elements are guaranteed.
payment_meta
Object
Information about where the transaction occurred. The payment_meta key will always be an Object, but no payment_meta data elements are guaranteed.
pending
Boolean
When true, identifies the transaction as pending or unsettled. Pending transaction details (name, type, amount, category ID) may change before they are settled.
pending_transaction_id
String, nullable
The ID of a posted transaction's associated pending transaction—where applicable.
account_owner
String, nullable
The name of the account owner. This field is not typically populated and only relevant when dealing with sub-accounts.
Transaction location data
Key Description
address
String, nullable
The street address where the transaction occurred.
city
String, nullable
The city where the transaction occurred.
state
String, nullable
The state where the transaction occurred.
zip
String, nullable
The zip code where the transaction occurred.
lat
Number, nullable
The latitude where the transaction occurred.
lon
Number, nullable
The longitude where the transaction occurred.
Transaction payment meta data
Key Description
reference_number
String, nullable
The transaction reference number supplied by the financial institution.
ppd_id
String, nullable
The ACH PPD ID for the payer.
payee_name
String, nullable
For transfers, the party that is receiving the transaction.
Retrieve Transactions
POST /transactions/get

To retrieve transaction data for an Item, use the /transactions/get endpoint.

Due to the potentially large number of transactions associated with an Item, results are paginated. Manipulate the count and offset parameters in conjunction with the total_transactions response body field to fetch all available Transactions.

Field Required? Description
client_id
String
yes
secret
String
yes
access_token
String
yes
start_date
Date
yes Dates should be formatted as YYYY-MM-DD
end_date
Date
yes Dates should be formatted as YYYY-MM-DD
options
Object
no If provided, must be non-null.

The following options are available:

Field Default Description
account_ids
[String]
null A list of account_ids to retrieve for the Item.

Note: An error will be returned if a provided account_id is not associated with the Item
count
Number
100 The number of transactions to fetch, where 0 < count <= 500.
offset
Number
0 The number of transactions to skip, where offset >= 0.
Retrieve Transactions request

// Pull transactions for a date range
client.getTransactions(accessToken, '2018-01-01', '2018-02-01', {
  count: 250,
  offset: 0,
}, (err, result) => {
  // Handle err
  const transactions = result.transactions;
});

curl -X POST https://sandbox.plaid.com/transactions/get \
-H 'Content-Type: application/json' \
-d '{
  "client_id": String,
  "secret": String,
  "access_token": String,
  "start_date": "2018-01-01",
  "end_date": "2018-02-01",
  "options": {
    "count": 250,
    "offset": 100
  }
}'

# Pull transactions for a date range
response = @client.transactions.get(@access_token,
                                    '2018-01-01',
                                    '2018-02-01')

# Manipulate the count and offset parameters to paginate
# transactions and retrieve all available data
response = @client.transactions.get(@access_token,
                                    '2018-01-01',
                                    '2018-02-01',
                                    count: 250,
                                    offset: 0)
total_transactions = response['total_transactions']

SimpleDateFormat simpleDateFormat = new SimpleDateFormat("yyyy-MM-dd");
startDate = simpleDateFormat.parse("2018-01-01");
endDate = simpleDateFormat.parse("2018-02-01");
// Pull transactions for a date range
Response<TransactionsGetResponse> response = client().service().transactionsGet(
  new TransactionsGetRequest(
    "ACCESS_TOKEN",
    startDate,
    endDate))
  .execute();

// Manipulate the count and offset parameters to paginate
// transactions and retrieve all available data
Response<TransactionsGetResponse> response = client().service().transactionsGet(
  new TransactionsGetRequest(
    accessToken,
    startDate,
    endDate)
    .withAccountIds(Arrays.asList(someAccountId))
    .withCount(numTxns)
    .withOffset(1)).execute();

for (TransactionsGetResponse.Transaction txn : response.body().getTransactions()) { ... }

response = client.Transactions.get(access_token,
                                   start_date='2018-01-01',
                                   end_date='2018-02-01')
transactions = response['transactions']

# Manipulate the count and offset parameters to paginate
# transactions and retrieve all available data
while len(transactions) < response['total_transactions']:
    response = client.Transactions.get(access_token,
                                       start_date='2018-01-01',
                                       end_date='2018-02-01',
                                       offset=len(transactions)
                                      )
    transactions.extend(response['transactions'])
Retrieve Transactions response

http code 200
{
 "accounts": [{object}],
 "transactions": [{
    "account_id": "vokyE5Rn6vHKqDLRXEn5fne7LwbKPLIXGK98d",
    "amount": 2307.21,
    "iso_currency_code": "USD",
    "unofficial_currency_code": null,
    "category": [
      "Shops",
      "Computers and Electronics"
    ],
    "category_id": "19013000",
    "date": "2017-01-29",
    "location": {
     "address": "300 Post St",
     "city": "San Francisco",
     "state": "CA",
     "zip": "94108",
     "lat": null,
     "lon": null
    },
    "name": "Apple Store",
    "payment_meta": Object,
    "pending": false,
    "pending_transaction_id": null,
    "account_owner": null,
    "transaction_id": "lPNjeW1nR6CDn5okmGQ6hEpMo4lLNoSrzqDje",
    "transaction_type": "place"
   }, {
    "account_id": "XA96y1wW3xS7wKyEdbRzFkpZov6x1ohxMXwep",
    "amount": 78.5,
    "iso_currency_code": "USD",
    "unofficial_currency_code": null,
    "category": [
      "Food and Drink",
      "Restaurants"
    ],
    "category_id": "13005000",
    "date": "2017-01-29",
    "location": {
      "address": "262 W 15th St",
      "city": "New York",
      "state": "NY",
      "zip": "10011",
      "lat": 40.740352,
      "lon": -74.001761
    },
    "name": "Golden Crepes",
    "payment_meta": Object,
    "pending": false,
    "pending_transaction_id": null,
    "account_owner": null,
    "transaction_id": "4WPD9vV5A1cogJwyQ5kVFB3vPEmpXPS3qvjXQ",
    "transaction_type": "place"
  }],
  "item": {Object},
  "total_transactions": Number,
  "request_id": "45QSn"
}
Item transaction updates

After an Item is added, Plaid begins a process to collect, parse, and clean all of the Item's most recent transactions over the next 30-240 seconds. If a webhook is provided, you’ll get a notification as soon as that process is complete. After that, we’ll update the Item’s data at set intervals throughout the day to collect all of the most recent transactions. An Item’s account and transaction data may be retrieved at any time from our /transactions/get endpoint.

Transactions are pulled as they are posted to the issuing institution. Dependent on the merchant acquirer, processor, gateway and issuer, the time from when a transaction occurs to when it's posted can be from a few minutes to a few days. The date listed in transaction will be as close to the original transaction date as possible.

Full transaction history

After the initial Item transaction pull, you should receive a webhook for the INITIAL_UPDATE, after which we will pull all available transactional history for the Item.

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. To see more information on data availability by institution, please visit our Help Center.

Balance

The /accounts/balance/get endpoint returns the real-time balance for each of an Item’s accounts. It can be used for existing Items that were added via any of Plaid’s other products.

The current balance is the total amount of funds in the account. The available balance is the amount of funds available to be withdrawn from an account, as determined by the financial institution. The available balance typically, but not always, equals the current balance less any pending outflows plus any pending inflows.

Note that not all institutions calculate the available balance. In the event that available balance is unavailable from the institution, Plaid will return an available balance value of null.

Field Required?
client_id
String
yes
secret
String
yes
access_token
String
yes
options
Object
no

The following options are available:

Field Default Description
account_ids
[String]
null A list of account_ids to retrieve for the Item.

Note: An error will be returned if a provided account_id is not associated with the Item.
Retrieve Balance
POST /accounts/balance/get
Retrieve Balance request

// Pull real-time balance information for each account associated
// with the Item
client.getBalance(ACCESS_TOKEN, (err, result) => {
  // Handle err
  const accounts = result.accounts;
});

curl -X POST https://sandbox.plaid.com/accounts/balance/get \
-H 'Content-Type: application/json' \
-d '{
  "client_id": String,
  "secret": String,
  "access_token": String,
  "options": {
    "account_ids": [String]
  }
}'

# Pull real-time balance information for each account associated
# with the Item
response = @client.accounts.balance.get(@access_token)
accounts = response[:accounts]

// Pull real-time balance information for each account associated
// with the Item
Response<AccountsBalanceGetResponse> response = client().service().accountsBalanceGet(
  new AccountsBalanceGetRequest("ACCESS_TOKEN"))
  .execute();
List<Account> accounts = response.body().getAccounts();

# Pull real-time balance information for each account associated
# with the Item
response = client.Accounts.balance.get(access_token)
accounts = response['accounts']
Retrieve Balance response

http code 200
{
  "accounts": [{
     "account_id": "QKKzevvp33HxPWpoqn6rI13BxW4awNSjnw4xv",
     "balances": {
       "available": 100,
       "current": 110,
       "limit": null,
       "iso_currency_code": "USD",
       "unofficial_currency_code": null
     },
     "mask": "0000",
     "name": "Plaid Checking",
     "official_name": "Plaid Gold Checking",
     "subtype": "checking",
     "type": "depository"
  }],
  "item": {object},
  "request_id": "m8MDnv9okwxFNBV"
}

Identity

The /identity/get endpoint allows you to retrieve various account holder information on file with the financial institution, including names, emails, phone numbers, and addresses.

Note: This request may take some time to complete if identity was not specified as an initial product when creating the Item. This is because Plaid must communicate directly with the institution to retrieve the data.

Field Required?
client_id
String
yes
secret
String
yes
access_token
String
yes
Retrieve Identity
POST /identity/get
Retrieve Identity request

// Pull Identity data for an Item
client.getIdentity(accessToken, (err, result) => {
  // Handle err
  const identity = result.identity;
});

curl -X POST https://sandbox.plaid.com/identity/get \
-H 'Content-Type: application/json' \
-d '{
  "client_id": String,
  "secret": String,
  "access_token": String
}'

# pull identity data for an item
response = @client.identity.get(@access_token)
identity = response[:identity]

// Pull Identity data for an Item
Response<IdentityGetResponse> response = client().service().identityGet(
  new IdentityGetRequest("ACCESS_TOKEN")
).execute();
IdentityGetResponse.Identity identity = response.body().getIdentity();

# pull identity data for an item
response = client.Identity.get(access_token)
identity = response['identity']
Retrieve Identity response

http code 200
{
  "accounts": [{object}],
  "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
      },
      {
        "accounts": [
          "Plaid Credit Card 3333"
        ],
        "data": {
          "city": "San Matias",
          "state": "CA",
          "street": "2493 Leisure Lane",
          "zip": "93405-2255"
        },
        "primary": false
      }
    ],
    "emails": [
      {
        "data": "accountholder0@example.com",
        "primary": true,
        "type": "primary"
      }
    ],
    "names": [
      "Alberta Bobbeth Charleson"
    ],
    "phone_numbers": [{
      "primary": true,
      "type": "home",
      "data": "4673956022"
    }],
  },
  "item": {object},
  "request_id": "m8MDnv9okwxFNBV"
}

Income

The /income/get endpoint allows you to retrieve information pertaining to a Item’s income. In addition to the annual income, detailed information will be provided for each contributing income stream (or job). Details on each of these fields can be found below.

Field Required?
client_id
String
yes
secret
String
yes
access_token
String
yes
Income data elements
Key Description
last_year_income
Number
The sum of the Item’s income over the past 365 days. If we have less than 365 days of data this will be less than a full year's income.
last_year_income_before_tax
Number
last_year_income interpolated to value before taxes. This is the minimum pre-tax salary that assumes a filing status of single with zero dependents.
projected_yearly_income
Number
Item’s income extrapolated over a year based on current, active income streams. Income streams become inactive if they have not recurred for more than two cycles. For example, if a weekly paycheck hasn’t been seen for the past two weeks, it's no longer active.
projected_yearly_income_before_tax
Number
projected_yearly_income interpolated to value before taxes. This is the minimum pre-tax salary that assumes a filing status of single with zero dependents.
income_streams
[Object]
An array of income streams with detailed information on each. See income streams.
max_number_of_overlapping_income_streams
Number
Max number of income streams present at the same time over the past 365 days.
number_of_income_streams
Number
Total number of distinct income streams received over the past 365 days.
Income streams
Key Description
monthly_income
Number
The monthly income associated with the income stream
confidence
Number
A numeric representation of our confidence in the income data associated with this particular income stream, with 0 being the lowest confidence and 1 being the highest
days
Number
Extent of data found for this income stream
name
String
Name of the entity associated with this income stream
Retrieve Income
POST /income/get
Retrieve Income request

// Retrieve Income data for an Item
client.getIncome(accessToken, function(err, result) {
  // Handle err
  var income = result.income;
});

curl -X POST https://sandbox.plaid.com/income/get \
-H 'Content-Type: application/json' \
-d '{
  "client_id": String,
  "secret": String,
  "access_token": String
}'

# retrieve Income data for an Item
income_response = client.income.get(access_token)

// Retrieve Income data for an Item
Response<IncomeGetResponse> response =
  client().service().incomeGet(new IncomeGetRequest(ACCESS_TOKEN)).execute();
Income income = response.getIncome();
List<IncomeStreams> incomeStreams = income.getIncomeStreams();

# retrieve Income data for an Item
income_response = client.Income.get(access_token)
Retrieve Income response

http code 200
{
  "item": {Object},
  "income": {
    "income_streams": [
      {
        "confidence": 1,
        "days": 518,
        "monthly_income": 1601,
        "name": "PLAID"
      },
      {
        "confidence": 0.95,
        "days": 415,
        "monthly_income": 1530,
        "name": "BAGUETTES INC"
      }
    ],
    "last_year_income": 28072,
    "last_year_income_before_tax": 38681,
    "projected_yearly_income": 19444,
    "projected_yearly_income_before_tax": 26291,
    "max_number_of_overlapping_income_streams": 2,
    "number_of_income_streams": 2
  },
  "request_id": "x9a1xa"
}

http code 200
{
  "item": {Object},
  "income": {
    "income_streams": [
      {
        "confidence": 1,
        "days": 518,
        "monthly_income": 1601,
        "name": "PLAID"
      },
      {
        "confidence": 0.95,
        "days": 415,
        "monthly_income": 1530,
        "name": "BAGUETTES INC"
      }
    ],
    "last_year_income": 28072,
    "last_year_income_before_tax": 38681,
    "projected_yearly_income": 19444,
    "projected_yearly_income_before_tax": 26291,
    "max_number_of_overlapping_income_streams": 2,
    "number_of_income_streams": 2
  },
  "request_id": "x9a1xa"
}

http code 200
{
  "item": {Object},
  "income": {
    "income_streams": [
      {
        "confidence": 1,
        "days": 518,
        "monthly_income": 1601,
        "name": "PLAID"
      },
      {
        "confidence": 0.95,
        "days": 415,
        "monthly_income": 1530,
        "name": "BAGUETTES INC"
      }
    ],
    "last_year_income": 28072,
    "last_year_income_before_tax": 38681,
    "projected_yearly_income": 19444,
    "projected_yearly_income_before_tax": 26291,
    "max_number_of_overlapping_income_streams": 2,
    "number_of_income_streams": 2
  },
  "request_id": "x9a1xa"
}

http code 200
{
  "item": {Object},
  "income": {
    "income_streams": [
      {
        "confidence": 1,
        "days": 518,
        "monthly_income": 1601,
        "name": "PLAID"
      },
      {
        "confidence": 0.95,
        "days": 415,
        "monthly_income": 1530,
        "name": "BAGUETTES INC"
      }
    ],
    "last_year_income": 28072,
    "last_year_income_before_tax": 38681,
    "projected_yearly_income": 19444,
    "projected_yearly_income_before_tax": 26291,
    "max_number_of_overlapping_income_streams": 2,
    "number_of_income_streams": 2
  },
  "request_id": "x9a1xa"
}

http code 200
{
  "item": {Object},
  "income": {
    "income_streams": [
      {
        "confidence": 1,
        "days": 518,
        "monthly_income": 1601,
        "name": "PLAID"
      },
      {
        "confidence": 0.95,
        "days": 415,
        "monthly_income": 1530,
        "name": "BAGUETTES INC"
      }
    ],
    "last_year_income": 28072,
    "last_year_income_before_tax": 38681,
    "projected_yearly_income": 19444,
    "projected_yearly_income_before_tax": 26291,
    "max_number_of_overlapping_income_streams": 2,
    "number_of_income_streams": 2
  },
  "request_id": "x9a1xa"
}

Assets

The /asset_report/get and /asset_report/pdf/get endpoints allow you to retrieve point-in-time snapshots of an Item or set of Items, including account balances, historical transactions, and account holder identity information, which we call Asset Reports.

In addition to the Item data retrieved from the financial institution via Plaid, you can append additional data that you supply to the Asset Report such as your own tracking ID and information about the user; some of these client-submitted fields are required for various partner programs like Fannie Mae's Day 1 Certainty™, but are otherwise optional.

Asset Reports are intended to be created on a per-user basis. In the context of a loan application, for example, the lender would create an Asset Report for each borrower on a given loan.

Finally, Asset Reports are immutable, meaning they can only be created and removed, not updated. If you would like to retrieve updated transactions and balances, for example, you can simply create a new Asset Report by submitting the same access_tokens and other information you provided when creating the original Report.

With your desired access_tokens in hand, all you need to do to create an Asset Report is to call the /asset_report/create endpoint. For a description of each required and optional parameter, see the Assets parameter reference.

To obtain an Asset Report for a given user, you’ll need to complete the following steps:

  1. Create Items for each of the user’s institutions, using Plaid Link
  2. Create the Asset Report using the access_tokens for each of those Items
  3. Retrieve the Asset Report in your desired format
  4. Share the Asset Report (optional) by obtaining an audit_copy_token and then passing it to a participating third party, for example Fannie Mae as part of its Day 1 Certainty™ program
1. Create Items

First, you'll obtain an access_token for each of the user's institutions by creating Items with Plaid Link. In order for an access_token to be used to obtain an Asset Report, it must have been generated with assets included in Link's product array (see the Link parameter reference above); otherwise, you will encounter a PRODUCT_NOT_ENABLED error when creating an Asset Report with that access_token.

If the user needs to link accounts at multiple institutions, simply repeat the Link flow for each, instructing the user to authenticate the next institution until they have linked all of their intended Items. You can include multiple Items in a single Asset Report by including an access_token for each Item.

2. Create an Asset Report

With your desired access_tokens in hand, all you need to do to create an Asset Report is to call the /asset_report/create endpoint.

Create Asset Report request


const daysRequested = 60;
const options = {
  client_report_id: '123',
  webhook: 'https://www.example.com',
  user: {
    client_user_id: '789',
    first_name: 'Jane',
    middle_name: 'Leah',
    last_name: 'Doe',
    ssn: '123-45-6789',
    phone_number: '(555) 123-4567',
    email: 'jane.doe@example.com',
  },
};

// ACCESS_TOKENS is an array of Item access tokens.
// Note that the assets product must be enabled for all Items.
// All fields on the options object are optional.
client.createAssetReport(ACCESS_TOKENS, daysRequested, options,
  (error, createResponse) => {
  if (error != null) {
    // Handle error.
  }

  const assetReportId = createResponse.asset_report_id;
  const assetReportToken = createResponse.asset_report_token;
});

curl -X POST https://sandbox.plaid.com/asset_report/create \
-H 'Content-Type: application/json' \
-d '{
 "client_id": String,
 "secret": String,
 "access_tokens": [String],
 "days_requested": Integer,
 "options": {
    // all optional
    "client_report_id": String,
    "webhook": String,
    "user": {
      // all optional
      "client_user_id": String,
      "first_name": String,
      "middle_name": String,
      "last_name": String,
      "ssn": String,
      "phone_number": String,
      "email": String
    }
 }
}'

days_requested = 60
options = {
  client_report_id: '123',
  webhook: 'https://www.example.com',
  user: {
    client_user_id: '789',
    first_name: 'Jane',
    middle_name: 'Leah',
    last_name: 'Doe',
    ssn: '123-45-6789',
    phone_number: '(555) 123-4567',
    email: 'jane.doe@example.com',
  },
};

# access_tokens is a list of Item access tokens.
# Note that the assets product must be enabled for all Items.
# All fields on the options Hash are optional.
response = @client.asset_report.create(access_tokens, days_requested, options)
asset_report_id = response.asset_report_id
asset_report_token = response.asset_report_token

// ACCESS_TOKENS is an array of Item access tokens.
// Note that the assets product must be enabled for all Items.
// All fields on the options object are optional.
AssetReportCreateRequest request =
  new AssetReportCreateRequest(ACCESS_TOKENS, 60)
    .withClientReportId("123")
    .withClientUserId("789")
    .withFirstName("Jane")
    .withMiddleName("Leah")
    .withLastName("Doe")
    .withSsn("123-45-6789")
    .withPhoneNumber("(555) 123-4567")
    .withEmail("jane.doe@example.com")
    .withWebhook("https://www.example.com");

Response<AssetReportCreateResponse> response =
  client
  .service()
  .assetReportCreate(request)
  .execute();
String assetReportId = response.body().getAssetReportId();
String assetReportToken = response.body().getAssetReportToken();

days_requested = 60
client_report_id = '123'
webhook = 'https://www.example.com'
user = {
  'client_user_id': '789',
  'first_name': 'Jane',
  'middle_name': 'Leah',
  'last_name': 'Doe',
  'ssn': '123-45-6789',
  'phone_number': '(555) 123-4567',
  'email': 'jane.doe@example.com',
}

# access_tokens is a list of Item access tokens.
# Note that the assets product must be enabled for all Items.
# All fields on the options object are optional.
response = client.AssetReport.create(
  access_tokens,
  days_requested,
  client_report_id=client_report_id,
  webhook=webhook,
  user=user,
)
asset_report_id = response['asset_report_id']
asset_report_token = response['asset_report_token']

When creating an Asset Report, the only required fields are your client_id, secret, an array of access_tokens (one for each Item to be included in the Report), and the number of days_requested which determines the duration of transaction history to be included. All other fields are optional.

Create Asset Report request parameters
Field Type Description
client_id string Your client_id
secret string Your secret
access_tokens list of strings An array of access tokens, one token for each Item to be included in the Asset Report.
days_requested integer Days of transaction history requested to be included in the Asset Report. Plaid will return as much data as possible within the implied date range, up to a maximum of 730 days (2 years) of history.
options Options object If provided, must be non-null. See Options object for fields.
Options object

The options object allows you to provide additional fields when creating an Asset Report, all of which are optional. Some fields nested in the user object are required for Fannie Mae’s Day 1 Certainty™ program.

Field Type Description
client_report_id string Client-generated identifier, which can be used by lenders to track loan applications.
webhook string URL to which Plaid will send Assets webhooks, for example when the requested Asset Report is ready.
user User object Data submitted by you about the user whose Asset Report is being compiled. See User object for fields.
User object

The user object allows you to provide additional information about the user to be appended to the Asset Report. All fields in the user object are optional if you simply want to retrieve an Asset Report, however the first_name, last_name, and ssn fields are required if you would like the Report to eligible for Fannie Mae’s Day 1 Certainty™ program.

Field Type D1C™ Description
client_user_id string optional An identifier you determine and submit for the user
first_name string required The user’s first name
middle_name string optional The user’s middle name
last_name string required The user’s last name
ssn string required The user’s social security number Format: "\d\d\d-\d\d-\d\d\d\d"
phone_number string optional The user’s phone number Format: “+{country_code}{area code and subscriber number}”, e.g. “+14155555555” (known as E.164 format)
email string optional The user’s email address
Create Asset Report response

http code 200
{
   "asset_report_token": "assets-sandbox-6f12f5bb-22dd-4855-b918-f47ec439198a",
   "asset_report_id": "1f414183-220c-44f5-b0c8-bc0e6d4053bb",
   "request_id": "Iam3b"
}

http code 200
{
   "asset_report_token": "assets-sandbox-6f12f5bb-22dd-4855-b918-f47ec439198a",
   "asset_report_id": "1f414183-220c-44f5-b0c8-bc0e6d4053bb",
   "request_id": "Iam3b"
}

http code 200
{
   "asset_report_token": "assets-sandbox-6f12f5bb-22dd-4855-b918-f47ec439198a",
   "asset_report_id": "1f414183-220c-44f5-b0c8-bc0e6d4053bb",
   "request_id": "Iam3b"
}

http code 200
{
   "asset_report_token": "assets-sandbox-6f12f5bb-22dd-4855-b918-f47ec439198a",
   "asset_report_id": "1f414183-220c-44f5-b0c8-bc0e6d4053bb",
   "request_id": "Iam3b"
}

http code 200
{
   "asset_report_token": "assets-sandbox-6f12f5bb-22dd-4855-b918-f47ec439198a",
   "asset_report_id": "1f414183-220c-44f5-b0c8-bc0e6d4053bb",
   "request_id": "Iam3b"
}

That’s it! Save the asset_report_token and asset_report_id in a secure datastore, as they’re used to access the Asset Report data and identify webhooks, respectively.

Note: In order for an access_token to be used to obtain an Asset Report, it must have been generated with assets included in Link’s product array (see the Link parameter reference above); otherwise, you will encounter a PRODUCT_NOT_ENABLED error when creating an Asset Report with that access_token, as shown here:


http code 400
{
    "display_message": null,
    "error_code": "PRODUCT_NOT_ENABLED",
    "error_message": "the 'assets' product is not enabled for the following access tokens: access-sandbox-fb88b20c-7b74-4197-8d01-0ab122dad0bc. please ensure that 'assets' is included in the 'product' array when initializing Link and create the Item(s) again.",
    "error_type": "ASSET_REPORT_ERROR",
    "request_id": "m8MDnv9okwxFNBV"
}

Refreshing an Asset Report

An Asset Report is an immutable snapshot of a user's assets. In order to "refresh" an Asset Report you created previously, you can use the /asset_report/refresh endpoint to create a new Asset Report based on the old one, but with the most recent data available from the financial institution(s).

The new Asset Report will contain the same Items as the original Report, excluding any Accounts previously excluded from it using the /asset_report/filter endpoint.

By default, the new Asset Report will contain the same values you submitted within the options object of your original /asset_report/create request, but these values can be overriden. For example, if you provided a webhook URL in your initial /asset_report/create request, the same webhook URL will be associated with the new Report unless you override it. To override any of the options fields, simply supply new values for them in your request to /asset_report/refresh as shown below. Submit an empty string ("") for any previously-populated fields you would like set as empty.

The new Asset Report will also contain by default the same number of days of transaction history as the original Report, but you can request a different number of days by including the days_requested field in your request to /asset_report/refresh, as shown below:


const overrides = {
  daysRequested: 60;
  options: {
    client_report_id: '123',
    webhook: 'https://www.example.com',
    user: {
      client_user_id: '789',
      first_name: 'Jane',
      middle_name: 'Leah',
      last_name: 'Doe',
      ssn: '123-45-6789',
      phone_number: '(555) 123-4567',
      email: 'jane.doe@example.com',
    },
  },
};

client.refreshAssetReport(assetReportToken, overrides,
  (error, refreshResponse) => {
  if (error != null) {
    // Handle error.
  }

  const assetReportId = refreshResponse.asset_report_id;
  const assetReportToken = refreshResponse.asset_report_token;
});

curl -X POST https://sandbox.plaid.com/asset_report/refresh \
-H 'Content-Type: application/json' \
-d '{
  "client_id": String,
  "secret": String,
  "asset_report_token": String,
  "days_requested": Integer, // optional
  "options": {
      // all optional
      "client_report_id": String,
      "webhook": String,
      "user": {
        // all optional
        "client_user_id": String,
        "first_name": String,
        "middle_name": String,
        "last_name": String,
        "ssn": String,
        "phone_number": String,
        "email": String
      }
  }
}'

overrides = {
  days_requested: 60,
  options: {
    client_report_id: '123',
    webhook: 'https://www.example.com',
    user: {
      client_user_id: '789',
      first_name: 'Jane',
      middle_name: 'Leah',
      last_name: 'Doe',
      ssn: '123-45-6789',
      phone_number: '(555) 123-4567',
      email: 'jane.doe@example.com',
    },
  },
};

response = @client.asset_report.refresh(asset_report_token, overrides)
asset_report_id = response.asset_report_id
asset_report_token = response.asset_report_token

AssetReportRefreshRequest request =
new AssetReportRefreshRequest(assetReportToken)
  .withDaysRequested(60)
  .withClientReportId("123")
  .withClientUserId("789")
  .withFirstName("Jane")
  .withMiddleName("Leah")
  .withLastName("Doe")
  .withSsn("123-45-6789")
  .withPhoneNumber("(555) 123-4567")
  .withEmail("jane.doe@example.com")
  .withWebhook("https://www.example.com");

Response<AssetReportRefreshResponse> response =
client
.service()
.assetReportRefresh(request)
.execute();
String assetReportId = response.body().getAssetReportId();
String assetReportToken = response.body().getAssetReportToken();

overrides = {
  'days_requested': 60,
  'options': {
    'client_report_id': '123',
    'webhook': 'https://www.example.com',
    'user': {
      'client_user_id': '789',
      'first_name': 'Jane',
      'middle_name': 'Leah',
      'last_name': 'Doe',
      'ssn': '123-45-6789',
      'phone_number': '(555) 123-4567',
      'email': 'jane.doe@example.com',
    },
  },
}

response = client.AssetReport.refresh(asset_report_token, overrides)
asset_report_id = response['asset_report_id']
asset_report_token = response['asset_report_token']
Refresh Asset Report response

http code 200
{
  "asset_report_id": "c33ebe8b-6a63-4d74-a83d-d39791231ac0",
  "asset_report_token": "assets-sandbox-8218d5f8-6d6d-403d-92f5-13a9afaa4398",
  "request_id": "NBZaq"
}

http code 200
{
  "asset_report_id": "c33ebe8b-6a63-4d74-a83d-d39791231ac0",
  "asset_report_token": "assets-sandbox-8218d5f8-6d6d-403d-92f5-13a9afaa4398",
  "request_id": "NBZaq"
}

http code 200
{
  "asset_report_id": "c33ebe8b-6a63-4d74-a83d-d39791231ac0",
  "asset_report_token": "assets-sandbox-8218d5f8-6d6d-403d-92f5-13a9afaa4398",
  "request_id": "NBZaq"
}

http code 200
{
  "asset_report_id": "c33ebe8b-6a63-4d74-a83d-d39791231ac0",
  "asset_report_token": "assets-sandbox-8218d5f8-6d6d-403d-92f5-13a9afaa4398",
  "request_id": "NBZaq"
}

http code 200
{
  "asset_report_id": "c33ebe8b-6a63-4d74-a83d-d39791231ac0",
  "asset_report_token": "assets-sandbox-8218d5f8-6d6d-403d-92f5-13a9afaa4398",
  "request_id": "NBZaq"
}
Specifying which Accounts appear in the Asset Report

By default, an Asset Report will contain all of the Accounts on a given Item. To narrow an Asset Report to only a subset of Accounts, you'll use the /asset_report/filter endpoint.

To exclude certain Accounts from an Asset Report, you'll first use the /asset_report/create endpoint as described above, which creates a "full" Asset Report containing data for all available Accounts. Then, after that initial Asset Report has finished being generated, you'll send its asset_report_token along with a list of account_ids to exclude to the /asset_report/filter endpoint, to create a new Asset Report which contains only a subset of the original Asset Report's data.

Because Asset Reports are immutable, calling /asset_report/filter does not alter the original Asset Report in any way; rather, /asset_report/filter creates a new Asset Report, with a new asset_report_token, asset_report_id, and date_generated, containing a subset of the data from the original Asset Report. Asset Reports created via /asset_report/filter do not contain new Asset data, and are not billed.

"Filtering" an Asset Report is therefore similar to creating an Asset Report from scratch. The /asset_report/filter request returns immediately, while Report generation completes asynchronously. Plaid will send you a webhook once generation of the filtered Asset Report has completed.

Once created, a filtered Asset Report behaves like any other. You can retrieve it, create and share Audit Copies of it, and remove it, all as described below.

You can also refresh a filtered Asset Report. The account_ids_to_exclude that you provided in your request to /asset_report/filter will be excluded from the refreshed report as well.

There are many ways you can determine which Accounts to include in an Asset Report. For example, you might have the end user choose which Accounts are relevant in Link using the Select Account view, which you can enable in the dashboard. Or, you might always exclude certain Account types or subtypes, which you can identify without retrieving the entire Asset Report by using the /accounts/get endpoint (see above).

Filter Asset Report request

const accountIdsToExclude = ['JJGWd5wKDgHbw6yyzL3MsqBAvPyDlqtdyk419'];
client.filterAssetReport(asset_report_token, accountIdsToExclude,
  (error, filterResponse) => {
  if (error != null) {
    // Handle error.
  }

  const assetReportId = filterResponse.asset_report_id;
  const assetReportToken = filterResponse.asset_report_token;
});

curl -X POST https://sandbox.plaid.com/asset_report/filter \
 -H 'Content-Type: application/json' \
 -d '{
   "client_id": String,
   "secret": String,
   "asset_report_token": String,
   "account_ids_to_exclude": [String]
 }'

account_ids_to_exclude = ["JJGWd5wKDgHbw6yyzL3MsqBAvPyDlqtdyk419"]
response = @client.asset_report.filter(asset_report_token, account_ids_to_exclude)
asset_report_id = response.asset_report_id
asset_report_token = response.asset_report_token

String[] accountIdsToExclude = {"JJGWd5wKDgHbw6yyzL3MsqBAvPyDlqtdyk419"};
AssetReportFilterRequest request =
  new AssetReportFilterRequest(assetReportToken, accountIdsToExclude)

Response<AssetReportFilterResponse> response =
  client
  .service()
  .assetReportFilter(request)
  .execute();
String assetReportId = response.body().getAssetReportId();
String assetReportToken = response.body().getAssetReportToken();

account_ids_to_exclude = ['JJGWd5wKDgHbw6yyzL3MsqBAvPyDlqtdyk419']
response = client.AssetReport.filter(
  asset_report_token,
  account_ids_to_exclude,
)
asset_report_id = response['asset_report_id']
asset_report_token = response['asset_report_token']
Filter Asset Report response

http code 200
{
   "asset_report_token": "assets-sandbox-bc410c6a-4653-4c75-985c-e757c3497c5c",
   "asset_report_id": "fdc09207-0cef-4d88-b5eb-0d970758ebd9",
   "request_id": "qEg07"
}

http code 200
{
   "asset_report_token": "assets-sandbox-bc410c6a-4653-4c75-985c-e757c3497c5c",
   "asset_report_id": "fdc09207-0cef-4d88-b5eb-0d970758ebd9",
   "request_id": "qEg07"
}

http code 200
{
   "asset_report_token": "assets-sandbox-bc410c6a-4653-4c75-985c-e757c3497c5c",
   "asset_report_id": "fdc09207-0cef-4d88-b5eb-0d970758ebd9",
   "request_id": "qEg07"
}

http code 200
{
   "asset_report_token": "assets-sandbox-bc410c6a-4653-4c75-985c-e757c3497c5c",
   "asset_report_id": "fdc09207-0cef-4d88-b5eb-0d970758ebd9",
   "request_id": "qEg07"
}

http code 200
{
   "asset_report_token": "assets-sandbox-bc410c6a-4653-4c75-985c-e757c3497c5c",
   "asset_report_id": "fdc09207-0cef-4d88-b5eb-0d970758ebd9",
   "request_id": "qEg07"
}
3. Retrieve an Asset Report

You can retrieve your Asset Report in multiple formats, determined by the endpoint you call.


POST /asset_report/get
POST /asset_report/pdf/get
Retrieve JSON Report request

To retrieve the Asset Report in JSON format, simply call the /asset_report/get endpoint.


// ASSET_REPORT_TOKEN is the token from the createAssetReport response.
client.getAssetReport(ASSET_REPORT_TOKEN, (error, getResponse) => {
  if (error != null) {
    if (error.status_code === 400 &&
        error.error_code === 'PRODUCT_NOT_READY') {
      // Asset report is not ready yet. Try again later.
    } else {
      // Handle error.
    }
  }

  const report = getResponse.report;
});

curl -X POST https://sandbox.plaid.com/asset_report/get \
 -H 'Content-Type: application/json' \
 -d '{
   "client_id": String,
   "secret": String,
   "asset_report_token": String
 }'

# asset_report_token is the token from the AssetReport.create response.
response = @client.asset_report.get(asset_report_token)
report = response.report

// assetReportToken is the token from the AssetReportCreateRequest response.
AssetReportGetRequest assetReportGet =
  new AssetReportGetRequest(assetReportToken);
Response<AssetReportGetResponse> response =
  client
  .service()
  .assetReportGet(assetReportGet)
  .execute();
AssetReport report = response.body().getReport();

# asset_report_token is the token from the AssetReport.create response.
try:
  response = client.AssetReport.get(asset_report_token)
  report = response['report']
except PlaidError as e:
  if e.code == 'PRODUCT_NOT_READY':
    # Asset report is not ready yet. Try again later.
  else:
    # Handle error.
Retrieve JSON Report response

http code 200
{
  "report": {
    "asset_report_id": "c5b638f9-02b8-45c6-9093-552195149b0c",
    "client_report_id": "123456",
    "date_generated": "2018-04-12T03:32:11Z",
    "days_requested": 730,
    "items": [
      {
        "accounts": [
          {
            "account_id": "jW4r4QvdeXcAZNj8J3Dni68DqxQ3laHZwGyBD",
            "balances": {
              "available": 100,
              "current": 110
            },
            "days_available": 730,
            "historical_balances": [
              {
                "current": 110,
                "date": "2018-04-12",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              },
              {
                "current": 110,
                "date": "2018-04-11",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              },
              {
                "current": 110,
                "date": "2018-04-10",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              },
              ...
            ],
            "mask": "0000",
            "name": "Plaid Checking",
            "official_name": "Plaid Gold Standard 0% Interest Checking",
            "owners": [
              {
                "addresses": [
                  {
                    "data": {
                      "city": "Malakoff",
                      "state": "NY",
                      "street": "2992 Cameron Road",
                      "zip": "14236"
                    },
                    "primary": true
                  },
                  {
                    "data": {
                      "city": "San Matias",
                      "state": "CA",
                      "street": "2493 Leisure Lane",
                      "zip": "93405-2255"
                    },
                    "primary": false
                  }
                ],
                "emails": [
                  {
                    "data": "accountholder0@example.com",
                    "primary": true,
                    "type": "primary"
                  },
                  {
                    "data": "accountholder1@example.com",
                    "primary": false,
                    "type": "secondary"
                  },
                  {
                    "data": "extraordinarily.long.email.username.123456@reallylonghostname.com",
                    "primary": false,
                    "type": "other"
                  }
                ],
                "names": [
                  "Alberta Bobbeth Charleson"
                ],
                "phone_numbers": [
                  {
                    "data": "1112223333",
                    "primary": false,
                    "type": "home"
                  },
                  {
                    "data": "1112224444",
                    "primary": false,
                    "type": "work"
                  },
                  {
                    "data": "1112225555",
                    "primary": false,
                    "type": "mobile1"
                  }
                ]
              }
            ],
            "subtype": "checking",
            "transactions": [
              ...
              {
                "account_id": "jW4r4QvdeXcAZNj8J3Dni68DqxQ3laHZwGyBD",
                "amount": -500,
                "date": "2018-03-25",
                "original_description": "United Airlines  REFUND ",
                "pending": false,
                "transaction_id": "wPkQknvpz9HV8bPK465rC6GnyrnlrXCMr9vgm",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              },
              {
                "account_id": "jW4r4QvdeXcAZNj8J3Dni68DqxQ3laHZwGyBD",
                "amount": 5.4,
                "date": "2018-03-27",
                "original_description": "Uber 063015 SFPOOL",
                "pending": false,
                "transaction_id": "GM4K4LJqGBu5g8yqjkQJuVnry6rz6zh8Qwkv9",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              },
              {
                "account_id": "jW4r4QvdeXcAZNj8J3Dni68DqxQ3laHZwGyBD",
                "amount": 6.33,
                "date": "2018-04-09",
                "original_description": "Uber 072515 SFPOOL",
                "pending": false,
                "transaction_id": "DekykZJWrjf5g7kjRaLvceLZb4avg5CVBDGz5x",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              }
            ],
            "type": "depository"
          },
          {
            "account_id": "V3EkERBQXGF5z6Jb9NDkupNeoy1b81cjpWVDe",
            "balances": {
              "available": 200,
              "current": 210
            },
            "days_available": 730,
            "historical_balances": [
              {
                "current": 210,
                "date": "2018-04-12",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              },
              {
                "current": 210,
                "date": "2018-04-11",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              },
              {
                "current": 210,
                "date": "2018-04-10",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              },
              ...
            ],
            "mask": "1111",
            "name": "Plaid Saving",
            "official_name": "Plaid Silver Standard 0.1% Interest Saving",
            "owners": [
              {
                "addresses": [
                  {
                    "data": {
                      "city": "Malakoff",
                      "state": "NY",
                      "street": "2992 Cameron Road",
                      "zip": "14236"
                    },
                    "primary": true
                  },
                  {
                    "data": {
                      "city": "San Matias",
                      "state": "CA",
                      "street": "2493 Leisure Lane",
                      "zip": "93405-2255"
                    },
                    "primary": false
                  }
                ],
                "emails": [
                  {
                    "data": "accountholder0@example.com",
                    "primary": true,
                    "type": "primary"
                  },
                  {
                    "data": "accountholder1@example.com",
                    "primary": false,
                    "type": "secondary"
                  },
                  {
                    "data": "extraordinarily.long.email.username.123456@reallylonghostname.com",
                    "primary": false,
                    "type": "other"
                  }
                ],
                "names": [
                  "Alberta Bobbeth Charleson"
                ],
                "phone_numbers": [
                  {
                    "data": "1112223333",
                    "primary": false,
                    "type": "home"
                  },
                  {
                    "data": "1112224444",
                    "primary": false,
                    "type": "work"
                  },
                  {
                    "data": "1112225555",
                    "primary": false,
                    "type": "mobile1"
                  }
                ]
              }
            ],
            "subtype": "savings",
            "transactions": [
              ...
              {
                "account_id": "V3EkERBQXGF5z6Jb9NDkupNeoy1b81cjpWVDe",
                "amount": 25,
                "date": "2018-02-25",
                "original_description": "CREDIT CARD 3333 PAYMENT //",
                "pending": false,
                "transaction_id": "LkexeEJ3Ryf5Vw3evRMMIXlLjkRkawIdzm6Ak",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              },
              {
                "account_id": "V3EkERBQXGF5z6Jb9NDkupNeoy1b81cjpWVDe",
                "amount": -4.22,
                "date": "2018-03-22",
                "original_description": "INTRST PYMNT",
                "pending": false,
                "transaction_id": "y7EJEmwgazsjJDVdMZ3QSQBKpaKnQzSjElP71M",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              },
              {
                "account_id": "V3EkERBQXGF5z6Jb9NDkupNeoy1b81cjpWVDe",
                "amount": 25,
                "date": "2018-03-27",
                "original_description": "CREDIT CARD 3333 PAYMENT //",
                "pending": false,
                "transaction_id": "dLz7z41KlaSWLbmJqpxXiaqPgJPbn5IgMwymJ",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              }
            ],
            "type": "depository"
          },
          {
            "account_id": "4RWyWq143jIEm7BaqJNKCQyG9Ndnv5iJaENyV",
            "balances": {
              "available": null,
              "current": 5000
            },
            "days_available": 730,
            "historical_balances": [
              {
                "current": 5000,
                "date": "2018-04-12",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              },
              {
                "current": 1000,
                "date": "2018-04-11",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              },
              {
                "current": 1000,
                "date": "2018-04-10",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              },
              ...
            ],
            "mask": "2222",
            "name": "Plaid CD",
            "official_name": "Plaid Bronze Standard 0.2% Interest CD",
            "owners": [
              {
                "addresses": [
                  {
                    "data": {
                      "city": "Malakoff",
                      "state": "NY",
                      "street": "2992 Cameron Road",
                      "zip": "14236"
                    },
                    "primary": true
                  },
                  {
                    "data": {
                      "city": "San Matias",
                      "state": "CA",
                      "street": "2493 Leisure Lane",
                      "zip": "93405-2255"
                    },
                    "primary": false
                  }
                ],
                "emails": [
                  {
                    "data": "accountholder0@example.com",
                    "primary": true,
                    "type": "primary"
                  },
                  {
                    "data": "accountholder1@example.com",
                    "primary": false,
                    "type": "secondary"
                  },
                  {
                    "data": "extraordinarily.long.email.username.123456@reallylonghostname.com",
                    "primary": false,
                    "type": "other"
                  }
                ],
                "names": [
                  "Alberta Bobbeth Charleson"
                ],
                "phone_numbers": [
                  {
                    "data": "1112223333",
                    "primary": false,
                    "type": "home"
                  },
                  {
                    "data": "1112224444",
                    "primary": false,
                    "type": "work"
                  },
                  {
                    "data": "1112225555",
                    "primary": false,
                    "type": "mobile1"
                  }
                ]
              }
            ],
            "subtype": "cd",
            "transactions": [
              ...
              {
                "account_id": "4RWyWq143jIEm7BaqJNKCQyG9Ndnv5iJaENyV",
                "amount": 1000,
                "date": "2018-01-25",
                "original_description": "CD DEPOSIT .INITIAL.",
                "pending": false,
                "transaction_id": "M8QdQWJx1GS51ZymxjNNILQ7GwjwG1I3qr3RwX",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              },
              {
                "account_id": "4RWyWq143jIEm7BaqJNKCQyG9Ndnv5iJaENyV",
                "amount": 1000,
                "date": "2018-02-24",
                "original_description": "CD DEPOSIT .INITIAL.",
                "pending": false,
                "transaction_id": "q3Z4ZgvempFnljLVzqxxhPQ3we7eW9sdJy5jP",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              },
              {
                "account_id": "4RWyWq143jIEm7BaqJNKCQyG9Ndnv5iJaENyV",
                "amount": 1000,
                "date": "2018-03-26",
                "original_description": "CD DEPOSIT .INITIAL.",
                "pending": false,
                "transaction_id": "aZqNqxQAEyHvboB8jazrsbPWNwW6WxU8zRj5kw",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              }
            ],
            "type": "depository"
          }
        ],
        "date_last_updated": "2018-04-12T03:32:10Z",
        "institution_id": "ins_109511",
        "institution_name": "Tartan Bank",
        "item_id": "zeWoWyv84xfkGg1w4ox5iQy5k6j75xu8QXMEm"
      }
    ],
    "user": {
      "client_user_id": "123456789",
      "email": "accountholder0@example.com",
      "first_name": "Alberta",
      "last_name": "Charleson",
      "middle_name": "Bobbeth",
      "phone_number": "111-222-3333",
      "ssn": "123-45-6789"
    }
  },
  "request_id": "pdwYD",
  "warnings": []
}

http code 200
{
  "report": {
    "asset_report_id": "c5b638f9-02b8-45c6-9093-552195149b0c",
    "client_report_id": "123456",
    "date_generated": "2018-04-12T03:32:11Z",
    "days_requested": 730,
    "items": [
      {
        "accounts": [
          {
            "account_id": "jW4r4QvdeXcAZNj8J3Dni68DqxQ3laHZwGyBD",
            "balances": {
              "available": 100,
              "current": 110
            },
            "days_available": 730,
            "historical_balances": [
              {
                "current": 110,
                "date": "2018-04-12",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              },
              {
                "current": 110,
                "date": "2018-04-11",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              },
              {
                "current": 110,
                "date": "2018-04-10",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              },
              ...
            ],
            "mask": "0000",
            "name": "Plaid Checking",
            "official_name": "Plaid Gold Standard 0% Interest Checking",
            "owners": [
              {
                "addresses": [
                  {
                    "data": {
                      "city": "Malakoff",
                      "state": "NY",
                      "street": "2992 Cameron Road",
                      "zip": "14236"
                    },
                    "primary": true
                  },
                  {
                    "data": {
                      "city": "San Matias",
                      "state": "CA",
                      "street": "2493 Leisure Lane",
                      "zip": "93405-2255"
                    },
                    "primary": false
                  }
                ],
                "emails": [
                  {
                    "data": "accountholder0@example.com",
                    "primary": true,
                    "type": "primary"
                  },
                  {
                    "data": "accountholder1@example.com",
                    "primary": false,
                    "type": "secondary"
                  },
                  {
                    "data": "extraordinarily.long.email.username.123456@reallylonghostname.com",
                    "primary": false,
                    "type": "other"
                  }
                ],
                "names": [
                  "Alberta Bobbeth Charleson"
                ],
                "phone_numbers": [
                  {
                    "data": "1112223333",
                    "primary": false,
                    "type": "home"
                  },
                  {
                    "data": "1112224444",
                    "primary": false,
                    "type": "work"
                  },
                  {
                    "data": "1112225555",
                    "primary": false,
                    "type": "mobile1"
                  }
                ]
              }
            ],
            "subtype": "checking",
            "transactions": [
              ...
              {
                "account_id": "jW4r4QvdeXcAZNj8J3Dni68DqxQ3laHZwGyBD",
                "amount": -500,
                "date": "2018-03-25",
                "original_description": "United Airlines  REFUND ",
                "pending": false,
                "transaction_id": "wPkQknvpz9HV8bPK465rC6GnyrnlrXCMr9vgm",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              },
              {
                "account_id": "jW4r4QvdeXcAZNj8J3Dni68DqxQ3laHZwGyBD",
                "amount": 5.4,
                "date": "2018-03-27",
                "original_description": "Uber 063015 SFPOOL",
                "pending": false,
                "transaction_id": "GM4K4LJqGBu5g8yqjkQJuVnry6rz6zh8Qwkv9",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              },
              {
                "account_id": "jW4r4QvdeXcAZNj8J3Dni68DqxQ3laHZwGyBD",
                "amount": 6.33,
                "date": "2018-04-09",
                "original_description": "Uber 072515 SFPOOL",
                "pending": false,
                "transaction_id": "DekykZJWrjf5g7kjRaLvceLZb4avg5CVBDGz5x",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              }
            ],
            "type": "depository"
          },
          {
            "account_id": "V3EkERBQXGF5z6Jb9NDkupNeoy1b81cjpWVDe",
            "balances": {
              "available": 200,
              "current": 210
            },
            "days_available": 730,
            "historical_balances": [
              {
                "current": 210,
                "date": "2018-04-12",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              },
              {
                "current": 210,
                "date": "2018-04-11",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              },
              {
                "current": 210,
                "date": "2018-04-10",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              },
              ...
            ],
            "mask": "1111",
            "name": "Plaid Saving",
            "official_name": "Plaid Silver Standard 0.1% Interest Saving",
            "owners": [
              {
                "addresses": [
                  {
                    "data": {
                      "city": "Malakoff",
                      "state": "NY",
                      "street": "2992 Cameron Road",
                      "zip": "14236"
                    },
                    "primary": true
                  },
                  {
                    "data": {
                      "city": "San Matias",
                      "state": "CA",
                      "street": "2493 Leisure Lane",
                      "zip": "93405-2255"
                    },
                    "primary": false
                  }
                ],
                "emails": [
                  {
                    "data": "accountholder0@example.com",
                    "primary": true,
                    "type": "primary"
                  },
                  {
                    "data": "accountholder1@example.com",
                    "primary": false,
                    "type": "secondary"
                  },
                  {
                    "data": "extraordinarily.long.email.username.123456@reallylonghostname.com",
                    "primary": false,
                    "type": "other"
                  }
                ],
                "names": [
                  "Alberta Bobbeth Charleson"
                ],
                "phone_numbers": [
                  {
                    "data": "1112223333",
                    "primary": false,
                    "type": "home"
                  },
                  {
                    "data": "1112224444",
                    "primary": false,
                    "type": "work"
                  },
                  {
                    "data": "1112225555",
                    "primary": false,
                    "type": "mobile1"
                  }
                ]
              }
            ],
            "subtype": "savings",
            "transactions": [
              ...
              {
                "account_id": "V3EkERBQXGF5z6Jb9NDkupNeoy1b81cjpWVDe",
                "amount": 25,
                "date": "2018-02-25",
                "original_description": "CREDIT CARD 3333 PAYMENT //",
                "pending": false,
                "transaction_id": "LkexeEJ3Ryf5Vw3evRMMIXlLjkRkawIdzm6Ak",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              },
              {
                "account_id": "V3EkERBQXGF5z6Jb9NDkupNeoy1b81cjpWVDe",
                "amount": -4.22,
                "date": "2018-03-22",
                "original_description": "INTRST PYMNT",
                "pending": false,
                "transaction_id": "y7EJEmwgazsjJDVdMZ3QSQBKpaKnQzSjElP71M",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              },
              {
                "account_id": "V3EkERBQXGF5z6Jb9NDkupNeoy1b81cjpWVDe",
                "amount": 25,
                "date": "2018-03-27",
                "original_description": "CREDIT CARD 3333 PAYMENT //",
                "pending": false,
                "transaction_id": "dLz7z41KlaSWLbmJqpxXiaqPgJPbn5IgMwymJ",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              }
            ],
            "type": "depository"
          },
          {
            "account_id": "4RWyWq143jIEm7BaqJNKCQyG9Ndnv5iJaENyV",
            "balances": {
              "available": null,
              "current": 5000
            },
            "days_available": 730,
            "historical_balances": [
              {
                "current": 5000,
                "date": "2018-04-12",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              },
              {
                "current": 1000,
                "date": "2018-04-11",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              },
              {
                "current": 1000,
                "date": "2018-04-10",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              },
              ...
            ],
            "mask": "2222",
            "name": "Plaid CD",
            "official_name": "Plaid Bronze Standard 0.2% Interest CD",
            "owners": [
              {
                "addresses": [
                  {
                    "data": {
                      "city": "Malakoff",
                      "state": "NY",
                      "street": "2992 Cameron Road",
                      "zip": "14236"
                    },
                    "primary": true
                  },
                  {
                    "data": {
                      "city": "San Matias",
                      "state": "CA",
                      "street": "2493 Leisure Lane",
                      "zip": "93405-2255"
                    },
                    "primary": false
                  }
                ],
                "emails": [
                  {
                    "data": "accountholder0@example.com",
                    "primary": true,
                    "type": "primary"
                  },
                  {
                    "data": "accountholder1@example.com",
                    "primary": false,
                    "type": "secondary"
                  },
                  {
                    "data": "extraordinarily.long.email.username.123456@reallylonghostname.com",
                    "primary": false,
                    "type": "other"
                  }
                ],
                "names": [
                  "Alberta Bobbeth Charleson"
                ],
                "phone_numbers": [
                  {
                    "data": "1112223333",
                    "primary": false,
                    "type": "home"
                  },
                  {
                    "data": "1112224444",
                    "primary": false,
                    "type": "work"
                  },
                  {
                    "data": "1112225555",
                    "primary": false,
                    "type": "mobile1"
                  }
                ]
              }
            ],
            "subtype": "cd",
            "transactions": [
              ...
              {
                "account_id": "4RWyWq143jIEm7BaqJNKCQyG9Ndnv5iJaENyV",
                "amount": 1000,
                "date": "2018-01-25",
                "original_description": "CD DEPOSIT .INITIAL.",
                "pending": false,
                "transaction_id": "M8QdQWJx1GS51ZymxjNNILQ7GwjwG1I3qr3RwX",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              },
              {
                "account_id": "4RWyWq143jIEm7BaqJNKCQyG9Ndnv5iJaENyV",
                "amount": 1000,
                "date": "2018-02-24",
                "original_description": "CD DEPOSIT .INITIAL.",
                "pending": false,
                "transaction_id": "q3Z4ZgvempFnljLVzqxxhPQ3we7eW9sdJy5jP",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              },
              {
                "account_id": "4RWyWq143jIEm7BaqJNKCQyG9Ndnv5iJaENyV",
                "amount": 1000,
                "date": "2018-03-26",
                "original_description": "CD DEPOSIT .INITIAL.",
                "pending": false,
                "transaction_id": "aZqNqxQAEyHvboB8jazrsbPWNwW6WxU8zRj5kw",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              }
            ],
            "type": "depository"
          }
        ],
        "date_last_updated": "2018-04-12T03:32:10Z",
        "institution_id": "ins_109511",
        "institution_name": "Tartan Bank",
        "item_id": "zeWoWyv84xfkGg1w4ox5iQy5k6j75xu8QXMEm"
      }
    ],
    "user": {
      "client_user_id": "123456789",
      "email": "accountholder0@example.com",
      "first_name": "Alberta",
      "last_name": "Charleson",
      "middle_name": "Bobbeth",
      "phone_number": "111-222-3333",
      "ssn": "123-45-6789"
    }
  },
  "request_id": "pdwYD",
  "warnings": []
}

http code 200
{
  "report": {
    "asset_report_id": "c5b638f9-02b8-45c6-9093-552195149b0c",
    "client_report_id": "123456",
    "date_generated": "2018-04-12T03:32:11Z",
    "days_requested": 730,
    "items": [
      {
        "accounts": [
          {
            "account_id": "jW4r4QvdeXcAZNj8J3Dni68DqxQ3laHZwGyBD",
            "balances": {
              "available": 100,
              "current": 110
            },
            "days_available": 730,
            "historical_balances": [
              {
                "current": 110,
                "date": "2018-04-12",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              },
              {
                "current": 110,
                "date": "2018-04-11",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              },
              {
                "current": 110,
                "date": "2018-04-10",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              },
              ...
            ],
            "mask": "0000",
            "name": "Plaid Checking",
            "official_name": "Plaid Gold Standard 0% Interest Checking",
            "owners": [
              {
                "addresses": [
                  {
                    "data": {
                      "city": "Malakoff",
                      "state": "NY",
                      "street": "2992 Cameron Road",
                      "zip": "14236"
                    },
                    "primary": true
                  },
                  {
                    "data": {
                      "city": "San Matias",
                      "state": "CA",
                      "street": "2493 Leisure Lane",
                      "zip": "93405-2255"
                    },
                    "primary": false
                  }
                ],
                "emails": [
                  {
                    "data": "accountholder0@example.com",
                    "primary": true,
                    "type": "primary"
                  },
                  {
                    "data": "accountholder1@example.com",
                    "primary": false,
                    "type": "secondary"
                  },
                  {
                    "data": "extraordinarily.long.email.username.123456@reallylonghostname.com",
                    "primary": false,
                    "type": "other"
                  }
                ],
                "names": [
                  "Alberta Bobbeth Charleson"
                ],
                "phone_numbers": [
                  {
                    "data": "1112223333",
                    "primary": false,
                    "type": "home"
                  },
                  {
                    "data": "1112224444",
                    "primary": false,
                    "type": "work"
                  },
                  {
                    "data": "1112225555",
                    "primary": false,
                    "type": "mobile1"
                  }
                ]
              }
            ],
            "subtype": "checking",
            "transactions": [
              ...
              {
                "account_id": "jW4r4QvdeXcAZNj8J3Dni68DqxQ3laHZwGyBD",
                "amount": -500,
                "date": "2018-03-25",
                "original_description": "United Airlines  REFUND ",
                "pending": false,
                "transaction_id": "wPkQknvpz9HV8bPK465rC6GnyrnlrXCMr9vgm",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              },
              {
                "account_id": "jW4r4QvdeXcAZNj8J3Dni68DqxQ3laHZwGyBD",
                "amount": 5.4,
                "date": "2018-03-27",
                "original_description": "Uber 063015 SFPOOL",
                "pending": false,
                "transaction_id": "GM4K4LJqGBu5g8yqjkQJuVnry6rz6zh8Qwkv9",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              },
              {
                "account_id": "jW4r4QvdeXcAZNj8J3Dni68DqxQ3laHZwGyBD",
                "amount": 6.33,
                "date": "2018-04-09",
                "original_description": "Uber 072515 SFPOOL",
                "pending": false,
                "transaction_id": "DekykZJWrjf5g7kjRaLvceLZb4avg5CVBDGz5x",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              }
            ],
            "type": "depository"
          },
          {
            "account_id": "V3EkERBQXGF5z6Jb9NDkupNeoy1b81cjpWVDe",
            "balances": {
              "available": 200,
              "current": 210
            },
            "days_available": 730,
            "historical_balances": [
              {
                "current": 210,
                "date": "2018-04-12",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              },
              {
                "current": 210,
                "date": "2018-04-11",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              },
              {
                "current": 210,
                "date": "2018-04-10",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              },
              ...
            ],
            "mask": "1111",
            "name": "Plaid Saving",
            "official_name": "Plaid Silver Standard 0.1% Interest Saving",
            "owners": [
              {
                "addresses": [
                  {
                    "data": {
                      "city": "Malakoff",
                      "state": "NY",
                      "street": "2992 Cameron Road",
                      "zip": "14236"
                    },
                    "primary": true
                  },
                  {
                    "data": {
                      "city": "San Matias",
                      "state": "CA",
                      "street": "2493 Leisure Lane",
                      "zip": "93405-2255"
                    },
                    "primary": false
                  }
                ],
                "emails": [
                  {
                    "data": "accountholder0@example.com",
                    "primary": true,
                    "type": "primary"
                  },
                  {
                    "data": "accountholder1@example.com",
                    "primary": false,
                    "type": "secondary"
                  },
                  {
                    "data": "extraordinarily.long.email.username.123456@reallylonghostname.com",
                    "primary": false,
                    "type": "other"
                  }
                ],
                "names": [
                  "Alberta Bobbeth Charleson"
                ],
                "phone_numbers": [
                  {
                    "data": "1112223333",
                    "primary": false,
                    "type": "home"
                  },
                  {
                    "data": "1112224444",
                    "primary": false,
                    "type": "work"
                  },
                  {
                    "data": "1112225555",
                    "primary": false,
                    "type": "mobile1"
                  }
                ]
              }
            ],
            "subtype": "savings",
            "transactions": [
              ...
              {
                "account_id": "V3EkERBQXGF5z6Jb9NDkupNeoy1b81cjpWVDe",
                "amount": 25,
                "date": "2018-02-25",
                "original_description": "CREDIT CARD 3333 PAYMENT //",
                "pending": false,
                "transaction_id": "LkexeEJ3Ryf5Vw3evRMMIXlLjkRkawIdzm6Ak",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              },
              {
                "account_id": "V3EkERBQXGF5z6Jb9NDkupNeoy1b81cjpWVDe",
                "amount": -4.22,
                "date": "2018-03-22",
                "original_description": "INTRST PYMNT",
                "pending": false,
                "transaction_id": "y7EJEmwgazsjJDVdMZ3QSQBKpaKnQzSjElP71M",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              },
              {
                "account_id": "V3EkERBQXGF5z6Jb9NDkupNeoy1b81cjpWVDe",
                "amount": 25,
                "date": "2018-03-27",
                "original_description": "CREDIT CARD 3333 PAYMENT //",
                "pending": false,
                "transaction_id": "dLz7z41KlaSWLbmJqpxXiaqPgJPbn5IgMwymJ",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              }
            ],
            "type": "depository"
          },
          {
            "account_id": "4RWyWq143jIEm7BaqJNKCQyG9Ndnv5iJaENyV",
            "balances": {
              "available": null,
              "current": 5000
            },
            "days_available": 730,
            "historical_balances": [
              {
                "current": 5000,
                "date": "2018-04-12",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              },
              {
                "current": 1000,
                "date": "2018-04-11",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              },
              {
                "current": 1000,
                "date": "2018-04-10",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              },
              ...
            ],
            "mask": "2222",
            "name": "Plaid CD",
            "official_name": "Plaid Bronze Standard 0.2% Interest CD",
            "owners": [
              {
                "addresses": [
                  {
                    "data": {
                      "city": "Malakoff",
                      "state": "NY",
                      "street": "2992 Cameron Road",
                      "zip": "14236"
                    },
                    "primary": true
                  },
                  {
                    "data": {
                      "city": "San Matias",
                      "state": "CA",
                      "street": "2493 Leisure Lane",
                      "zip": "93405-2255"
                    },
                    "primary": false
                  }
                ],
                "emails": [
                  {
                    "data": "accountholder0@example.com",
                    "primary": true,
                    "type": "primary"
                  },
                  {
                    "data": "accountholder1@example.com",
                    "primary": false,
                    "type": "secondary"
                  },
                  {
                    "data": "extraordinarily.long.email.username.123456@reallylonghostname.com",
                    "primary": false,
                    "type": "other"
                  }
                ],
                "names": [
                  "Alberta Bobbeth Charleson"
                ],
                "phone_numbers": [
                  {
                    "data": "1112223333",
                    "primary": false,
                    "type": "home"
                  },
                  {
                    "data": "1112224444",
                    "primary": false,
                    "type": "work"
                  },
                  {
                    "data": "1112225555",
                    "primary": false,
                    "type": "mobile1"
                  }
                ]
              }
            ],
            "subtype": "cd",
            "transactions": [
              ...
              {
                "account_id": "4RWyWq143jIEm7BaqJNKCQyG9Ndnv5iJaENyV",
                "amount": 1000,
                "date": "2018-01-25",
                "original_description": "CD DEPOSIT .INITIAL.",
                "pending": false,
                "transaction_id": "M8QdQWJx1GS51ZymxjNNILQ7GwjwG1I3qr3RwX",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              },
              {
                "account_id": "4RWyWq143jIEm7BaqJNKCQyG9Ndnv5iJaENyV",
                "amount": 1000,
                "date": "2018-02-24",
                "original_description": "CD DEPOSIT .INITIAL.",
                "pending": false,
                "transaction_id": "q3Z4ZgvempFnljLVzqxxhPQ3we7eW9sdJy5jP",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              },
              {
                "account_id": "4RWyWq143jIEm7BaqJNKCQyG9Ndnv5iJaENyV",
                "amount": 1000,
                "date": "2018-03-26",
                "original_description": "CD DEPOSIT .INITIAL.",
                "pending": false,
                "transaction_id": "aZqNqxQAEyHvboB8jazrsbPWNwW6WxU8zRj5kw",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              }
            ],
            "type": "depository"
          }
        ],
        "date_last_updated": "2018-04-12T03:32:10Z",
        "institution_id": "ins_109511",
        "institution_name": "Tartan Bank",
        "item_id": "zeWoWyv84xfkGg1w4ox5iQy5k6j75xu8QXMEm"
      }
    ],
    "user": {
      "client_user_id": "123456789",
      "email": "accountholder0@example.com",
      "first_name": "Alberta",
      "last_name": "Charleson",
      "middle_name": "Bobbeth",
      "phone_number": "111-222-3333",
      "ssn": "123-45-6789"
    }
  },
  "request_id": "pdwYD",
  "warnings": []
}

http code 200
{
  "report": {
    "asset_report_id": "c5b638f9-02b8-45c6-9093-552195149b0c",
    "client_report_id": "123456",
    "date_generated": "2018-04-12T03:32:11Z",
    "days_requested": 730,
    "items": [
      {
        "accounts": [
          {
            "account_id": "jW4r4QvdeXcAZNj8J3Dni68DqxQ3laHZwGyBD",
            "balances": {
              "available": 100,
              "current": 110
            },
            "days_available": 730,
            "historical_balances": [
              {
                "current": 110,
                "date": "2018-04-12",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              },
              {
                "current": 110,
                "date": "2018-04-11",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              },
              {
                "current": 110,
                "date": "2018-04-10",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              },
              ...
            ],
            "mask": "0000",
            "name": "Plaid Checking",
            "official_name": "Plaid Gold Standard 0% Interest Checking",
            "owners": [
              {
                "addresses": [
                  {
                    "data": {
                      "city": "Malakoff",
                      "state": "NY",
                      "street": "2992 Cameron Road",
                      "zip": "14236"
                    },
                    "primary": true
                  },
                  {
                    "data": {
                      "city": "San Matias",
                      "state": "CA",
                      "street": "2493 Leisure Lane",
                      "zip": "93405-2255"
                    },
                    "primary": false
                  }
                ],
                "emails": [
                  {
                    "data": "accountholder0@example.com",
                    "primary": true,
                    "type": "primary"
                  },
                  {
                    "data": "accountholder1@example.com",
                    "primary": false,
                    "type": "secondary"
                  },
                  {
                    "data": "extraordinarily.long.email.username.123456@reallylonghostname.com",
                    "primary": false,
                    "type": "other"
                  }
                ],
                "names": [
                  "Alberta Bobbeth Charleson"
                ],
                "phone_numbers": [
                  {
                    "data": "1112223333",
                    "primary": false,
                    "type": "home"
                  },
                  {
                    "data": "1112224444",
                    "primary": false,
                    "type": "work"
                  },
                  {
                    "data": "1112225555",
                    "primary": false,
                    "type": "mobile1"
                  }
                ]
              }
            ],
            "subtype": "checking",
            "transactions": [
              ...
              {
                "account_id": "jW4r4QvdeXcAZNj8J3Dni68DqxQ3laHZwGyBD",
                "amount": -500,
                "date": "2018-03-25",
                "original_description": "United Airlines  REFUND ",
                "pending": false,
                "transaction_id": "wPkQknvpz9HV8bPK465rC6GnyrnlrXCMr9vgm",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              },
              {
                "account_id": "jW4r4QvdeXcAZNj8J3Dni68DqxQ3laHZwGyBD",
                "amount": 5.4,
                "date": "2018-03-27",
                "original_description": "Uber 063015 SFPOOL",
                "pending": false,
                "transaction_id": "GM4K4LJqGBu5g8yqjkQJuVnry6rz6zh8Qwkv9",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              },
              {
                "account_id": "jW4r4QvdeXcAZNj8J3Dni68DqxQ3laHZwGyBD",
                "amount": 6.33,
                "date": "2018-04-09",
                "original_description": "Uber 072515 SFPOOL",
                "pending": false,
                "transaction_id": "DekykZJWrjf5g7kjRaLvceLZb4avg5CVBDGz5x",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              }
            ],
            "type": "depository"
          },
          {
            "account_id": "V3EkERBQXGF5z6Jb9NDkupNeoy1b81cjpWVDe",
            "balances": {
              "available": 200,
              "current": 210
            },
            "days_available": 730,
            "historical_balances": [
              {
                "current": 210,
                "date": "2018-04-12",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              },
              {
                "current": 210,
                "date": "2018-04-11",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              },
              {
                "current": 210,
                "date": "2018-04-10",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              },
              ...
            ],
            "mask": "1111",
            "name": "Plaid Saving",
            "official_name": "Plaid Silver Standard 0.1% Interest Saving",
            "owners": [
              {
                "addresses": [
                  {
                    "data": {
                      "city": "Malakoff",
                      "state": "NY",
                      "street": "2992 Cameron Road",
                      "zip": "14236"
                    },
                    "primary": true
                  },
                  {
                    "data": {
                      "city": "San Matias",
                      "state": "CA",
                      "street": "2493 Leisure Lane",
                      "zip": "93405-2255"
                    },
                    "primary": false
                  }
                ],
                "emails": [
                  {
                    "data": "accountholder0@example.com",
                    "primary": true,
                    "type": "primary"
                  },
                  {
                    "data": "accountholder1@example.com",
                    "primary": false,
                    "type": "secondary"
                  },
                  {
                    "data": "extraordinarily.long.email.username.123456@reallylonghostname.com",
                    "primary": false,
                    "type": "other"
                  }
                ],
                "names": [
                  "Alberta Bobbeth Charleson"
                ],
                "phone_numbers": [
                  {
                    "data": "1112223333",
                    "primary": false,
                    "type": "home"
                  },
                  {
                    "data": "1112224444",
                    "primary": false,
                    "type": "work"
                  },
                  {
                    "data": "1112225555",
                    "primary": false,
                    "type": "mobile1"
                  }
                ]
              }
            ],
            "subtype": "savings",
            "transactions": [
              ...
              {
                "account_id": "V3EkERBQXGF5z6Jb9NDkupNeoy1b81cjpWVDe",
                "amount": 25,
                "date": "2018-02-25",
                "original_description": "CREDIT CARD 3333 PAYMENT //",
                "pending": false,
                "transaction_id": "LkexeEJ3Ryf5Vw3evRMMIXlLjkRkawIdzm6Ak",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              },
              {
                "account_id": "V3EkERBQXGF5z6Jb9NDkupNeoy1b81cjpWVDe",
                "amount": -4.22,
                "date": "2018-03-22",
                "original_description": "INTRST PYMNT",
                "pending": false,
                "transaction_id": "y7EJEmwgazsjJDVdMZ3QSQBKpaKnQzSjElP71M",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              },
              {
                "account_id": "V3EkERBQXGF5z6Jb9NDkupNeoy1b81cjpWVDe",
                "amount": 25,
                "date": "2018-03-27",
                "original_description": "CREDIT CARD 3333 PAYMENT //",
                "pending": false,
                "transaction_id": "dLz7z41KlaSWLbmJqpxXiaqPgJPbn5IgMwymJ",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              }
            ],
            "type": "depository"
          },
          {
            "account_id": "4RWyWq143jIEm7BaqJNKCQyG9Ndnv5iJaENyV",
            "balances": {
              "available": null,
              "current": 5000
            },
            "days_available": 730,
            "historical_balances": [
              {
                "current": 5000,
                "date": "2018-04-12",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              },
              {
                "current": 1000,
                "date": "2018-04-11",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              },
              {
                "current": 1000,
                "date": "2018-04-10",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              },
              ...
            ],
            "mask": "2222",
            "name": "Plaid CD",
            "official_name": "Plaid Bronze Standard 0.2% Interest CD",
            "owners": [
              {
                "addresses": [
                  {
                    "data": {
                      "city": "Malakoff",
                      "state": "NY",
                      "street": "2992 Cameron Road",
                      "zip": "14236"
                    },
                    "primary": true
                  },
                  {
                    "data": {
                      "city": "San Matias",
                      "state": "CA",
                      "street": "2493 Leisure Lane",
                      "zip": "93405-2255"
                    },
                    "primary": false
                  }
                ],
                "emails": [
                  {
                    "data": "accountholder0@example.com",
                    "primary": true,
                    "type": "primary"
                  },
                  {
                    "data": "accountholder1@example.com",
                    "primary": false,
                    "type": "secondary"
                  },
                  {
                    "data": "extraordinarily.long.email.username.123456@reallylonghostname.com",
                    "primary": false,
                    "type": "other"
                  }
                ],
                "names": [
                  "Alberta Bobbeth Charleson"
                ],
                "phone_numbers": [
                  {
                    "data": "1112223333",
                    "primary": false,
                    "type": "home"
                  },
                  {
                    "data": "1112224444",
                    "primary": false,
                    "type": "work"
                  },
                  {
                    "data": "1112225555",
                    "primary": false,
                    "type": "mobile1"
                  }
                ]
              }
            ],
            "subtype": "cd",
            "transactions": [
              ...
              {
                "account_id": "4RWyWq143jIEm7BaqJNKCQyG9Ndnv5iJaENyV",
                "amount": 1000,
                "date": "2018-01-25",
                "original_description": "CD DEPOSIT .INITIAL.",
                "pending": false,
                "transaction_id": "M8QdQWJx1GS51ZymxjNNILQ7GwjwG1I3qr3RwX",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              },
              {
                "account_id": "4RWyWq143jIEm7BaqJNKCQyG9Ndnv5iJaENyV",
                "amount": 1000,
                "date": "2018-02-24",
                "original_description": "CD DEPOSIT .INITIAL.",
                "pending": false,
                "transaction_id": "q3Z4ZgvempFnljLVzqxxhPQ3we7eW9sdJy5jP",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              },
              {
                "account_id": "4RWyWq143jIEm7BaqJNKCQyG9Ndnv5iJaENyV",
                "amount": 1000,
                "date": "2018-03-26",
                "original_description": "CD DEPOSIT .INITIAL.",
                "pending": false,
                "transaction_id": "aZqNqxQAEyHvboB8jazrsbPWNwW6WxU8zRj5kw",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              }
            ],
            "type": "depository"
          }
        ],
        "date_last_updated": "2018-04-12T03:32:10Z",
        "institution_id": "ins_109511",
        "institution_name": "Tartan Bank",
        "item_id": "zeWoWyv84xfkGg1w4ox5iQy5k6j75xu8QXMEm"
      }
    ],
    "user": {
      "client_user_id": "123456789",
      "email": "accountholder0@example.com",
      "first_name": "Alberta",
      "last_name": "Charleson",
      "middle_name": "Bobbeth",
      "phone_number": "111-222-3333",
      "ssn": "123-45-6789"
    }
  },
  "request_id": "pdwYD",
  "warnings": []
}

http code 200
{
  "report": {
    "asset_report_id": "c5b638f9-02b8-45c6-9093-552195149b0c",
    "client_report_id": "123456",
    "date_generated": "2018-04-12T03:32:11Z",
    "days_requested": 730,
    "items": [
      {
        "accounts": [
          {
            "account_id": "jW4r4QvdeXcAZNj8J3Dni68DqxQ3laHZwGyBD",
            "balances": {
              "available": 100,
              "current": 110
            },
            "days_available": 730,
            "historical_balances": [
              {
                "current": 110,
                "date": "2018-04-12",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              },
              {
                "current": 110,
                "date": "2018-04-11",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              },
              {
                "current": 110,
                "date": "2018-04-10",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              },
              ...
            ],
            "mask": "0000",
            "name": "Plaid Checking",
            "official_name": "Plaid Gold Standard 0% Interest Checking",
            "owners": [
              {
                "addresses": [
                  {
                    "data": {
                      "city": "Malakoff",
                      "state": "NY",
                      "street": "2992 Cameron Road",
                      "zip": "14236"
                    },
                    "primary": true
                  },
                  {
                    "data": {
                      "city": "San Matias",
                      "state": "CA",
                      "street": "2493 Leisure Lane",
                      "zip": "93405-2255"
                    },
                    "primary": false
                  }
                ],
                "emails": [
                  {
                    "data": "accountholder0@example.com",
                    "primary": true,
                    "type": "primary"
                  },
                  {
                    "data": "accountholder1@example.com",
                    "primary": false,
                    "type": "secondary"
                  },
                  {
                    "data": "extraordinarily.long.email.username.123456@reallylonghostname.com",
                    "primary": false,
                    "type": "other"
                  }
                ],
                "names": [
                  "Alberta Bobbeth Charleson"
                ],
                "phone_numbers": [
                  {
                    "data": "1112223333",
                    "primary": false,
                    "type": "home"
                  },
                  {
                    "data": "1112224444",
                    "primary": false,
                    "type": "work"
                  },
                  {
                    "data": "1112225555",
                    "primary": false,
                    "type": "mobile1"
                  }
                ]
              }
            ],
            "subtype": "checking",
            "transactions": [
              ...
              {
                "account_id": "jW4r4QvdeXcAZNj8J3Dni68DqxQ3laHZwGyBD",
                "amount": -500,
                "date": "2018-03-25",
                "original_description": "United Airlines  REFUND ",
                "pending": false,
                "transaction_id": "wPkQknvpz9HV8bPK465rC6GnyrnlrXCMr9vgm",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              },
              {
                "account_id": "jW4r4QvdeXcAZNj8J3Dni68DqxQ3laHZwGyBD",
                "amount": 5.4,
                "date": "2018-03-27",
                "original_description": "Uber 063015 SFPOOL",
                "pending": false,
                "transaction_id": "GM4K4LJqGBu5g8yqjkQJuVnry6rz6zh8Qwkv9",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              },
              {
                "account_id": "jW4r4QvdeXcAZNj8J3Dni68DqxQ3laHZwGyBD",
                "amount": 6.33,
                "date": "2018-04-09",
                "original_description": "Uber 072515 SFPOOL",
                "pending": false,
                "transaction_id": "DekykZJWrjf5g7kjRaLvceLZb4avg5CVBDGz5x",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              }
            ],
            "type": "depository"
          },
          {
            "account_id": "V3EkERBQXGF5z6Jb9NDkupNeoy1b81cjpWVDe",
            "balances": {
              "available": 200,
              "current": 210
            },
            "days_available": 730,
            "historical_balances": [
              {
                "current": 210,
                "date": "2018-04-12",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              },
              {
                "current": 210,
                "date": "2018-04-11",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              },
              {
                "current": 210,
                "date": "2018-04-10",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              },
              ...
            ],
            "mask": "1111",
            "name": "Plaid Saving",
            "official_name": "Plaid Silver Standard 0.1% Interest Saving",
            "owners": [
              {
                "addresses": [
                  {
                    "data": {
                      "city": "Malakoff",
                      "state": "NY",
                      "street": "2992 Cameron Road",
                      "zip": "14236"
                    },
                    "primary": true
                  },
                  {
                    "data": {
                      "city": "San Matias",
                      "state": "CA",
                      "street": "2493 Leisure Lane",
                      "zip": "93405-2255"
                    },
                    "primary": false
                  }
                ],
                "emails": [
                  {
                    "data": "accountholder0@example.com",
                    "primary": true,
                    "type": "primary"
                  },
                  {
                    "data": "accountholder1@example.com",
                    "primary": false,
                    "type": "secondary"
                  },
                  {
                    "data": "extraordinarily.long.email.username.123456@reallylonghostname.com",
                    "primary": false,
                    "type": "other"
                  }
                ],
                "names": [
                  "Alberta Bobbeth Charleson"
                ],
                "phone_numbers": [
                  {
                    "data": "1112223333",
                    "primary": false,
                    "type": "home"
                  },
                  {
                    "data": "1112224444",
                    "primary": false,
                    "type": "work"
                  },
                  {
                    "data": "1112225555",
                    "primary": false,
                    "type": "mobile1"
                  }
                ]
              }
            ],
            "subtype": "savings",
            "transactions": [
              ...
              {
                "account_id": "V3EkERBQXGF5z6Jb9NDkupNeoy1b81cjpWVDe",
                "amount": 25,
                "date": "2018-02-25",
                "original_description": "CREDIT CARD 3333 PAYMENT //",
                "pending": false,
                "transaction_id": "LkexeEJ3Ryf5Vw3evRMMIXlLjkRkawIdzm6Ak",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              },
              {
                "account_id": "V3EkERBQXGF5z6Jb9NDkupNeoy1b81cjpWVDe",
                "amount": -4.22,
                "date": "2018-03-22",
                "original_description": "INTRST PYMNT",
                "pending": false,
                "transaction_id": "y7EJEmwgazsjJDVdMZ3QSQBKpaKnQzSjElP71M",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              },
              {
                "account_id": "V3EkERBQXGF5z6Jb9NDkupNeoy1b81cjpWVDe",
                "amount": 25,
                "date": "2018-03-27",
                "original_description": "CREDIT CARD 3333 PAYMENT //",
                "pending": false,
                "transaction_id": "dLz7z41KlaSWLbmJqpxXiaqPgJPbn5IgMwymJ",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              }
            ],
            "type": "depository"
          },
          {
            "account_id": "4RWyWq143jIEm7BaqJNKCQyG9Ndnv5iJaENyV",
            "balances": {
              "available": null,
              "current": 5000
            },
            "days_available": 730,
            "historical_balances": [
              {
                "current": 5000,
                "date": "2018-04-12",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              },
              {
                "current": 1000,
                "date": "2018-04-11",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              },
              {
                "current": 1000,
                "date": "2018-04-10",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              },
              ...
            ],
            "mask": "2222",
            "name": "Plaid CD",
            "official_name": "Plaid Bronze Standard 0.2% Interest CD",
            "owners": [
              {
                "addresses": [
                  {
                    "data": {
                      "city": "Malakoff",
                      "state": "NY",
                      "street": "2992 Cameron Road",
                      "zip": "14236"
                    },
                    "primary": true
                  },
                  {
                    "data": {
                      "city": "San Matias",
                      "state": "CA",
                      "street": "2493 Leisure Lane",
                      "zip": "93405-2255"
                    },
                    "primary": false
                  }
                ],
                "emails": [
                  {
                    "data": "accountholder0@example.com",
                    "primary": true,
                    "type": "primary"
                  },
                  {
                    "data": "accountholder1@example.com",
                    "primary": false,
                    "type": "secondary"
                  },
                  {
                    "data": "extraordinarily.long.email.username.123456@reallylonghostname.com",
                    "primary": false,
                    "type": "other"
                  }
                ],
                "names": [
                  "Alberta Bobbeth Charleson"
                ],
                "phone_numbers": [
                  {
                    "data": "1112223333",
                    "primary": false,
                    "type": "home"
                  },
                  {
                    "data": "1112224444",
                    "primary": false,
                    "type": "work"
                  },
                  {
                    "data": "1112225555",
                    "primary": false,
                    "type": "mobile1"
                  }
                ]
              }
            ],
            "subtype": "cd",
            "transactions": [
              ...
              {
                "account_id": "4RWyWq143jIEm7BaqJNKCQyG9Ndnv5iJaENyV",
                "amount": 1000,
                "date": "2018-01-25",
                "original_description": "CD DEPOSIT .INITIAL.",
                "pending": false,
                "transaction_id": "M8QdQWJx1GS51ZymxjNNILQ7GwjwG1I3qr3RwX",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              },
              {
                "account_id": "4RWyWq143jIEm7BaqJNKCQyG9Ndnv5iJaENyV",
                "amount": 1000,
                "date": "2018-02-24",
                "original_description": "CD DEPOSIT .INITIAL.",
                "pending": false,
                "transaction_id": "q3Z4ZgvempFnljLVzqxxhPQ3we7eW9sdJy5jP",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              },
              {
                "account_id": "4RWyWq143jIEm7BaqJNKCQyG9Ndnv5iJaENyV",
                "amount": 1000,
                "date": "2018-03-26",
                "original_description": "CD DEPOSIT .INITIAL.",
                "pending": false,
                "transaction_id": "aZqNqxQAEyHvboB8jazrsbPWNwW6WxU8zRj5kw",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              }
            ],
            "type": "depository"
          }
        ],
        "date_last_updated": "2018-04-12T03:32:10Z",
        "institution_id": "ins_109511",
        "institution_name": "Tartan Bank",
        "item_id": "zeWoWyv84xfkGg1w4ox5iQy5k6j75xu8QXMEm"
      }
    ],
    "user": {
      "client_user_id": "123456789",
      "email": "accountholder0@example.com",
      "first_name": "Alberta",
      "last_name": "Charleson",
      "middle_name": "Bobbeth",
      "phone_number": "111-222-3333",
      "ssn": "123-45-6789"
    }
  },
  "request_id": "pdwYD",
  "warnings": []
}
Retrieve JSON Report response data elements

The /asset_report/get response combines data Plaid retrieves from financial institutions (the items object) and data that you submitted when you created the Asset Report (the user object).

Field Type Description
report Report object The data comprising the Asset Report; see Report object for fields
request_id string A unique identifier included in Plaid success and error responses; this can be shared with Plaid Support to expedite investigation
warnings Warning objects (list)
Report object
Field Type Description
asset_report_id string Plaid’s unique identifier for this Asset Report
client_report_id string An identifier you determine and submit for the Asset Report
date_generated datetime The date and time when the Asset Report was created
days_requested integer The duration of transaction history you requested
user User object Data submitted by you about the user whose Asset Report is being compiled; see User object for fields
items Item objects (list) Data returned by Plaid about each of the Items included in the Asset Report; see Item object for fields
Item object
Field Type Description
item_id string Plaid’s unique identifier for the Item
institution_name string The full financial institution name associated with the Item
institution_id string The financial institution associated with the Item
date_last_updated datetime The date and time when this Item’s data was retrieved from the financial institution
accounts Account objects (list) Data about each of the accounts open on the Item; see Account object for fields
Account object
Field Type Description
account_id string Plaid’s unique identifier for the account
mask string The last 2-5 digits of the account's number
name string The name of the account, either assigned by the user or by the financial institution itself
official_name string The official name of the account as given by the financial institution
type string See below
subtype string See below
owners Owner objects (list) Data returned by the financial institution about the account owner or owners; see Owner object for fields
balances Balance object Data about the various balances on the account; see Balance object for fields
historical_balances Historical balance objects (list) Calculated data about the historical balances on the account; see Historical balance object for fields
transactions Transaction objects (list) Data about the transactions
days_available integer The duration of transaction history available for this Item, typically defined as the time since the date of the earliest transaction in that account

Account type and subtype are indicated as follows:

Type Subtype
depository checking, savings, money market, paypal, prepaid
credit credit card, paypal, line of credit, rewards
brokerage 401k, brokerage, ira, retirement, roth, ugma
loan auto, commercial, construction, consumer, home, home equity, loan, mortgage, overdraft, line of credit, student
mortgage home
other 403B, cash management, cd, hsa, keogh, money market, mutual fund, prepaid, recurring, rewards, safe deposit, sarsep, other
Owner object

The owner object consists of data returned from the financial institution, whereas the user object consists of data you optionally submit yourself when creating the Asset Report.

Field Type Description
names strings (list) A list of names associated with the account by the financial institution
phone_numbers Phone number objects (list) A list of phone numbers associated with the account by the financial institution; see Phone number object for fields
emails Email number objects (list) A list of emails associated with the account by the financial institution; see Email object for fields
addresses Address objects (list) Data about the various addresses associated with the account by the financial institution; see Address object for fields
Phone number object
Field Type Description
data string The phone number
primary boolean When true, identifies the phone number as the primary number on an account
type string The type of phone number as described by the financial institution

Example: "mobile"
Email object
Field Type Description
data string The email address
primary boolean When true, identifies the email address as the primary email address on an account
type string The type of email

Example: "secondary"
Address object
Field Type Description
data Address data object Data about the components comprising an address; see Address data object for fields.
primary boolean When true, identifies the address as the primary address on an account
Address data object
Field Type Description
city string The full city name
state string The two-letter state abbreviation

Example: "NC"
street string The full street address

Example: “564 Main Street, APT 15”
zip string The five or nine digit postal code
Balance object
Field Type Description
available decimal The amount of funds available to be withdrawn from an account, as determined by the financial institution. The available balance typically, but not always, equals the current balance less any pending outflows plus any pending inflows.

Not all institutions calculate the available balance; in the event that available balance is unavailable from the institution, Plaid will return an available balance value of null.
current decimal The total amount of funds in the account
iso_currency_code string The ISO currency code of the transaction, either USD or CAD. Always null if unofficial_currency_code is non-null.
unofficial_currency_code string The unofficial currency code associated with the transaction. Always null if iso_currency_code is non-null.
Historical balance object
Field Type Description
date date The date of the calculated historical balance
current decimal The total amount of funds in the account, calculated from the current balance in the balance object by subtracting inflows and adding back outflows according to the posted date of each

If the account has any pending transactions, historical balance amounts on or after the date of the earliest pending transaction may differ if retrieved in subsequent Asset Reports as a result of those pending transactions posting
iso_currency_code string The ISO currency code of the transaction, either USD or CAD. Always null if unofficial_currency_code is non-null.
unofficial_currency_code string The unofficial currency code associated with the transaction. Always null if iso_currency_code is non-null.
Transaction object
Field Type Description
account_id string Plaid’s unique identifier for the account
transaction_id string Plaid’s unique identifier for the transaction
date date For pending transactions, Plaid returns the date the transaction occurred; for posted transactions, Plaid returns the date the transaction posts; both dates are returned in an ISO 8601 format (YYYY-MM-DD).
original_description string The string returned by the financial institution to describe the transaction
pending boolean When true, identifies the transaction as pending or unsettled; pending transaction details (description, amount) may change before they are settled
amount decimal The settled dollar value; positive values when money moves out of the account, negative values when money moves in

For example, purchases are positive, while credit card payments, direct deposits, and refunds are negative
iso_currency_code string The ISO currency code of the transaction, either USD or CAD. Always null if unofficial_currency_code is non-null.
unofficial_currency_code string The unofficial currency code associated with the transaction. Always null if iso_currency_code is non-null.

Warning object

Field Type Description
warning_type string The warning type, which will always be "ASSET_REPORT_WARNING".
warning_code string The warning code identifies a specific kind of warning. Currently, the only possible warning code is "OWNERS_UNAVAILABLE", which indicates that account-owner information is not available.
cause Cause The underlying cause of this warning.
Cause object
Field Type Description
error Error The underlying error. See the section on errors for details.
item_id string The item ID.
Retrieve PDF Report request

To retrieve the Asset Report as a pre-formatted PDF, call the /asset_report/pdf/get endpoint. On success, the request id for /asset_report/pdf/get is returned in the Plaid-Request-ID header.


client.getAssetReportPdf(ASSET_REPORT_TOKEN, (error, pdfResponse) => {
  if (error != null) {
    // Handle error.
  }

  // The PDF is binary data.
  const pdf = pdfResponse;
});

curl -X POST https://sandbox.plaid.com/asset_report/pdf/get \
 -H 'Content-Type: application/json' \
 -d '{
   "client_id": String,
   "secret": String,
   "asset_report_token": String
 }' \
 -o 'asset_report.pdf'

pdf = @client.asset_report.get_pdf(asset_report_token)

Response<AssetReportGetPdfResponse> response =
  client
  .service()
  .assetReportPdfGet(new AssetReportPdfGetRequest(assetReportToken);)
  .execute();
byte[] pdf = response.body().bytes();

pdf = client.AssetReport.get_pdf(asset_report_token)
4. Share an Audit Copy

Plaid can provide an Audit Copy of any Asset Report directly to a participating third party on your behalf. For example, Plaid will supply an Audit Copy directly to Fannie Mae on your behalf if you participate in the Day 1 Certainty™ program.

An Audit Copy contains the same underlying data as the Asset Report. To grant access to an Audit Copy, you’ll create an audit_copy_token for it and then pass that token to the third party who needs access. Each third party has its own auditor_id, for example fannie_mae. You’ll need to create a separate Audit Copy for each third party to whom you want to grant access to the Report.

Simply call the /asset_report/audit_copy/create endpoint as follows:

Create Audit Copy request

// The auditor ID corresponds to the third party with which you want to share
// the asset report. For example, Fannie Mae's auditor ID is 'fannie_mae'.
const auditorId = 'fannie_mae';

client.createAuditCopy(ASSET_REPORT_TOKEN, auditorId, (error, createResponse) => {
  if (error != null) {
    // Handle error.
  }

  const auditCopyToken = createResponse.audit_copy_token;
});

curl -X POST https://sandbox.plaid.com/asset_report/audit_copy/create \
 -H 'Content-Type: application/json' \
 -d '{
   "client_id": String,
   "secret": String,
   "asset_report_token": String,
   "auditor_id": String
 }'

# The auditor ID corresponds to the third party with which you want to share
# the asset report. For example, Fannie Mae's auditor ID is 'fannie_mae'.
auditor_id = 'fannie_mae'

response = @client.asset_report.create_audit_copy(asset_report_token, auditor_id)
audit_copy_token = response.audit_copy_token

// The auditor ID corresponds to the third party with which you want to share
// the asset report. For example, Fannie Mae's auditor ID is "fannie_mae".
String auditorId = "fannie_mae";
AssetReportAuditCopyCreateRequest request =
  new AssetReportAuditCopyCreateRequest(assetReportToken, auditorId);
Response<AssetReportAuditCopyCreateResponse> response =
  client
  .service()
  .assetReportAuditCopyCreate(request)
  .execute();
String auditCopyToken = response.body().getAuditCopyToken();

# The auditor ID corresponds to the third party with which you want to share
# the asset report. For example, Fannie Mae's auditor ID is 'fannie_mae'.
auditor_id = 'fannie_mae'

response = client.AssetReport.audit_copy.create(asset_report_token, auditor_id)
audit_copy_token = response['audit_copy_token']
Create Audit Copy response

http code 200
{
   "audit_copy_token": "a-sandbox-3TAU2CWVYBDVRHUCAAAI27ULU4",
   "request_id": "Iam3b"
}

http code 200
{
   "audit_copy_token": "a-sandbox-3TAU2CWVYBDVRHUCAAAI27ULU4",
   "request_id": "Iam3b"
}

http code 200
{
   "audit_copy_token": "a-sandbox-3TAU2CWVYBDVRHUCAAAI27ULU4",
   "request_id": "Iam3b"
}

http code 200
{
   "audit_copy_token": "a-sandbox-3TAU2CWVYBDVRHUCAAAI27ULU4",
   "request_id": "Iam3b"
}

http code 200
{
   "audit_copy_token": "a-sandbox-3TAU2CWVYBDVRHUCAAAI27ULU4",
   "request_id": "Iam3b"
}

Store the audit_copy_token in a secure datastore.

Next pass the audit_copy_token to the third party you want to have access to the Audit Copy. The third party will then be able to access the Audit Copy directly from Plaid using the token along with its client_id and secret.

Additional Fannie Mae Day 1 Certainty™ considerations

To be eligible for Day 1 Certainty™, three otherwise optional fields are required when creating an Asset Report. Fannie Mae requires the first_name, last_name and ssn fields within the User object. You can omit these if you do not plan to pass an audit_copy_token to Fannie Mae. Additionally, days_requested must be at least 61 for new originations or at least 31 for refinancings.

Only Asset Reports created within the production environment are compatible with Day 1 Certainty™. Asset Reports created in the sandbox or development environments cannot be accessed by Fannie Mae.

Remove Asset Reports and Audit Copies

The /item/remove endpoint allows you to invalidate an access_token, meaning you will not be able to create new Asset Reports with it. Removing an Item does not affect any Asset Reports or Audit Copies you have already created, which will remain accessible until you remove them specifically. In other words, removing an Item does not cascade-remove any Asset Reports.

The /asset_report/remove endpoint allows you to remove an Asset Report. Removing an Asset Report invalidates its asset_report_token, meaning you will no longer be able to use it to access Report data or create new Audit Copies. Removing an Asset Report does not affect the underlying Items, but does also invalidate any audit_copy_tokens associated with the Asset Report. In other words, removing an Asset Report also cascade-removes its Audit Copies.

Remove Asset Report request

client.removeAssetReport(ASSET_REPORT_TOKEN, (error, removeResponse) => {
  if (error != null) {
    // Handle error.
  }

  const removed = removeResponse.removed;
});

curl -X POST https://sandbox.plaid.com/asset_report/remove \
 -H 'Content-Type: application/json' \
 -d '{
   "client_id": String,
   "secret": String,
   "asset_report_token": String
 }'

response = @client.asset_report.remove_asset_report(asset_report_token)
removed = response.removed

  Response<AssetReportRemoveResponse> response =
    client
    .service()
    .assetReportRemove(new AssetReportRemoveRequest(assetReportToken))
    .execute();
  boolean removed = response.body().getRemoved();

response = client.AssetReport.remove(asset_report_token)
removed = response['removed']
Remove Asset Report response

http code 200
{
 "removed": true,
 "request_id": "I6zHN"
}

http code 200
{
 "removed": true,
 "request_id": "I6zHN"
}

http code 200
{
 "removed": true,
 "request_id": "I6zHN"
}

http code 200
{
 "removed": true,
 "request_id": "I6zHN"
}

http code 200
{
 "removed": true,
 "request_id": "I6zHN"
}

The /asset_report/audit_copy/remove endpoint allows you to remove an Audit Copy. Removing an Audit Copy invalidates the audit_copy_token associated with it, meaning both you and any third parties holding the token will no longer be able to use it to access Report data. Items associated with the Asset Report, the Asset Report itself and other Audit Copies of it are not affected and will remain accessible after removing the given Audit Copy.

Remove Audit Copy request

// AUDIT_COPY_TOKEN is the token from the createAuditCopy response.
client.removeAuditCopy(AUDIT_COPY_TOKEN, (error, removeResponse) => {
  if (error != null) {
    // Handle error.
  }

  const removed = removeResponse.removed;
});

curl -X POST https://sandbox.plaid.com/asset_report/audit_copy/remove \
 -H 'Content-Type: application/json' \
 -d '{
   "client_id": String,
   "secret": String,
   "audit_copy_token": String
 }'

# audit_copy_token is the token from the create_audit_copy response.
response = @client.asset_report.remove_audit_copy(audit_copy_token)
removed = response.removed

// auditCopyToken is the token from the AssetReportCreateAuditCopyRequest
// response.
Response<AssetReportAuditCopyRemoveResponse> response =
  client
  .service()
  .assetReportAuditCopyRemove(new AssetReportAuditCopyRemoveRequest(auditCopyToken))
  .execute();
boolean removed = response.body().getRemoved();

# audit_copy_token is the token from the AssetReport.audit_copy.create response.
response = client.AssetReport.audit_copy.remove(audit_copy_token)
removed = response['removed']

Remove Audit Copy response


http code 200
{
 "removed": true,
 "request_id": "m8MDnv9okwxFNBV"
}

Item management

Accounts

Account data elements
Key Description
account_id
String
The unique ID of the account.

Note: In some instances, account IDs may change.
item
Object
Information about the Item associated with the accounts such as the item ID and institution ID. See POST /item/get for more information.
balances
Object
The current balance is the total amount of funds in the account. The available balance is the amount of funds available to be withdrawn from an account, as determined by the financial institution. The available balance typically, but not always, equals the current balance less any pending outflows plus any pending inflows.

Note: Not all institutions calculate the available balance. In the event that available balance is unavailable from the institution, Plaid will return an available balance value of null.
name
String
The name of the Account, either assigned by the user or the financial institution itself.
mask
String
The last four digits of the Account's number.
official_name
String
The official name of the Account as given by the financial institution.
type
String
See account types below.
subtype
String
See account subtypes below.
Account type Description
brokerage Brokerage account
credit Credit card
depository Checking or savings accounts
loan Loan account
mortgage Mortgage account
other Non-specified account type
Account type Subtypes
brokerage 401k, brokerage, ira, retirement, roth, ugma
credit credit card, paypal, line of credit, rewards
depository cd, checking, savings, money market, paypal, prepaid
loan auto, commercial, construction, consumer, home, home equity, loan, mortgage, overdraft, line of credit, student
mortgage home
other 403B, cash management, cd, hsa, keogh, money market, mutual fund, prepaid, recurring, rewards, safe deposit, sarsep, other
Retrieve Accounts

POST /accounts/get
Retrieve Accounts Request

// Pull the accounts associated with the Item
client.getAccounts(ACCESS_TOKEN, (err, result) => {
  // Handle err
  // High-level information about each account associated with the Item is available
  const accounts = result.accounts;
});

curl -X POST https://sandbox.plaid.com/accounts/get \
-H 'Content-Type: application/json' \
-d '{
  "client_id": String,
  "secret": String,
  "access_token": String
}'

# Pull the accounts associated with the Item
response = @client.accounts.get(@access_token)

// Pull the accounts associated with the Item
Response<AccountsGetResponse> response = client().service().accountsGet(
  new AccountsGetRequest("ACCESS_TOKEN"))
  .execute();
List<Account> accounts = response.body().getAccounts();

# Pull the accounts associated with the Item
# associated with the Item is available
response = client.Accounts.get(access_token)
accounts = response['accounts']
Retrieve Accounts Response

http code 200
{
  "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 Checking",
    "subtype": "checking",
    "type": "depository"
  }, {
    "account_id": "6Myq63K1KDSe3lBwp7K1fnEbNGLV4nSxalVdW",
    "balances": {
      "available": null,
      "current": 410,
      "limit": 2000,
      "iso_currency_code": "USD",
      "unofficial_currency_code": null,
    },
    "mask": "3333",
    "name": "Plaid Credit Card",
    "official_name": "Plaid Diamond Credit Card",
    "subtype": "credit card",
    "type": "credit"
  }],
  "item": {Object},
  "request_id": "45QSn"
}

http code 200
{
  "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 Checking",
    "subtype": "checking",
    "type": "depository"
  }, {
    "account_id": "6Myq63K1KDSe3lBwp7K1fnEbNGLV4nSxalVdW",
    "balances": {
      "available": null,
      "current": 410,
      "limit": 2000,
      "iso_currency_code": "USD",
      "unofficial_currency_code": null,
    },
    "mask": "3333",
    "name": "Plaid Credit Card",
    "official_name": "Plaid Diamond Credit Card",
    "subtype": "credit card",
    "type": "credit"
  }],
  "item": {Object},
  "request_id": "45QSn"
}

http code 200
{
  "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 Checking",
    "subtype": "checking",
    "type": "depository"
  }, {
    "account_id": "6Myq63K1KDSe3lBwp7K1fnEbNGLV4nSxalVdW",
    "balances": {
      "available": null,
      "current": 410,
      "limit": 2000,
      "iso_currency_code": "USD",
      "unofficial_currency_code": null,
    },
    "mask": "3333",
    "name": "Plaid Credit Card",
    "official_name": "Plaid Diamond Credit Card",
    "subtype": "credit card",
    "type": "credit"
  }],
  "item": {Object},
  "request_id": "45QSn"
}

http code 200
{
  "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 Checking",
    "subtype": "checking",
    "type": "depository"
  }, {
    "account_id": "6Myq63K1KDSe3lBwp7K1fnEbNGLV4nSxalVdW",
    "balances": {
      "available": null,
      "current": 410,
      "limit": 2000,
      "iso_currency_code": "USD",
      "unofficial_currency_code": null,
    },
    "mask": "3333",
    "name": "Plaid Credit Card",
    "official_name": "Plaid Diamond Credit Card",
    "subtype": "credit card",
    "type": "credit"
  }],
  "item": {Object},
  "request_id": "45QSn"
}

http code 200
{
  "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 Checking",
    "subtype": "checking",
    "type": "depository"
  }, {
    "account_id": "6Myq63K1KDSe3lBwp7K1fnEbNGLV4nSxalVdW",
    "balances": {
      "available": null,
      "current": 410,
      "limit": 2000,
      "iso_currency_code": "USD",
      "unofficial_currency_code": null,
    },
    "mask": "3333",
    "name": "Plaid Credit Card",
    "official_name": "Plaid Diamond Credit Card",
    "subtype": "credit card",
    "type": "credit"
  }],
  "item": {Object},
  "request_id": "45QSn"
}

Retrieve Item

The POST /item/get endpoint returns information about the status of an Item:

  • Available products
  • Billed products
  • Error status
  • Institution ID (institution_id)
  • Item ID (item_id)
  • Webhook
Field Required?
client_id
String
yes
secret
String
yes
access_token
String
yes
Retrieve Item

POST /item/get
Retrieve Item Request

// Pull information about the Item
client.getItem(ACCESS_TOKEN, (err, result) => {
  // Handle err
  // The Item has a list of available products, billed products, error status,
  // webhook information, and more.
  const item = result.item;
});

curl -X POST https://sandbox.plaid.com/item/get \
  -H 'Content-Type: application/json' \
  -d '{
    "client_id": String,
    "secret": String,
    "access_token": String
  }'

# Pull information about the Item
response = client.item.get(access_token)
item = response['item']

// Pull information about the Item
Response<ItemGetResponse> response =
  client().service().itemGet(new ItemGetRequest("ACCESS_TOKEN")).execute();
// The Item has a list of available products, billed products, error status,
// webhook information, and more.
Item item = response.body().getItem();

# Pull information about the Item
response = client.Item.get(access_token)
item = response['item']
Retrieve Item Response

http code 200
{
  "item": {
    "available_products": [
      "balance",
      "auth"
    ],
    "billed_products": [
      "identity",
      "transactions"
    ],
    "error": null,
    "institution_id": "ins_109508",
    "item_id": "Ed6bjNrDLJfGvZWwnkQlfxwoNz54B5C97ejBr",
    "webhook": "https://plaid.com/example/hook"
  },
  "request_id": "qpCtl"
}

http code 200
{
  "item": {
    "available_products": [
      "balance",
      "auth"
    ],
    "billed_products": [
      "identity",
      "transactions"
    ],
    "error": null,
    "institution_id": "ins_109508",
    "item_id": "Ed6bjNrDLJfGvZWwnkQlfxwoNz54B5C97ejBr",
    "webhook": "https://plaid.com/example/hook"
  },
  "request_id": "qpCtl"
}

http code 200
{
  "item": {
    "available_products": [
      "balance",
      "auth"
    ],
    "billed_products": [
      "identity",
      "transactions"
    ],
    "error": null,
    "institution_id": "ins_109508",
    "item_id": "Ed6bjNrDLJfGvZWwnkQlfxwoNz54B5C97ejBr",
    "webhook": "https://plaid.com/example/hook"
  },
  "request_id": "qpCtl"
}

http code 200
{
  "item": {
    "available_products": [
      "balance",
      "auth"
    ],
    "billed_products": [
      "identity",
      "transactions"
    ],
    "error": null,
    "institution_id": "ins_109508",
    "item_id": "Ed6bjNrDLJfGvZWwnkQlfxwoNz54B5C97ejBr",
    "webhook": "https://plaid.com/example/hook"
  },
  "request_id": "qpCtl"
}

http code 200
{
  "item": {
    "available_products": [
      "balance",
      "auth"
    ],
    "billed_products": [
      "identity",
      "transactions"
    ],
    "error": null,
    "institution_id": "ins_109508",
    "item_id": "Ed6bjNrDLJfGvZWwnkQlfxwoNz54B5C97ejBr",
    "webhook": "https://plaid.com/example/hook"
  },
  "request_id": "qpCtl"
}

Update webhook

The POST /item/webhook/update allows you to update the webhook associated with an Item. This request triggers a WEBHOOK_UPDATE_ACKNOWLEDGED webhook.

Field Required? Description
client_id
String
yes
secret
String
yes
access_token
String
yes
webhook
String
Yes The new webhook to associate with the Item.
Update webhook

POST /item/webhook/update
Update webhook request

client.updateItemWebhook(ACCESS_TOKEN, "https://my-new-webhook.com/plaid-webhook", (err, result) => {
  // Handle err
  // A successful response indicates that the webhook has been updated. An
  // acknowledgement webhook will also be fired.
  const item = result.item;
});

curl -X POST https://sandbox.plaid.com/item/webhook/update \
  -H 'Content-Type: application/json' \
  -d '{
    "client_id": String,
    "secret": String,
    "access_token": String,
    "webhook": "https://plaid.com/updated/hook"
  }'

# Update the webhook associated with an Item
webhook_response = client.item.webhook.update(item['access_token'],
                                              'https://my-new-webhook.com/plaid-webhook')

Response<ItemWebhookUpdateResponse> webhookResponse = client().service().itemWebhookUpdate(
    new ItemWebhookUpdateRequest(ACCESS_TOKEN, "https://my-new-webhook.com/plaid-webhook")).execute();
ItemStatus itemStatus = webhookResponse.body().getItem();
String webhook = itemStatus.getWebhook();

# Update the webhook associated with an Item
webhook_response = client.Item.webhook.update(
    access_token, 'https://my-new-webhook.com/plaid-webhook')
Update Webhook Response

http code 200
{
  "item": {
    "available_products": [
      "balance",
      "auth"
    ],
    "billed_products": [
      "identity",
      "transactions"
    ],
    "error": null,
    "institution_id": "ins_109508",
    "item_id": "Ed6bjNrDLJfGvZWwnkQlfxwoNz54B5C97ejBr",
    "webhook": "https://plaid.com/updated/webhook"
  },
  "request_id": "qpCtl"
}

http code 200
{
  "item": {
    "available_products": [
      "balance",
      "auth"
    ],
    "billed_products": [
      "identity",
      "transactions"
    ],
    "error": null,
    "institution_id": "ins_109508",
    "item_id": "Ed6bjNrDLJfGvZWwnkQlfxwoNz54B5C97ejBr",
    "webhook": "https://plaid.com/updated/webhook"
  },
  "request_id": "qpCtl"
}

http code 200
{
  "item": {
    "available_products": [
      "balance",
      "auth"
    ],
    "billed_products": [
      "identity",
      "transactions"
    ],
    "error": null,
    "institution_id": "ins_109508",
    "item_id": "Ed6bjNrDLJfGvZWwnkQlfxwoNz54B5C97ejBr",
    "webhook": "https://plaid.com/updated/webhook"
  },
  "request_id": "qpCtl"
}

http code 200
{
  "item": {
    "available_products": [
      "balance",
      "auth"
    ],
    "billed_products": [
      "identity",
      "transactions"
    ],
    "error": null,
    "institution_id": "ins_109508",
    "item_id": "Ed6bjNrDLJfGvZWwnkQlfxwoNz54B5C97ejBr",
    "webhook": "https://plaid.com/updated/webhook"
  },
  "request_id": "qpCtl"
}

http code 200
{
  "item": {
    "available_products": [
      "balance",
      "auth"
    ],
    "billed_products": [
      "identity",
      "transactions"
    ],
    "error": null,
    "institution_id": "ins_109508",
    "item_id": "Ed6bjNrDLJfGvZWwnkQlfxwoNz54B5C97ejBr",
    "webhook": "https://plaid.com/updated/webhook"
  },
  "request_id": "qpCtl"
}

Rotate Access Token

By default, the access_token associated with an Item does not expire and should be stored in a persistent, secure manner.

You can use the POST /item/access_token/invalidate endpoint to rotate the access_token associated with an Item. The endpoint returns a new access_token and immediately invalidates the previous access_token.

Field Required?
client_id
String
yes
secret
String
yes
access_token
String
yes
Rotate Access Token

POST /item/access_token/invalidate
Rotate Access Token request

// Generate a new access_token for an Item and invalidate the old one
client.invalidateAccessToken(ACCESS_TOKEN, (err, result) => {
  // Handle err
  // Store the new access_token in a persistent, secure datastore
  const accessToken  = result.new_acccess_token;
});

curl -X POST https://sandbox.plaid.com/item/access_token/invalidate \
  -H 'Content-Type: application/json' \
  -d '{
    "client_id": String,
    "secret": String,
    "access_token": String
  }'

# Generate a new access_token for an Item and invalidate the old one
response = client.item.access_token.invalidate(access_token)
# Store the new access_token in a persistent, secure datastore
new_access_token = response['new_acccess_token']

Response<ItemAccessTokenInvalidateResponse> response = client().service().itemAccessTokenInvalidate(
  new ItemAccessTokenInvalidateRequest("ACCESS_TOKEN")).execute();

String newAccessToken;
if (response.isSuccessful()) {
  newAccessToken = response.body().getNewAccessToken();
}

# Generate a new access_token for an Item and invalidate the old one
response = client.Item.access_token.invalidate(access_token)
# Store the new access_token in a persistent, secure datastore
new_access_token = response['new_acccess_token']
Rotate Access Token response

http code 200
{
  "new_access_token": "access-sandbox-8ab976e6-64bc-4b38-98f7-731e7a349970",
  "request_id": "ou2XQ"
}

http code 200
{
  "new_access_token": "access-sandbox-8ab976e6-64bc-4b38-98f7-731e7a349970",
  "request_id": "ou2XQ"
}

http code 200
{
  "new_access_token": "access-sandbox-8ab976e6-64bc-4b38-98f7-731e7a349970",
  "request_id": "ou2XQ"
}

http code 200
{
  "new_access_token": "access-sandbox-8ab976e6-64bc-4b38-98f7-731e7a349970",
  "request_id": "ou2XQ"
}

http code 200
{
  "new_access_token": "access-sandbox-8ab976e6-64bc-4b38-98f7-731e7a349970",
  "request_id": "ou2XQ"
}

Update Access Token version

If you have an access_token from the legacy version of Plaid’s API, you can use the /item/access_token/update_version endpoint to generate an access_token for the Item that works with the current API.

Calling this endpoint does not revoke the legacy API access_token. You can still use the legacy access_token in the legacy API environment to retrieve data. You can also begin using the new access_token with our current API immediately.

If there is a webhook associated with the Item, you will begin receiving current API webhooks as soon as a new access_token is generated for the Item.

The response includes an item_id that should be stored along the new access_token. The item_id is used to identify items in webhooks. The item_id can always be retrieved by making an /item/get request.

This endpoint is only available in the Development and Production API environments.

Field Required? Description
client_id
String
yes
secret
String
yes
access_token_v1
String
yes The legacy API access_token (160 character hexadecimal string)
Update Access Token version

POST /item/access_token/update_version
Update Access Token version request

// Generate an updated access token for the legacy token
client.updateAccessTokenVersion("LEGACY_API_ACCESS_TOKEN", (err, result) => {
  // Handle err
  // The response includes an access token compatible with Plaid's new API and
  // the item ID for the access_token, which is used to identify the Item in
  // webhook payloads from Plaid.
  // The old access token will still work with Plaid's legacy API endpoints.
  // Store the new access_token and the item_id in a persistent, secure data store.
  const newAccessToken = result.access_token;
  const itemId = result.item_id;
});

# Update a access_token created in our legacy Production environment
curl -X POST https://production.plaid.com/item/access_token/update_version \
  -H 'Content-Type: application/json' \
  -d '{
    "client_id": String,
    "secret": String,
    "access_token_v1": String
  }'

# generate an updated access token for the legacy token
response = client.item.access_token.update_version("LEGACY_API_ACCESS_TOKEN")
# The response includes an access token compatible with Plaid's new API and
# the item ID for the access_token, which is used to identify the Item in
# webhook payloads from Plaid.
# The old access token will still work with Plaid's legacy API endpoints.
# Store the new access_token and the item_id in a persistent, secure data store.
newAccessToken = response['access_token']
itemId = response['item_id']

// Generate an updated access token for the legacy token
Response<ItemAccessTokenUpdateVersionResponse> response = client().service().itemAccessTokenUpdateVersion(
  new ItemAccessTokenUpdateVersionRequest("LEGACY_API_ACCESS_TOKEN"))
  .execute();

String newAccessToken;
String itemId;
if (response.isSuccessful()) {
  // The response includes an access token compatible with Plaid's new API and
  // the item ID for the access_token, which is used to identify the Item in
  // webhook payloads from Plaid.
  // The old access token will still work with Plaid's legacy API endpoints.
  // Store the new access_token and the item_id in a persistent, secure data store.
  newAccessToken = response.body().getAccessToken();
  itemId = response.body().getItemId();
}

# generate an updated access token for the legacy token
response = client.Item.access_token.update_version("LEGACY_API_ACCESS_TOKEN")
# The response includes an access token compatible with Plaid's new API and
# the item ID for the access_token, which is used to identify the Item in
# webhook payloads from Plaid.
# The old access token will still work with Plaid's legacy API endpoints.
# Store the new access_token and the item_id in a persistent, secure data store.
newAccessToken = response.access_token
itemId = response.item_id
Update Access Token version response

http code 200
{
  "access_token": "access-production-8acd3678-3aa8-411e-bf5a-ee7851e0c75d",
  "item_id": "XkW36J3gewh9wE69VkyzSxyXwEBewBio4wwJ3",
  "request_id": "c92aB"
}

http code 200
{
  "access_token": "access-production-8acd3678-3aa8-411e-bf5a-ee7851e0c75d",
  "item_id": "XkW36J3gewh9wE69VkyzSxyXwEBewBio4wwJ3",
  "request_id": "c92aB"
}

http code 200
{
  "access_token": "access-production-8acd3678-3aa8-411e-bf5a-ee7851e0c75d",
  "item_id": "XkW36J3gewh9wE69VkyzSxyXwEBewBio4wwJ3",
  "request_id": "c92aB"
}

http code 200
{
  "access_token": "access-production-8acd3678-3aa8-411e-bf5a-ee7851e0c75d",
  "item_id": "XkW36J3gewh9wE69VkyzSxyXwEBewBio4wwJ3",
  "request_id": "c92aB"
}

http code 200
{
  "access_token": "access-production-8acd3678-3aa8-411e-bf5a-ee7851e0c75d",
  "item_id": "XkW36J3gewh9wE69VkyzSxyXwEBewBio4wwJ3",
  "request_id": "c92aB"
}

Remove an Item

The /item/remove endpoint allows you to remove an Item. Once removed, the access_token associated with the Item is no longer valid and cannot be used to access any data that was associated with the Item.

Note: In the Development environment, issuing an /item/remove request will not decrement your live credential count.

Field Required?
client_id
String
yes
secret
String
yes
access_token
String
yes
Remove Item

POST /item/remove
Remove Item request

client.removeItem(ACCESS_TOKEN, (err, result) => {
  // Handle err
  // The Item has been removed and the
  // access token is now invalid
  const isRemoved = result.removed;
});

curl -X POST https://sandbox.plaid.com/item/remove \
  -H 'Content-Type: application/json' \
  -d '{
    "client_id": String,
    "secret": String,
    "access_token": String
  }'

# Provide the access token for the Item you want to remove
response = client.item.remove(access_token)

Response<ItemRemoveResponse> response = client().service().itemRemove(
  new ItemRemoveRequest(getItemCreateResponse().getAccessToken())
).execute();
// The Item has been removed and the access token is now invalid
Boolean isRemoved = response.body().getRemoved();

# Provide the access token for the Item you want to remove
response = client.Item.remove(access_token)
Remove Item response

http code 200
{
  "removed": true,
  "request_id": "c92aB",
}

http code 200
{
  "removed": true,
  "request_id": "c92aB",
}

http code 200
{
  "removed": true,
  "request_id": "c92aB",
}

http code 200
{
  "removed": true,
  "request_id": "c92aB",
}

http code 200
{
  "removed": true,
  "request_id": "c92aB",
}

Errors

Errors overview

We use standard HTTP response codes for success and failure notifications, and our errors are further classified by error_type. In general, 200 HTTP codes correspond to success, 40X codes are for developer- or user-related failures, and 50X codes are for Plaid-related issues. We’re always working to minimize API errors related to Plaid integrations and to address connectivity issues across bank infrastructure. The best resource related to error code resolution is the Help Center.

Error schema

{
  "error_type": String,
  "error_code": String,
  "error_message": String,
  "display_message": String
}

All errors returned by the API include the following data elements:

Field Description
error_type
String
A broad categorization of the error. One of: INVALID_REQUEST, INVALID_INPUT, INSTITUTION_ERROR, RATE_LIMIT_EXCEEDED, API_ERROR, ITEM_ERROR, or ASSET_REPORT_ERROR.

Safe for programmatic use.
error_code
String
The particular error code. Each error_type has a specific set of error_codes.

Safe for programmatic use.
error_message
String
A developer-friendly representation of the error code.

This may change over time and is not safe for programmatic use.
display_message
String, nullable
A user-friendly representation of the error code. null if the error is not related to user action.

This may change over time and is not safe for programmatic use.

Invalid request errors

Returned when the request is malformed and cannot be processed.

Error type

INVALID_REQUEST
Invalid request error

{
  "error_type": "INVALID_REQUEST",
  "http_code": Enum (400, 404),
  "error_code": Enum (
    "MISSING_FIELDS",
    "UNKNOWN_FIELDS",
    "INVALID_FIELD",
    "INVALID_BODY",
    "INVALID_HEADERS",
    "NOT_FOUND",
    "SANDBOX_ONLY"
  )
  "error_message": String
  "display_message": Null,
  "request_id": String
  }
Error code Notes
MISSING_FIELDS
HTTP 400
The request was missing one or more required fields. The error_message field will list the missing field(s).
UNKNOWN_FIELDS
HTTP 400
The request included a field that is not recognized by the endpoint. The error_message field will list the extraneous field(s).
INVALID_FIELD
HTTP 400
One or more of the request body fields was improperly formatted or an invalid type.
INVALID_BODY
HTTP 400
The request body was invalid. Only JSON bodies are accepted.
INVALID_HEADERS
HTTP 400
The request was missing a required header, typically the Content-Type header.
NOT_FOUND
HTTP 404
The endpoint requested does not exist.
SANDBOX_ONLY
HTTP 400
The requested endpoint is only available in the Sandbox API environment.

Invalid input errors

Returned when all fields are provided and are in the correct format, but the values provided are incorrect in some way.

Error type

INVALID_INPUT
Invalid input error

{
  "error_type": "INVALID_INPUT",
  "http_code": 400,
  "error_code": Enum (
    "INVALID_API_KEYS",
    "UNAUTHORIZED_ENVIRONMENT",
    "INVALID_ACCESS_TOKEN",
    "INVALID_PUBLIC_TOKEN",
    "INVALID_PRODUCT",
    "INVALID_ACCOUNT_ID",
    "INVALID_INSTITUTION"
  )
  "error_message": String
  "display_message": Null,
  "request_id": String
}
Error code Notes
INVALID_API_KEYS
HTTP 400
The client ID and secret included in the request body were invalid. Find your API keys in the Dashboard.
UNAUTHORIZED_ENVIRONMENT
HTTP 400
Your client ID does not have access to this API environment. See which environments you are enabled for from the Dashboard.
INVALID_ACCESS_TOKEN
HTTP 400
Access tokens are in the format:

access-<environment>-<identifier>

This error can happen when the access_token you provided is invalid, from a different API environment, or has been removed via a /item/remove request.
INVALID_PUBLIC_TOKEN
HTTP 400
Public tokens are in the format:

public-<environment>-<identifier>

This error can happen when the public_token you provided is invalid, from a different API environment, or expired.
INVALID_PRODUCT
HTTP 400
Your client ID does not have access to this product. Contact us to gain access.
INVALID_ACCOUNT_ID
HTTP 400
One of the account_id(s) specified is invalid or does not exist.
INVALID_INSTITUTION
HTTP 400
The institution_id specified is invalid or does not exist.

Rate limit exceeded errors

Returned when the request is valid but has exceeded established rate limits. All API endpoints are rate limited and all data-access endpoints are rate limited by access_token. Exact limits are dynamic and are designed to prevent any single source of traffic from impacting overall API stability.

Error type

RATE_LIMIT_EXCEEDED
Rate limit error schema

{
  "error_type": "RATE_LIMIT_EXCEEDED",
  "http_code": 429,
  "error_code": Enum (
    "ADDITION_LIMIT",
    "AUTH_LIMIT",
    "TRANSACTIONS_LIMIT",
    "IDENTITY_LIMIT",
    "INCOME_LIMIT",
    "ITEM_GET_LIMIT",
    "RATE_LIMIT"
  )
  "error_message": String
  "display_message": nullable String,
  "request_id": String
}
Error code Notes
ADDITION_LIMIT
HTTP 429
You have exceeded your addition limit in our Development environment. To increase it, or raise it from zero, contact us.
AUTH_LIMIT
HTTP 429
Too many requests were made to the /auth/get endpoint.
TRANSACTIONS_LIMIT
HTTP 429
Too many requests were made to the /transactions/get endpoint.
IDENTITY_LIMIT
HTTP 429
Too many requests were made to the /identity/get endpoint.
INCOME_LIMIT
HTTP 429
Too many requests were made to the /income/get endpoint.
RATE_LIMIT
HTTP 429
Too many requests were made.
ITEM_GET_LIMIT
HTTP 429
Too many requests were made to the /item/get endpoint.

API errors

Returned during planned maintenance windows and in response to API errors.

Error type

API_ERROR
API error schema

{
  "error_type": "API_ERROR",
  "http_code": 500,
  "error_code": Enum (
    "INTERNAL_SERVER_ERROR",
    "PLANNED_MAINTENANCE"
  )
  "error_message": String
  "display_message": nullable String,
  "request_id": String
}
Error code Notes
INTERNAL_SERVER_ERROR
HTTP 500
Plaid was unable to process the request, either due to an internal system issue or an unsupported response from a financial institution.
PLANNED_MAINTENANCE
HTTP 500
Plaid's systems are in maintenance mode and API operations are disabled. Advanced notice will be provided if a maintenance window is ever planned.

Item errors

An ITEM_ERROR indicates that information provided for the Item (such as credentials or MFA) may be invalid or that the Item is not supported on Plaid's platform. You'll encounter ITEM_ERRORs as your users use Link via the onExit() callback.

Error type

ITEM_ERROR
Item error schema

{
  "error_type": "ITEM_ERROR",
  "http_code": 400,
  "error_code": Enum (
    "INVALID_CREDENTIALS",
    "INVALID_MFA",
    "INVALID_UPDATED_USERNAME",
    "ITEM_LOCKED",
    "ITEM_LOGIN_REQUIRED",
    "ITEM_NO_ERROR",
    "ITEM_NOT_SUPPORTED",
    "USER_SETUP_REQUIRED",
    "MFA_NOT_SUPPORTED",
    "NO_ACCOUNTS",
    "NO_AUTH_ACCOUNTS",
    "PRODUCT_NOT_READY",
    "PRODUCTS_NOT_SUPPORTED"
  )
  "error_message": String
  "display_message": nullable String,
  "request_id": String
}
Error code Notes
INVALID_CREDENTIALS
HTTP 400
The financial institution indicated that the credentials provided were invalid.
INVALID_MFA
HTTP 400
The financial institution indicated that the MFA response(s) provided were invalid.
INVALID_UPDATED_USERNAME
HTTP 400
The username provided in update mode via Link did not match the original username for the Item.
ITEM_LOCKED
HTTP 400
The financial institution indicated that the user's account is locked. The user will need to work with the institution directly to unlock their account.
ITEM_LOGIN_REQUIRED
HTTP 400
The financial institution indicated that the user's password or MFA information has changed. They will need to reauthenticate via Link's update mode
ITEM_NO_ERROR
HTTP 400
Link was initialized in update mode for an Item that is in a good state. No further action is required.
ITEM_NOT_SUPPORTED
HTTP 400
Plaid is unable to support this user's accounts due to restrictions in place at the financial institution.
USER_SETUP_REQUIRED
HTTP 400
The user must log in directly to the financial institution and take some action (agree to updated terms and conditions, change their password, etc.) before Plaid can access their accounts.
MFA_NOT_SUPPORTED
HTTP 400
Returned when the user requires a form of MFA that Plaid does not support for a given financial institution.
NO_ACCOUNTS
HTTP 400
Returned when there are no open accounts associated with the Item.
NO_AUTH_ACCOUNTS
HTTP 400
Returned from POST /auth/get when there are no valid checking or savings account(s) for which account and routing numbers could be retrieved.
PRODUCT_NOT_READY
HTTP 400
Returned when a data request has been made for a product that is not yet ready. This primarily happens when attempting to pull transactions prior to the initial pull.
PRODUCTS_NOT_SUPPORTED
HTTP 400
Returned when a data request has been made for an Item for a product that it does not support. Use the /item/get endpoint to find out which products an Item supports.

Asset Report errors and warnings

The ASSET_REPORT_ERROR and ASSET_REPORT_WARNING types identify a class of issues related to the creation of an Asset Report. ASSET_REPORT_ERROR is used for errors that prevent the creation of an Asset Report, while ASSET_REPORT_WARNING is used for warnings that limit the amount of data that can be included in the Report. Note that an Asset Report error will be returned as a standalone response, while an Asset Report warning will be returned in the warnings array on a successful response. See the Warning object reference for more.

Error type

ASSET_REPORT_ERROR
Asset Report error schema

{
  "error_type": "ASSET_REPORT_ERROR",
  "http_code": Enum (
    400,
    404,
    500
  ),
  "error_code": Enum (
    "PRODUCT_NOT_ENABLED",
    "DATA_UNAVAILABLE",
    "PRODUCT_NOT_READY",
    "ASSET_REPORT_GENERATION_FAILED",
    "INVALID_PARENT"
  ),
  "error_message": String,
  "display_message": nullable String,
  "causes": optional []Cause,
  "request_id": String
}
Error code Notes
PRODUCT_NOT_ENABLED
HTTP 400
In your request to the /asset_report/create endpoint, you included the access_token of an Item for which the assets product was not enabled. To fix this error, create the Item again with assets in the Link product array. See the Link parameter reference for more.
DATA_UNAVAILABLE
HTTP 400
Plaid was not able to pull sufficient data to generate the Asset Report. The causes field will contain detailed information about the underlying causes (e.g., institution maintenance).
PRODUCT_NOT_READY
HTTP 400
The Asset Report is still being generated. Try retrieving the Report again later.
ASSET_REPORT_GENERATION_FAILED
HTTP 500
The Asset Report could not be generated for an unknown reason. Try creating the Report again later.
INVALID_PARENT
HTTP 400 or 404
The filtered or refreshed Asset Report could not be created because the parent Asset Report is not in a good state (for example, it has been deleted).
Warning type

  ASSET_REPORT_WARNING
Asset Report warning schema

{
  "warning_type": "ASSET_REPORT_WARNING",
  "warning_code": Enum (
    "OWNERS_UNAVAILABLE"
  ),
  "cause": Cause
}
Warning code Notes
OWNERS_UNAVAILABLE Plaid was not able to pull account information due to the included Cause.

Institution errors

Returned when there are errors for the requested financial institution.

Error type

INSTITUTION_ERROR
Institution error schema

{
  "error_type": "INSTITUTION_ERROR",
  "http_code": 400,
  "error_code": Enum (
    "INSTITUTION_DOWN",
    "INSTITUTION_NOT_RESPONDING",
    "INSTITUTION_NOT_AVAILABLE",
    "INSTITUTION_NO_LONGER_SUPPORTED"
  )
  "error_message": String
  "display_message": nullable String,
  "request_id": String
}
Error code Notes
INSTITUTION_DOWN
HTTP 400
The financial institution is down, either for maintenance or due to an infrastructure issue with their systems.
INSTITUTION_NOT_RESPONDING
HTTP 400
The financial institution is failing to respond to some of our requests. Your user may be successful if they retry another time.
INSTITUTION_NOT_AVAILABLE
HTTP 400
The financial institution is not available this time.
INSTITUTION_NO_LONGER_SUPPORTED
HTTP 400
Plaid no longer supports this financial institution.

Webhooks

Transactions webhooks

You can receive notifications via a webhook whenever there are new transactions associated with an Item, including when Plaid’s initial and historical transaction pull are completed. All webhooks related to transactions have a webhook_type of TRANSACTIONS.

Code Details
INITIAL_UPDATE Fired when an Item’s initial transaction pull is completed.

Note: The default pull is 30 days.
HISTORICAL_UPDATE Fired when an Item’s historical transaction pull is completed. Plaid fetches as much data as is available from the financial institution. See data availability by institution.
DEFAULT_UPDATE Fired when new transaction data is available as Plaid performs its regular updates of the Item.
TRANSACTIONS_REMOVED Fired when posted transaction(s) for an Item are deleted. The deleted transaction IDs are included in the webhook payload.

The webhook must be in the standard format of http(s)://(www.)domain.com/. The response will contain a corresponding success message and code along with the same item_id that was returned in the initial call (examples below). Once the transaction processing has finished, you can use the Item's access_token to collect the full account and transaction information for that user.

All transactions webhooks will have a webhook_type equal to TRANSACTIONS. Each webhook payload will also include a unique webhook_code and the item_id for which the webhook is being fired.

Webhook Body
Initial Transaction Webhook

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

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

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

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

Item webhooks

Webhooks are also used to communicate changes to an Item, such as an updated webhook, or errors encountered with an Item. The error typically requires user action to resolve, such as when a user changes their password. For a complete list of possible errors, see Errors.

Code Details
WEBHOOK_UPDATE_ACKNOWLEDGED Fired when an Item’s webhook is updated.
ERROR Fired when an error is encountered with an Item. The error can be resolved by having the user go through Link’s update mode.
Item's Webhook Updated

{
  "webhook_type": "ITEM",
  "webhook_code": "WEBHOOK_UPDATE_ACKNOWLEDGED",
  "item_id": "wz666MBjYWTp2PDzzggYhM6oWWmBb",
  "error": null,
  "new_webhook": "https://plaid.com/example/webhook"
}
Error Response Webhook Example

{
  "webhook_type": "ITEM",
  "webhook_code": "ERROR",
  "item_id": "wz666MBjYWTp2PDzzggYhM6oWWmBb",
  "error": {
    "display_message": "The provided credentials were not correct. Please try again.",
    "error_code": "ITEM_LOGIN_REQUIRED",
    "error_message": "the provided credentials were not correct",
    "error_type": "ITEM_ERROR",
    "status": 400
  }
}

Income webhooks

If you're using webhooks with the Income product, you'll receive a webhook when Plaid calculates the Income data for the Item. Once you receive this webhook, you can make an /income/get API request to retrieve Income data.

Income ready webhook

{
  "webhook_type": "INCOME",
  "webhook_code": "PRODUCT_READY",
  "item_id": "wz666MBjYWTp2PDzzggYhM6oWWmBb",
  "error": null
}

Assets webhooks

When you create an Asset Report, Plaid collects account balances, account holder identity information, and transaction history for the duration specified in the days_requested field. If you attempt to retrieve an Asset Report before all the requested data has been collected, you’ll receive a response with the HTTP status code 400 and a Plaid error code of PRODUCT_NOT_READY.

To remove the need for polling, Plaid will send a webhook to the URL you supplied when creating the Asset Report once the Report has been generated. If Asset Report generation fails, Plaid will send a webhook indicating why generation failed.

Note that Assets webhooks will only be sent to the URL supplied when creating the Asset Report, not to the URLs supplied when creating the Items that are included in the Report.

Report generation successful webhook

{
  "asset_report_id": String,
  "webhook_code": "PRODUCT_READY",
  "webhook_type": "ASSETS"
}
Report generation failed webhook

{
  "asset_report_id": String,
  "error": {
    "display_message": String,
    "error_code": String,
    "error_message": String,
    "error_type": "ASSET_REPORT_ERROR"
  },
  "webhook_code": "ERROR",
  "webhook_type": "ASSETS"
}

Institutions

Institution overview

Plaid supports thousands of financial institutions, and we’re always working to add support for more. The /institutions/search endpoint makes it easy to stay up-to-date with supported institutions and help your users quickly find their institutions.

You can also use the /institutions/get endpoint to retrieve a complete list of supported institutions. This data changes frequently, and we recommend that you do not store it on your system. If you do store it, be sure to update it regularly.

Institutions endpoints


POST /institutions/get
POST /institutions/get_by_id
POST /institutions/search
Institutions by product

This is not a comprehensive list, but below you can find product coverage information for some of our most popular institutions:

Auth Transactions Balance Identity Income Assets
amex
ID:ins_10
bbt
ID:ins_2
bbvac
ID:ins_23
bofa
ID:ins_1
capone
ID:ins_9
chase
ID:ins_3
citizens
ID:ins_20
citi
ID:ins_5
huntington
ID:ins_21
keybank
ID:ins_29
mtb
ID:ins_27
nfcu
ID:ins_15
pnc
ID:ins_13
regions
ID:ins_19
schwab
ID:ins_11
simple
ID:ins_24
suntrust
ID:ins_16
td
ID:ins_14
us
ID:ins_6
usaa
ID:ins_7
wells
ID:ins_4

Information about transaction data availability for each of these financial institutions can be found at our Help Center.

To see a full list of supported institutions across all products, use the /institutions/get and /institutions/search endpoints.

Note: While we do our best to streamline the majority of bank interactions, it’s worth noting a few rare inconsistencies with certain banks and account types. For example, some newly opened accounts may be missing certain information for a short period of time while the data propagates through the bank’s systems. A detailed list of such exceptions can be found below.

Institution Notes
Chase Chase Liquid accounts do not support ACH debits, only ACH credits
SunTrust Business or Cash Manager accounts not supported
Bank of America One-time access codes not supported
Fidelity VIP access code MFA not supported
Navy Federal Credit Union Question based MFA not supported; Savings accounts not valid for ACH
USAA CyberText-code MFA not supported

Returns a JSON response containing details for all institutions that match the query parameters.

Field Required? Description
query
String
Yes The search query. Institutions with names matching the query are returned.
products
[String]
Yes Filter the Institutions based on whether they support all products listed in products. Provide null to get institutions regardless of supported products.
public_key
String
Yes
options
Object
No If provided, must be non-null.

POST /institutions/search
Search by Bank and Product

client.searchInstitutionsByName(SEARCH_QUERY, ['transactions'],
function(err, response) {
  // Handle err
  institutions = response.institutions;
});

curl -X POST https://sandbox.plaid.com/institutions/search \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "BB&T",
    "products": ["transactions"],
    "public_key": String
  }'

response = client.institutions.search(SEARCH_QUERY)
# search with products
response = client.institutions.search(SEARCH_QUERY, [:transactions])

Response<InstitutionsSearchResponse> response =
  client().service().institutionsSearch(new InstitutionsSearchRequest(SEARCH_QUERY).withProducts(Product.TRANSACTIONS)).execute();
List<Institution> results = response.body().getInstitutions();

response = client.Institutions.search(SEARCH_QUERY)
# search with products
response = client.Institutions.search(SEARCH_QUERY, products=['transactions'])
Institutions search response

http code 200
{
  "institutions": [{
    "credentials": [{
      "label": "User ID",
      "name": "username",
      "type": "text"
    }, {
      "label": "Password",
      "name": "password",
      "type": "password"
    }],
    "has_mfa": true,
    "institution_id": "ins_109509",
    "mfa": [
      "code",
      "list",
      "questions",
      "selections"
    ],
    "name": "First Gingham Credit Union",
    "products": [
      "balance",
      "identity",
      "auth",
      "transactions"
    ]
  }],
  "request_id": "DLVvK"
}

http code 200
{
  "institutions": [{
    "credentials": [{
      "label": "User ID",
      "name": "username",
      "type": "text"
    }, {
      "label": "Password",
      "name": "password",
      "type": "password"
    }],
    "has_mfa": true,
    "institution_id": "ins_109509",
    "mfa": [
      "code",
      "list",
      "questions",
      "selections"
    ],
    "name": "First Gingham Credit Union",
    "products": [
      "balance",
      "identity",
      "auth",
      "transactions"
    ]
  }],
  "request_id": "DLVvK"
}

http code 200
{
  "institutions": [{
    "credentials": [{
      "label": "User ID",
      "name": "username",
      "type": "text"
    }, {
      "label": "Password",
      "name": "password",
      "type": "password"
    }],
    "has_mfa": true,
    "institution_id": "ins_109509",
    "mfa": [
      "code",
      "list",
      "questions",
      "selections"
    ],
    "name": "First Gingham Credit Union",
    "products": [
      "balance",
      "identity",
      "auth",
      "transactions"
    ]
  }],
  "request_id": "DLVvK"
}

http code 200
{
  "institutions": [{
    "credentials": [{
      "label": "User ID",
      "name": "username",
      "type": "text"
    }, {
      "label": "Password",
      "name": "password",
      "type": "password"
    }],
    "has_mfa": true,
    "institution_id": "ins_109509",
    "mfa": [
      "code",
      "list",
      "questions",
      "selections"
    ],
    "name": "First Gingham Credit Union",
    "products": [
      "balance",
      "identity",
      "auth",
      "transactions"
    ]
  }],
  "request_id": "DLVvK"
}

http code 200
{
  "institutions": [{
    "credentials": [{
      "label": "User ID",
      "name": "username",
      "type": "text"
    }, {
      "label": "Password",
      "name": "password",
      "type": "password"
    }],
    "has_mfa": true,
    "institution_id": "ins_109509",
    "mfa": [
      "code",
      "list",
      "questions",
      "selections"
    ],
    "name": "First Gingham Credit Union",
    "products": [
      "balance",
      "identity",
      "auth",
      "transactions"
    ]
  }],
  "request_id": "DLVvK"
}

All Institutions

Returns a JSON response containing details on all financial institutions currently supported by Plaid. Because we support thousands of institutions, results are paginated.

Use the count and offset query parameters to retrieve the desired institution data.

Field Required? Description
client_id
String
Yes
secret
String
Yes
count
Number
Yes The total number of Institutions to return, with 0 < count <= 500.
offset
Number
Yes The number of Institutions to skip before returning results, with offset >= 0.
options
Object
No If provided, must be non-null.

The following options are available:

Field Default Description
products
[String]
null Filter the Institutions based on whether they support all products listed in products.
Retrieve all Institutions

 POST /institutions/get
Retrieve all Institutions request

// Pull institutions
client.getInstitutions(count, offset, (err, result) => {
  // Handle err
  const institutions = result.institutions;
});

curl -X POST https://sandbox.plaid.com/institutions/get \
  -H 'Content-Type: application/json' \
  -d '{
    "client_id": String,
    "secret":String,
    "count": Number,
    "offset": Number
  }'

response = client.institutions.get(count: count, offset: offset)
institutions = response['institutions']

Response<InstitutionsGetResponse> response =
  client().service().institutionsGet(new InstitutionsGetRequest(count, offset)).execute();
List<Institution> institutions = response.body().getInstitutions();

response = client.Institutions.get(count, offset=offset)
institutions = response['institutions']
Retrieve all Institutions response

http code 200
{
  "institutions": [
    {
      "credentials": [{
        "label": "User ID",
        "name": "username",
        "type": "text"
       }, {
        "label": "Password",
        "name": "password",
        "type": "password"
      }],
      "has_mfa": true,
      "institution_id": "ins_109508",
      "mfa": [
        "code",
        "list",
        "questions",
        "selections"
      ],
      "name": "First Platypus Bank",
      "products": [
        "balance",
        "identity",
        "auth",
        "transactions"
      ]
    }, {
    "credentials": [{
      "label": "User ID",
      "name": "username",
      "type": "text"
    }, {
      "label": "Password",
      "name": "password",
      "type": "password"
    }],
    "has_mfa": true,
    "institution_id": "ins_109509",
    "mfa": [
      "code",
      "list",
      "questions",
      "selections"
    ],
    "name": "First Gingham Credit Union",
    "products": [
      "balance",
      "identity",
      "auth",
      "transactions"
    ]
  }],
  "request_id": "lHkKq",
  "total": 5
}

http code 200
{
  "institutions": [
    {
      "credentials": [{
        "label": "User ID",
        "name": "username",
        "type": "text"
       }, {
        "label": "Password",
        "name": "password",
        "type": "password"
      }],
      "has_mfa": true,
      "institution_id": "ins_109508",
      "mfa": [
        "code",
        "list",
        "questions",
        "selections"
      ],
      "name": "First Platypus Bank",
      "products": [
        "balance",
        "identity",
        "auth",
        "transactions"
      ]
    }, {
    "credentials": [{
      "label": "User ID",
      "name": "username",
      "type": "text"
    }, {
      "label": "Password",
      "name": "password",
      "type": "password"
    }],
    "has_mfa": true,
    "institution_id": "ins_109509",
    "mfa": [
      "code",
      "list",
      "questions",
      "selections"
    ],
    "name": "First Gingham Credit Union",
    "products": [
      "balance",
      "identity",
      "auth",
      "transactions"
    ]
  }],
  "request_id": "lHkKq",
  "total": 5
}

http code 200
{
  "institutions": [
    {
      "credentials": [{
        "label": "User ID",
        "name": "username",
        "type": "text"
       }, {
        "label": "Password",
        "name": "password",
        "type": "password"
      }],
      "has_mfa": true,
      "institution_id": "ins_109508",
      "mfa": [
        "code",
        "list",
        "questions",
        "selections"
      ],
      "name": "First Platypus Bank",
      "products": [
        "balance",
        "identity",
        "auth",
        "transactions"
      ]
    }, {
    "credentials": [{
      "label": "User ID",
      "name": "username",
      "type": "text"
    }, {
      "label": "Password",
      "name": "password",
      "type": "password"
    }],
    "has_mfa": true,
    "institution_id": "ins_109509",
    "mfa": [
      "code",
      "list",
      "questions",
      "selections"
    ],
    "name": "First Gingham Credit Union",
    "products": [
      "balance",
      "identity",
      "auth",
      "transactions"
    ]
  }],
  "request_id": "lHkKq",
  "total": 5
}

http code 200
{
  "institutions": [
    {
      "credentials": [{
        "label": "User ID",
        "name": "username",
        "type": "text"
       }, {
        "label": "Password",
        "name": "password",
        "type": "password"
      }],
      "has_mfa": true,
      "institution_id": "ins_109508",
      "mfa": [
        "code",
        "list",
        "questions",
        "selections"
      ],
      "name": "First Platypus Bank",
      "products": [
        "balance",
        "identity",
        "auth",
        "transactions"
      ]
    }, {
    "credentials": [{
      "label": "User ID",
      "name": "username",
      "type": "text"
    }, {
      "label": "Password",
      "name": "password",
      "type": "password"
    }],
    "has_mfa": true,
    "institution_id": "ins_109509",
    "mfa": [
      "code",
      "list",
      "questions",
      "selections"
    ],
    "name": "First Gingham Credit Union",
    "products": [
      "balance",
      "identity",
      "auth",
      "transactions"
    ]
  }],
  "request_id": "lHkKq",
  "total": 5
}

http code 200
{
  "institutions": [
    {
      "credentials": [{
        "label": "User ID",
        "name": "username",
        "type": "text"
       }, {
        "label": "Password",
        "name": "password",
        "type": "password"
      }],
      "has_mfa": true,
      "institution_id": "ins_109508",
      "mfa": [
        "code",
        "list",
        "questions",
        "selections"
      ],
      "name": "First Platypus Bank",
      "products": [
        "balance",
        "identity",
        "auth",
        "transactions"
      ]
    }, {
    "credentials": [{
      "label": "User ID",
      "name": "username",
      "type": "text"
    }, {
      "label": "Password",
      "name": "password",
      "type": "password"
    }],
    "has_mfa": true,
    "institution_id": "ins_109509",
    "mfa": [
      "code",
      "list",
      "questions",
      "selections"
    ],
    "name": "First Gingham Credit Union",
    "products": [
      "balance",
      "identity",
      "auth",
      "transactions"
    ]
  }],
  "request_id": "lHkKq",
  "total": 5
}

Institutions by ID

Returns a JSON response containing details on a specified financial institution currently supported by Plaid.

Field Required? Description
institution_id
String
Yes
public_key
String
Yes
options
Object
No If provided, must be non-null.
Institutions by ID

 POST /institutions/get_by_id
Institutions by ID request

// Pull institution by ID
client.getInstitutionById(institutionId, (err, result) => {
  // Handle err
  const institution = result.institution;
});

curl -X POST https://sandbox.plaid.com/institutions/get_by_id \
  -H 'Content-Type: application/json' \
  -d '{
    "institution_id": "ins_109512",
    "public_key": String
  }'

response = client.institutions.get_by_id(INSTITUTION_ID)

// Pull institution by ID
Response<InstitutionsGetByIdResponse> response = client().service().institutionsGetById(new InstitutionsGetByIdRequest(INSTITUTION_ID))
  .execute();
Institution institution = response.body().getInstitution();

response = client.Institutions.get_by_id(INSTITUTION_ID)
Institutions by ID Response

http code 200
{
  "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"
    ]
  },
  "request_id": "9VpnU"
}

http code 200
{
  "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"
    ]
  },
  "request_id": "9VpnU"
}

http code 200
{
  "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"
    ]
  },
  "request_id": "9VpnU"
}

http code 200
{
  "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"
    ]
  },
  "request_id": "9VpnU"
}

http code 200
{
  "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"
    ]
  },
  "request_id": "9VpnU"
}

Categories

Category overview

Send a request to the /categories/get endpoint to get detailed information on categories returned by Plaid. This endpoint does not require authentication.

Category

POST /categories/get
All Categories request

client.getCategories(function(err, response) {
  // Handle err
  var categories = response.categories;
});

curl -X POST https://sandbox.plaid.com/categories/get \
  -H 'Content-Type: application/json' \
  -d '{}'

response = client.categories.get()
categories = response['categories']

Response<CategoriesGetResponse> response = client().service().categoriesGet(
  new CategoriesGetRequest()
).execute()
List<Category> categories = response.body().getCategories();

response = client.Categories.get()
categories = response['categories']
All Categories response

http code 200
{
  "categories": [
    {
      "group": "place",
      "hierarchy": [
        "Recreation",
        "Arts & Entertainment",
        "Circuses and Carnivals"
      ],
      "category_id": "17001013"
    },
    ...
  ],
  "request_id": "qpCtl"
}

http code 200
{
  "categories": [
    {
      "group": "place",
      "hierarchy": [
        "Recreation",
        "Arts & Entertainment",
        "Circuses and Carnivals"
      ],
      "category_id": "17001013"
    },
    ...
  ],
  "request_id": "qpCtl"
}

http code 200
{
  "categories": [
    {
      "group": "place",
      "hierarchy": [
        "Recreation",
        "Arts & Entertainment",
        "Circuses and Carnivals"
      ],
      "category_id": "17001013"
    },
    ...
  ],
  "request_id": "qpCtl"
}

http code 200
{
  "categories": [
    {
      "group": "place",
      "hierarchy": [
        "Recreation",
        "Arts & Entertainment",
        "Circuses and Carnivals"
      ],
      "category_id": "17001013"
    },
    ...
  ],
  "request_id": "qpCtl"
}

http code 200
{
  "categories": [
    {
      "group": "place",
      "hierarchy": [
        "Recreation",
        "Arts & Entertainment",
        "Circuses and Carnivals"
      ],
      "category_id": "17001013"
    },
    ...
  ],
  "request_id": "qpCtl"
}

Sandbox

To use Link in the API sandbox, simply initialize Link with the env parameter set to sandbox.

Sandbox API host

Sandbox institutions

All institutions that are available in our Development and Production environments are available in our Sandbox. Only certain test credentials are valid in the Sandbox and no interaction with the financial institutions occurs.

There are also six supported Sandbox-only Institutions that are suitable to write integration tests against:

Name ID
First Platypus Bank ins_109508
First Gingham Credit Union ins_109509
Tattersall Federal Credit Union ins_109510
Tartan Bank ins_109511
Houndstooth Bank ins_109512
Tartan-Dominion Bank of Canada ins_43

Complete information about Sandbox institutions is available from the /institutions/get endpoint in the Sandbox API environment.

Retrieve all Institutions request

curl -X POST https://sandbox.plaid.com/institutions/get \
-H 'Content-Type: application/json' \
-d '{
  "client_id": "[CLIENT_ID]",
  "secret": "[SECRET]",
  "count": 200,
  "offset": 0
}'

curl -X POST https://sandbox.plaid.com/institutions/get \
-H 'Content-Type: application/json' \
-d '{
  "client_id": "[CLIENT_ID]",
  "secret": "[SECRET]",
  "count": 200,
  "offset": 0
}'

curl -X POST https://sandbox.plaid.com/institutions/get \
-H 'Content-Type: application/json' \
-d '{
  "client_id": "[CLIENT_ID]",
  "secret": "[SECRET]",
  "count": 200,
  "offset": 0
}'

curl -X POST https://sandbox.plaid.com/institutions/get \
-H 'Content-Type: application/json' \
-d '{
  "client_id": "[CLIENT_ID]",
  "secret": "[SECRET]",
  "count": 200,
  "offset": 0
}'

curl -X POST https://sandbox.plaid.com/institutions/get \
-H 'Content-Type: application/json' \
-d '{
  "client_id": "[CLIENT_ID]",
  "secret": "[SECRET]",
  "count": 200,
  "offset": 0
}'
Retrieve Tartan Bank (institution_id: ins_109511) request

curl -X POST https://sandbox.plaid.com/institutions/get_by_id \
-H 'Content-Type: application/json' \
-d '{
  "public_key": "[PUBLIC_KEY]",
  "institution_id": "ins_109511"
}'

curl -X POST https://sandbox.plaid.com/institutions/get_by_id \
-H 'Content-Type: application/json' \
-d '{
  "public_key": "[PUBLIC_KEY]",
  "institution_id": "ins_109511"
}'

curl -X POST https://sandbox.plaid.com/institutions/get_by_id \
-H 'Content-Type: application/json' \
-d '{
  "public_key": "[PUBLIC_KEY]",
  "institution_id": "ins_109511"
}'

curl -X POST https://sandbox.plaid.com/institutions/get_by_id \
-H 'Content-Type: application/json' \
-d '{
  "public_key": "[PUBLIC_KEY]",
  "institution_id": "ins_109511"
}'

curl -X POST https://sandbox.plaid.com/institutions/get_by_id \
-H 'Content-Type: application/json' \
-d '{
  "public_key": "[PUBLIC_KEY]",
  "institution_id": "ins_109511"
}'

Creating Items in the Sandbox

Each institution works with Plaid’s Sandbox credentials. These special credentials allow you to simulate successful requests, requests that require various types of MFA, and failed requests. The default credentials are:


username: user_good
password: pass_good
pin: credential_good (when required)

You can trigger any type of MFA flow that Plaid supports when creating an Item. Do so by using username user_good and modifying the password:

Password Notes
mfa_device
Device MFA
Code for all devices: 1234
mfa_questions_<n>_<m>
Questions MFA
n-rounds of m-questions per round; answer_<i>_<j>, for j-th question in i-th round.
0 <= i, j < 9
mfa_selections
Selections MFA (simple)
Answer for all selections: "Yes"
mfa_selections_<n>_<m>_<o> Selections MFA (multiple) n-rounds of m-questions with o-answers per question; answer_<i>_<j>_0, for j-th question in i-th round.
0 < n, m < 10 and 2 <= o < 10

You can trigger any ITEM_ERROR or INSTITUTION_ERROR that you could typically receive when creating an Item. Do so by using username user_good and modifying the password:


error_[ERROR_CODE]

For example, the password error_ITEM_LOCKED allows you to simulate an ITEM_LOCKED error.

Creating Sandbox Items via the API

You can also create Items in the sandbox environment without using Link. Create a valid public_token for arbitrary institution ID and initial products. The created public_token maps to a new Sandbox Item. You can then exchange the public_token for an access_token and perform all API actions.


POST /sandbox/public_token/create
Field Required? Description
institution_id
String
Yes
public_key
String
Yes
initial_products
[String]
Yes The products to initially pull for the Item. May be any products that the specified institution_id supports.
options
Object, optional
No If provided, must be non-null.
Field Default Description
webhook
String
Specify a webhook to associate with the new Item.
Create Sandbox Item request

// Generate a public_token for a given institution ID and set of initial products
client.sandboxPublicTokenCreate(
  INSTITUTION_ID, INITIAL_PRODUCTS, function(err, createResponse) {
  // Handle error, if present
  var publicToken = createResponse.public_token;
  // The generated public_token can now be exchanged for an access_token
  client.exchangePublicToken(publicToken, function(err, exchangeRespone) {
    // Handle error, if present
    var accessToken = exchangeResponse.access_token;
  });
});

curl -X POST https://sandbox.plaid.com/sandbox/public_token/create \
-H 'Content-Type: application/json' \
-d '{
  "public_key": String,
  "institution_id": String,
  "initial_products": [String],
  "options": {
    "webhook": String
  }
}'

# Generate a public_token for a given institution ID and set of initial products
create_response = client.sandbox.sandbox_public_token.create(
  institution_id: SANDBOX_INSTITUTION,
  initial_products: ['transactions']
)
# The generated public_token can now be exchanged for an access_token
exchange_token_response = client.item.public_token.exchange(
  create_response.public_token
)

// Generate a public_token for a given institution ID and set of initial products
Response<SandboxPublicTokenCreateResponse> createResponse =
  client().service().sandboxPublicTokenCreate(
    new SandboxPublicTokenCreateRequest(INSTITUTION_ID, INITIAL_PRODUCTS)
  ).execute();
// The generated public_token can now be exchanged for an access_token
Response<ItemPublicTokenExchangeResponse> exchangeResponse =
  client().service().itemPublicTokenExchange(
    new ItemPublicTokenExchangeRequest(createResponse.body().getPublicToken())
  ).execute();

# Generate a public_token for a given institution ID and set of initial products
create_response =
  client.Sandbox.public_token.create(INSTITUTION_ID, ['transactions'])
# The generated public_token can now be exchanged for an access_token
exchange_response =
  client.Item.public_token.exchange(create_response['public_token'])
Create Sandbox Item response

> http code 200
{
  "public_token": String,
  "request_id": String
}

> http code 200
{
  "public_token": String,
  "request_id": String
}

> http code 200
{
  "public_token": String,
  "request_id": String
}

> http code 200
{
  "public_token": String,
  "request_id": String
}

> http code 200
{
  "public_token": String,
  "request_id": String
}

Managing Item states

An Item may transition into an error state in response to changes made by the user or financial institution. The most common scenarios are when a user changes their password or when the financial institution changes their multi-factor authentication flow. Plaid Link makes it easy to restore a user's Item to a good state by having them provide updated credentials and MFA information, if needed.

In the Sandbox, Items transition to an ITEM_LOGIN_REQUIRED error state automatically after 30 days. You can also simulate this event via an API request.

Simulating ITEM_LOGIN_REQUIRED errors

The /sandbox/item/reset_login endpoint allows you put an Item in an ITEM_LOGIN_REQUIRED error state. You can then use Plaid Link update mode to restore the Item to a good state.

An ITEM_LOGIN_REQUIRED webhook will be fired after a call to this endpoint, if one is associated with the Item.

Field Required?
client_id
String
Yes
secret
String
Yes
access_token
String
Yes

Note: This endpoint is only available in the Sandbox API environment.

Simulate Item error

POST /sandbox/item/reset_login
Sandbox reset Item login request

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

curl -X POST https://sandbox.plaid.com/sandbox/item/reset_login \
  -H 'Content-Type: application/json' \
  -d '{
    "client_id": String,
    "secret": String,
    "access_token": String
  }'

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

Response<ItemResetLoginResponse> response = client().service().itemResetLogin(
  new ItemResetLoginRequest(ACCESS_TOKEN)
).execute();

# 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)
Sandbox reset Item login response

http code 200
{
  "reset_login": true,
  "request_id": String
}

http code 200
{
  "reset_login": true,
  "request_id": String
}

http code 200
{
  "reset_login": true,
  "request_id": String
}

http code 200
{
  "reset_login": true,
  "request_id": String
}

http code 200
{
  "reset_login": true,
  "request_id": String
}