Beta docs

We've been working on a new version of our documentation. Try it out today.


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.

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
  • link_token: a short-lived token that can be configured for different Link flows and is used to initialize 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.

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, and secret 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

https://sandbox.plaid.com (Sandbox)
https://development.plaid.com (Development)
https://production.plaid.com (Production)

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/link/token/create
/item/public_token/exchange
Item management/accounts/get
/item/get
/item/webhook/update
/item/access_token/invalidate
/item/remove
Product accessSee product access endpoints
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
Product access endpoints
ProductEndpoints
Auth POST /auth/get
Transactions POST /transactions/get
Identity POST /identity/get
Balance POST /accounts/balance/get
Assets POST /assets/get
InvestmentsPOST /investments/holdings/get
POST /investments/transactions/get
Liabilities POST /liabilities/get
Payment Initiation (Europe)POST /payment_initiation/recipient/create
POST /payment_initiation/recipient/get
POST /payment_initiation/recipient/list
POST /payment_initiation/payment/create
POST /payment_initiation/payment/token/create
POST /payment_initiation/payment/get
POST /payment_initiation/payment/list

Versioning

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

Our client libraries make it easy to move between versions. You will either initialize the library with the version you wish to use (Python and Node) or use a specific release of the 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({
  clientID: PLAID_CLIENT_ID,
  secret: PLAID_SECRET,
  env: plaid.environments.sandbox,
  options: {
    version: '2019-05-29', // specify API version
  }
});


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

require 'plaid'

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

// Use builder to create a client
PlaidClient plaidClient = PlaidClient.newBuilder()
  .clientIdAndSecret(PLAID_CLIENT_ID, PLAID_SECRET)
  .sandboxBaseUrl()
  .build();
          

from plaid import Client

client = Client(
    client_id=PLAID_CLIENT_ID,
    secret=PLAID_SECRET,
    environment='sandbox',
    api_version='2019-05-29'  # Specify API version
)

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 identifiers

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.

Plaid tokens - public_token, access_token, link_token, or asset_report_token

Plaid tokens are in the format [type]-[environment]-[uuid].

The type may be public, access, link, or asset-report. Link is initialized with a link_token which allows you to create Items. All successful Item creations will return a public_token which should be exchanged for a persistent access_token or asset_report_token depending upon the product.

The environment may be sandbox, development, or production ; a token will only ever be valid within the environment it was created.

The UUID is a 32 character hexadecimal string in the pattern of 8-4-4-4-12 characters, and conforms to the RFC 4122 standard.

"public_token": "public-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d" "access_token": "access-sandbox-5cd6e1b1-1b5b-459d-9284-366e2da89755" "link_token": "link-sandbox-048efb96-09c3-421e-aa88-af2b902c476b" "asset_report_token": "assets-sandbox-6f12f5bb-22dd-4855-b918-f47ec439198a"
item_id

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

"item_id": "Jv785paMV8hRGWNBRjbjUybw8N9B3yTBDdkwV"
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.

"account_id": "yL8je73GrjTZogRqZLrLHLaX3Kb8a1s5z6Jlg"
transaction_id

Included in successful responses for Plaid’s Transactions product.

"transaction_id": "ZXmN54gvBNIJq1aPJrGrFjGg8VJB36IzeWayW"

Status

We provide comprehensive status information about the health of our API, supported institutions, and Items to ensure you have the context you need to debug issues and better serve your users.

System status

Available at status.plaid.com, Plaid system status reports uptime and incidents for our three API environments: Sandbox, Development, and Production.

Institution and Item status

Plaid provides access to thousands of financial institutions. The overall health of these connections as well as individual Items can vary based on a variety of factors. Institution and Item status information is accessible via the Dashboard and the API, giving you the flexibility to use the tools that best fit your team's workflows.

In the Dashboard

Visit Status in the Dashboard to find and inspect the health of institutions and your Items. Look up an institution using its name or institution_id and look up an Item using its item_id or access_token.

Via the API

To programmatically receive status information to support internal tools and analytics infrastructure, see institution status and Item status.

Test out our new Link docs

We've been working on a new version of our documentation. Try it out today to get started building with Link.

BETAVisit beta docs

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://cdn.plaid.com/link/v2/stable/link-initialize.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/jquery/2.2.3/jquery.min.js"></script>
<script type="text/javascript">
(async function($) {
  const fetchLinkToken = async () => {
    const response = await fetch('/create_link_token', { method: 'POST' });
    const responseJSON = await response.json();
    return responseJSON.link_token;
  };

  const configs = {
    // Required, fetch a link token from your server and pass it
    // back to your app to initialize Link.
    token: await fetchLinkToken(),
    onLoad: function() {
      // Optional, called when Link loads
    },
    onSuccess: async 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.
      await fetch('/get_access_token', {
        method: 'POST',
        body: JSON.stringify({ public_token: public_token }),
      });
    },
    onExit: async function(err, metadata) {
      // The user exited the Link flow.
      if (err != null) {
        // The user encountered a Plaid API error prior to exiting.
        if (err.error_code === 'INVALID_LINK_TOKEN') {
          // The link_token expired or the user entered too many
          // invalid credentials. We want to destroy the old iframe
          // and reinitialize Plaid Link with a new link_token.
          handler.destroy();
          handler = Plaid.create({
            ...configs,
            token: await fetchLinkToken(),
          });
        }
      }
      // 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",
      // }
    }
  };

  let handler = Plaid.create(configs);

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

<button id="link-button">Link Account</button>
<script src="https://cdn.plaid.com/link/v2/stable/link-initialize.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/jquery/2.2.3/jquery.min.js"></script>
<script type="text/javascript">
(async function($) {
  const fetchLinkToken = async () => {
    const response = await fetch('/create_link_token', { method: 'POST' });
    const responseJSON = await response.json();
    return responseJSON.link_token;
  };

  const configs = {
    // Required, fetch a link token from your server and pass it
    // back to your app to initialize Link.
    token: await fetchLinkToken(),
    onLoad: function() {
      // Optional, called when Link loads
    },
    onSuccess: async 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.
      await fetch('/get_access_token', {
        method: 'POST',
        body: JSON.stringify({ public_token: public_token }),
      });
    },
    onExit: async function(err, metadata) {
      // The user exited the Link flow.
      if (err != null) {
        // The user encountered a Plaid API error prior to exiting.
        if (err.error_code === 'INVALID_LINK_TOKEN') {
          // The link_token expired or the user entered too many
          // invalid credentials. We want to destroy the old iframe
          // and reinitialize Plaid Link with a new link_token.
          handler.destroy();
          handler = Plaid.create({
            ...configs,
            token: await fetchLinkToken(),
          });
        }
      }
      // 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",
      // }
    }
  };

  let handler = Plaid.create(configs);

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

<button id="link-button">Link Account</button>
<script src="https://cdn.plaid.com/link/v2/stable/link-initialize.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/jquery/2.2.3/jquery.min.js"></script>
<script type="text/javascript">
(async function($) {
  const fetchLinkToken = async () => {
    const response = await fetch('/create_link_token', { method: 'POST' });
    const responseJSON = await response.json();
    return responseJSON.link_token;
  };

  const configs = {
    // Required, fetch a link token from your server and pass it
    // back to your app to initialize Link.
    token: await fetchLinkToken(),
    onLoad: function() {
      // Optional, called when Link loads
    },
    onSuccess: async 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.
      await fetch('/get_access_token', {
        method: 'POST',
        body: JSON.stringify({ public_token: public_token }),
      });
    },
    onExit: async function(err, metadata) {
      // The user exited the Link flow.
      if (err != null) {
        // The user encountered a Plaid API error prior to exiting.
        if (err.error_code === 'INVALID_LINK_TOKEN') {
          // The link_token expired or the user entered too many
          // invalid credentials. We want to destroy the old iframe
          // and reinitialize Plaid Link with a new link_token.
          handler.destroy();
          handler = Plaid.create({
            ...configs,
            token: await fetchLinkToken(),
          });
        }
      }
      // 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",
      // }
    }
  };

  let handler = Plaid.create(configs);

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

<button id="link-button">Link Account</button>
<script src="https://cdn.plaid.com/link/v2/stable/link-initialize.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/jquery/2.2.3/jquery.min.js"></script>
<script type="text/javascript">
(async function($) {
  const fetchLinkToken = async () => {
    const response = await fetch('/create_link_token', { method: 'POST' });
    const responseJSON = await response.json();
    return responseJSON.link_token;
  };

  const configs = {
    // Required, fetch a link token from your server and pass it
    // back to your app to initialize Link.
    token: await fetchLinkToken(),
    onLoad: function() {
      // Optional, called when Link loads
    },
    onSuccess: async 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.
      await fetch('/get_access_token', {
        method: 'POST',
        body: JSON.stringify({ public_token: public_token }),
      });
    },
    onExit: async function(err, metadata) {
      // The user exited the Link flow.
      if (err != null) {
        // The user encountered a Plaid API error prior to exiting.
        if (err.error_code === 'INVALID_LINK_TOKEN') {
          // The link_token expired or the user entered too many
          // invalid credentials. We want to destroy the old iframe
          // and reinitialize Plaid Link with a new link_token.
          handler.destroy();
          handler = Plaid.create({
            ...configs,
            token: await fetchLinkToken(),
          });
        }
      }
      // 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",
      // }
    }
  };

  let handler = Plaid.create(configs);

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

<button id="link-button">Link Account</button>
<script src="https://cdn.plaid.com/link/v2/stable/link-initialize.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/jquery/2.2.3/jquery.min.js"></script>
<script type="text/javascript">
(async function($) {
  const fetchLinkToken = async () => {
    const response = await fetch('/create_link_token', { method: 'POST' });
    const responseJSON = await response.json();
    return responseJSON.link_token;
  };

  const configs = {
    // Required, fetch a link token from your server and pass it
    // back to your app to initialize Link.
    token: await fetchLinkToken(),
    onLoad: function() {
      // Optional, called when Link loads
    },
    onSuccess: async 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.
      await fetch('/get_access_token', {
        method: 'POST',
        body: JSON.stringify({ public_token: public_token }),
      });
    },
    onExit: async function(err, metadata) {
      // The user exited the Link flow.
      if (err != null) {
        // The user encountered a Plaid API error prior to exiting.
        if (err.error_code === 'INVALID_LINK_TOKEN') {
          // The link_token expired or the user entered too many
          // invalid credentials. We want to destroy the old iframe
          // and reinitialize Plaid Link with a new link_token.
          handler.destroy();
          handler = Plaid.create({
            ...configs,
            token: await fetchLinkToken(),
          });
        }
      }
      // 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",
      // }
    }
  };

  let handler = Plaid.create(configs);

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

npm install express body-parser plaid
node server.js
          

gem install sinatra plaid
ruby server.rb
          

<dependency>
  <groupId>com.plaid</groupId>
  <artifactId>plaid-java</artifactId>
  <version>{...}</version>
  // e.g.: <version>5.1.0</version>
  // Source the latest plaid-java version from
  // https://github.com/plaid/plaid-java/releases
</dependency>
          

npm install express body-parser plaid
node server.js
          

pip install plaid-python flask
python server.py
Server-side Link handler

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.
let ACCESS_TOKEN = null;
let ITEM_ID = null;

const client = new plaid.Client({
  clientID: 'PLAID_CLIENT_ID',
  secret: 'PLAID_SECRET',
  env: plaid.environments.sandbox
});

const app = express();

// Create a link_token to initialize Link
app.post('/create_link_token', async function(request, response, next) {
  // Grab the client_user_id by searching for the current user in your database
  const user = await User.find(...);
  const clientUserId = user.id;

  // Create the link_token with all of your configurations
  client.createLinkToken({
    user: {
      client_user_id: clientUserId,
    },
    client_name: 'My App',
    products: ['transactions'],
    country_codes: ['US'],
    language: 'en',
    webhook: 'https://sample.webhook.com',
  }, function(error, linkTokenResponse) {
    // Pass the result to your client-side app to initialize Link
    response.json({ link_token: linkTokenResponse.link_token });
  });
});

// Accept the public_token sent from Link
app.post('/get_access_token', function(request, response, next) {
  const public_token = request.body.public_token;
  client.exchangePublicToken(public_token, function(error, response) {
    if (error != null) {
      console.log('Could not exchange public_token!' + '\n' + error);
      return response.json({error: msg});
    }

    // Store the access_token and item_id in your database
    ACCESS_TOKEN = response.access_token;
    ITEM_ID = response.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')

access_token = nil
item_id = nil

post '/create_link_token' do
  # Grab the client_user_id by searching for the current user in your database
  current_user = User.find(...)
  client_user_id = current_user.id

  # Create the link_token with all of your configurations
  link_token_response = client.link_token.create(
    user: {
      client_user_id: client_user_id
    },
    client_name: 'My App',
    products: ['transactions'],
    country_codes: ['US'],
    language: 'en',
    webhook: 'https://sample.webhook.com',
  )

  # Pass the result to your client-side app to initialize Link
  content_type :json
  link_token_response.to_json
end

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

  # Store the access_token and item_id in your database
  access_token = exchange_token_response['access_token']
  item_id = exchange_token_response['item_id']

  content_type :json
  exchange_token_response.to_json
end
          

import java.net.*;
import java.io.*;
import com.sun.net.httpserver.*;

import com.plaid.client;
import com.plaid.client.request.ItemPublicTokenExchangeRequest;
import com.plaid.client.response.ItemPublicTokenExchangeResponse;
import com.plaid.client.request.LinkTokenCreateRequest;
import com.plaid.client.request.LinkTokenCreateResponse;


public class PlaidExample {
  private static final String CLIENT_ID = "PLAID_CLIENT_ID";
  private static final String SECRET = "PLAID_SECRET";
  private static final PlaidClient client = PlaidClient.newBuilder()
    .clientIdAndSecret(CLIENT_ID, SECRET)
    .sandboxBaseUrl() // sandbox Plaid environment
    .logLevel(HttpLoggingInterceptor.Level.BODY)
    .build();

  public static void main(String[] args) {
    HttpServer server = HttpServer.create(
      new InetSocketAddress("localhost", 8000), 0);
    server.createContext("/create_link_token", new CreateLinkToken());
    server.createContext("/get_access_token", new GetAccessToken());
    hs.setExecutor(null);
    server.start();
  }

  static class CreateLinkToken implements HttpHandler {
    public void handle(HttpExchange t) throws IOException {
      // Simplified psuedo-code for obtaining client_user_id
      User userFromDB = db.find(...);
      String clientUserId = userFromDB.id;

      // Create a link token for your specific link flow
      Response<LinkTokenCreateResponse> response =
        plaidClient
          .service()
          .linkTokenCreate(
            new LinkTokenCreateRequest(
              user,
              "My App",
              Collections.singletonList("transactions")
            )
            .withCountryCodes(Collections.singletonList("US"))
            .withLanguage("en")
            .withWebhook("https://sample.webhook.com")
          ).execute();

      // Pass the result to your client-side app to initialize Link
      return response.body();
    }
  }

  static class GetAccessToken implements HttpHandler {
    private String publicToken;
    private String accessToken;
    private String itemId;

    public void handle(HttpExchange t) throws IOException {
      // Simplified psuedo-code for obtaining public_token
      InputStream is = t.getRequestBody();
      publicToken = is.publicToken();

      // Exchange public_token for an access_token
      Response<ItemPublicTokenExchangeResponse> plaidResponse =
        plaidClient
          .service()
          .itemPublicTokenExchange(
            new ItemPublicTokenExchangeRequest(publicToken))
          .execute();

      // Store the access_token and item_id in your database
      accessToken = plaidResponse.body().getAccessToken();
      itemId      = plaidResponse.body().getItemId();
    }
  }
}
          

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',
                      'sandbox')

access_token = None
item_id = None

@app.route('/create_link_token')
def create_link_token():
  # Grab the client_user_id by searching for the current user in your database
  user = User.find(...)
  client_user_id = user.id

  # Create a link_token with all of your configurations
  response = client.LinkToken.create({
    'user': {
      'client_user_id': client_user_id,
    },
    'products': ["transactions"],
    'client_name': "My App",
    'country_codes': ['US'],
    'language': 'en',
    'webhook': 'https://sample.webhook.com',
  })

  # Pass the result to your client-side app to initialize Link
  print('link_token' +  response['link_token'])
  return jsonify(response)

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

    # Store the access_token and item_id in your database
    access_token = exchange_response['access_token']
    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 for the Link module.

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

ParameterDescription
token
required		Specify a link_token to launch Link. The link_token can be configured for different Link flows including the default flow, update mode, and payment_initiation.

Visit the /link/token/create endpoint for a complete list of configurations when generating a link_token.
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 to indicate that the user has reached 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.
receivedRedirectUri
optional		A receivedRedirectUri is required to supportOAuth authentication flows when re-launching Link on a mobile device and using one or more European country codes.
isWebview
optional		Set to true if launching Link within a WebView.
key
deprecated		As of July 23, 2020, the public_key is no longer used for new implementations of Link.

If your integration is still using a public_key, view our migration guide to upgrade to link_tokens. You can also view our maintenance guide to troubleshoot any public_key issues.

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:

ParameterDescription
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 2-4 alphanumeric characters of an account's official account number. Note that the mask may be non-unique between an Item's accounts, it may also not match the mask that the bank displays to the user. This field is nullable.
  • type: the account type
  • subtype: the account subtype
When all Auth features are enabled, verification_status is also present with one of the possible values:
  • null: the Item was added through Instant Match or Instant Auth
  • pending_automatic_verification: an Item is pending automated microdeposit verfication
  • pending_manual_verification: an Item is pending manual microdeposit verification
  • manually_verified: an Item was successfully manually verified
account
[Object]		The account object is not null in the onSuccess callback when your users connect a specific bank account via the Select Account pane in Link. You can enable this behavior in the Plaid Dashboard or by integrating with all Auth features.

Note: If Select Account is enabled for multiple accounts, account will contain only the first account. All accounts selected by the user will be present in the accounts object.
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,
      },
    });
  },
})
onSuccess metadata schema

{
  "link_session_id": String,
  "institution": {
    "name": String,
    "institution_id": String
  },
  "accounts": [
    {
      "id": String,
      "name": String,
      "mask": String,
      "type": String,
      "subtype": String,
      "verification_status": 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.

ParameterDescription
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:

StatusDescription
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

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
}
onExit 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.

OPEN events will be sent immediately upon Link’s opening, and remaining events will be sent by the time onSuccess or onExit is called. If you need the exact time when an event happened, please use the timestamp property.

ParameterDescription
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
EventDescription
CLOSE_OAUTH The user closed the third-party website or mobile app without completing the OAuth flow.
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.
FAIL_OAUTH The user encountered an error while completing the third-party's OAuth login flow.
HANDOFF The user has completed the Link flow and the onSuccess callback is fired.
OPEN The user has opened Link.
OPEN_MY_PLAID The user has opened my.plaid.com. This event is only sent when Link is initialized with assets as a product
OPEN_OAUTH The user has navigated to a third-party website or mobile app in order to complete the OAuth login flow.
SEARCH_INSTITUTION The user has searched for an institution.
SELECT_INSTITUTION The user selected an institution.
SUBMIT_CREDENTIALS The user has submitted credentials.
SUBMIT_MFA The user has submitted MFA.
TRANSITION_VIEW The TRANSITION_VIEW event indicates that the user has moved from one view to the next.
Metadata Reference
FieldDescription
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: SUBMIT_MFA and 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
ViewDisplayed when
CONNECTED The user has connected their account.
CONSENT We ask the user to consent to the privacy policy.
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.
NUMBERS The user is asked to insert their account and routing numbers.
RECAPTCHA The user was presented with a Google reCAPTCHA to verify they are human.
SELECT_ACCOUNT We ask the user to choose an account.
SELECT_INSTITUTION We ask the user to choose their institution.
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"
  "OPEN_MY_PLAID"
  "SEARCH_INSTITUTION"
  "SELECT_INSTITUTION"
  "TRANSITION_VIEW"
)
onEvent 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 Link

// 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:

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

destroy() function

The destroy function allows you to destroy the Link handler instance, properly removing any DOM artifacts that were created by it. Use destroy() when creating new replacement Link handler instances. This function will fail if called when Link is opened.

destroy() example

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

// Open Link
linkHandler.open()

// Exit
linkHandler.exit()

// Destroy Link
linkHandler.destroy()

// New link handler can be created cleanly
linkHandler = Plaid.create(...)


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

// Open Link
linkHandler.open()

// Exit
linkHandler.exit()

// Destroy Link
linkHandler.destroy()

// New link handler can be created cleanly
linkHandler = Plaid.create(...)


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

// Open Link
linkHandler.open()

// Exit
linkHandler.exit()

// Destroy Link
linkHandler.destroy()

// New link handler can be created cleanly
linkHandler = Plaid.create(...)


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

// Open Link
linkHandler.open()

// Exit
linkHandler.exit()

// Destroy Link
linkHandler.destroy()

// New link handler can be created cleanly
linkHandler = Plaid.create(...)


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

// Open Link
linkHandler.open()

// Exit
linkHandler.exit()

// Destroy Link
linkHandler.destroy()

// New link handler can be created cleanly
linkHandler = Plaid.create(...)

In order to initialize Link, you will need to create a link_token. A link_token can be configured for different Link flows depending on the fields provided during token creation. It is one-time use and has a short lived expiration. If the link_token is created with an existing access_token, it will have an expiry of 30 minutes. Otherwise, the link_token will expire after 4 hours. A link_token is considered invalid once it expires, has been used in a previous Link session, or has been associated with too many invalid logins.

If a link_token does get into an invalid state, Link will exit with an INVALID_LINK_TOKEN error code. By recognizing when this error occurs in the onExit callback, you can generate a fresh link_token for the next time your user opens Link.

ParameterDescription
client_id
String, required
secret
String, required
client_name
String, required		The app name displayed in Link.
language
String, required		Specify a Plaid-supported language to localize Link.

Supported languages:
  • English ( 'en' )
  • French ( 'fr' )
  • Spanish ( 'es' )
  • Dutch ( 'nl' )
country_codes
Array<String>, required		Specify an array of Plaid-supported country codes using the ISO-3166-1 alpha-2 country code standard. Note that if you initialize with a European country code, your users will see the European consent panel during the Link flow.

Supported country codes:
  • Canada ( 'CA' )
  • France ( 'FR' )
  • Ireland ( 'IE' )
  • Netherlands ( 'NL' )
  • Spain ( 'ES' )
  • United Kingdom ( 'GB' )
  • United States ( 'US' )
user
Object, required		An object containing information about your end user. See below for which fields are available.
products
Array<String>, optional		A list of Plaid product(s) you wish to use. Valid products are: transactions, auth, identity, assets, investments, liabilities, and payment_initiation. 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. If Link is launched with multiple country_codes, only products that you are enabled for in all countries will be used by Link.

Example: ['auth', 'transactions']
webhook
String, optional		Specify a webhook to associate with an Item. Plaid fires a webhook when the Item requires updated credentials, when new data is available, or when Auth numbers have been successfully verified.
link_customization_name
String, optional		Specify the name of a Link customization created in the Dashboard. The default customization is used if none is provided. Learn more
account_filters
Object, optional		Configures Link to return only accounts that are specified by these filters and only display institutions that support the specified subtypes. Must match the format:

{
  "<ACCOUNT_TYPE>": {
    "account_subtypes": ["<ACCOUNT_SUBTYPE>"]
  }
}
Learn more
access_token
String, optional		An access_token associates your link_token with an existing Item. If you provide an access_token with no products configured, you will create a Link token enabled for Update mode.
redirect_uri
String, optional		A URI indicating the destination where a user should be redirected to during specific Link flows in order to return control to your application. The redirect_uri is meant to be used only for specific Link flows such as OAuth authentication.

Note that the redirect_uri is not needed for Android integrations.
android_package_name
String, optional		Your Android application's package name. The android_package_name is required for Android integrations and is used to support OAuth authentication flows.
payment_initiation
Object, optional		An object containing configs specific to the payment_initiation product. If this config is provided, you should also include the payment_initiation product in the products array to enable the link_token for Payment Initiation

See below for payment_initiation fields.
KeyDescription
client_user_id
String, required		A unique identifier for each of your users. Do not use personally identifiable information such as an email or phone number.

Using `user.client_user_id` will allow for easier debugging in the Dashboard logs. You will be able to search for Link events that belong to one of your end users.
KeyDescription
payment_id
String, required		The payment_id returned from the /payment_initiation/payment/create request.
POST /link/token/create
Link token request
Link token response
Account Filters

The account_filters parameter is used to specify the account subtypes to be shown in Link. Only the specified subtypes will be shown. This filtering applies to both the Select Account view (if enabled) and the Institution Select view. Institutions that do not support the selected subtypes will be ommitted from Link.

account_filters takes the account types and subtypes you want to filter for. If you only want to filter by account type, pass “all” instead.

account_filters example

plaidClient.createLinkToken({
	...,
	account_filters: {
		depository: {
			account_subtypes: ['all'],
		},
		credit: {
			account_subtypes: ['credit card'],
		},
	},
	...,
}), function(err, apiResponse) {
  const linkToken = apiResponse.link_token;
});


curl -X POST https://sandbox.plaid.com/link/token/create \
  -H 'Content-Type: application/json' \
  -d '{
	...,
	"account_filters": {
		"depository": {
			"account_subtypes": ["all"],
		},
		"credit": {
			"account_subtypes": ["credit card"],
		},
	},
	...,
}'


response = client.link_token.create(
	...,
	account_filters: {
		depository: {
			account_subtypes: ['all'],
		},
		credit: {
			account_subtypes: ['credit card'],
		},
	},
	...,
)


plaidClient.createLinkToken({
	...,
	account_filters: {
		depository: {
			account_subtypes: ['all'],
		},
		credit: {
			account_subtypes: ['credit card'],
		},
	},
	...,
}), function(err, apiResponse) {
  const linkToken = apiResponse.link_token;
});
          

response = client.LinkToken.create({
	...,
	'account_filters': {
		'depository': {
			'account_subtypes': ['all'],
		},
		'credit': {
			'account_subtypes': ['credit card'],
		},
  },
	...,
})

Not all account type and product combinations are valid. The below table shows the valid account type and product combinations. As long as there is at least one valid account type and product combination, your Link configuration will be considered valid.

For example, if you initialized Link with the Auth product and filtered on credit account types, this would be considered an invalid combination. If you initialized Link with the Auth and Transactions products and filtered on credit account types, this would be considered a valid combination.

DepositoryCreditInvestmentLoanOther
AuthXX
TransactionsXXXX
IdentityXXX
AssetsXX
InvestmentsX
LiabilitiesXX

Note: while we distinguish among many subtypes, some subtypes have very few institutions that support them. Country filters can further narrow the set. It’s possible that a valid set of account type and product combination yields no default institutions. If you initialize Link with such a set of parameters, you will get a 500 error. If you plan on filtering for a narrow set of parameters, please ensure you test the outcome properly.

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.

FieldRequired?
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<ItemPublicTokenExchangeResponse> 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"
}

If you need your user to take action to restore or resolve an error associated with an Item, generate a link_token with the /link/token/create endpoint and configure it for update mode. To configure it for update mode, you will need to pass in the access_token that corresponds with the Item that you are trying to update. Note that you should not configure any initial products because update mode repairs existing Items, it does not create new ones. Once the link_token is created, you can then use it to initialize Link.

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

Refer to the full /link/token/create docs for a complete list of configurations.

POST /link/token/create
Create link_token request

// Create a link_token for use with Plaid Link's update mode
plaidClient.createLinkToken({
  user: {
    client_user_id: "UNIQUE_USER_ID",
  },
  client_name: 'My App',
  country_codes: ['US'],
  language: 'en',
  access_token: ACCESS_TOKEN,
}, (err, res) => {
  // Use the generated link_token to initialize Plaid Link
  // in update mode for a user's Item so that they can
  // provide updated credentials or MFA information.
  const link_token = res.link_token;
});


curl -X POST https://sandbox.plaid.com/link/token/create \
-H 'Content-Type: application/json' \
-d '{
  "client_id": "CLIENT_ID",
  "secret": "SECRET",
  "client_name": "My App",
  "user": { "client_user_id": "UNIQUE_USER_ID" },
  "country_codes": ["US"],
  "language": "en",
  "access_token": "ACCESS_TOKEN"
}'


# create a link_token for use with Plaid Link's update mode
response = client.link_token.create(
  user: {
    client_user_id: "UNIQUE_USER_ID"
  },
  client_name: 'My App',
  country_codes: ['US'],
  language: 'en',
  access_token: ACCESS_TOKEN,
)
# Use the generated link_token to initialize Plaid Link
# in update mode for a user's Item so that they can
# provide updated credentials or MFA information.
link_token = response['link_token']


LinkTokenCreateRequest.User user = new LinkTokenCreateRequest.User("UNIQUE_USER_ID")

// Create a link_token for use with Plaid Link's update mode
Response<LinkTokenCreateResponse> response =
  plaidClient.service()
    .linkTokenCreate(
      new LinkTokenCreateRequest(
        user,
        "My App",
        Collections.singletonList("transactions"),
        Collections.singletonList("US"),
        "en"
      )
      .withAccessToken(ACCESS_TOKEN)
    ).execute();

// Use the generated link_token to initialize Plaid Link
// in update mode for a user's Item so that they can
// provide updated credentials or MFA information.
return response.body();
          

# create a link_token for use with Plaid Link's update mode
response = client.LinkToken.create({
  'user': {
    'client_user_id': "UNIQUE_USER_ID",
  },
  'client_name': "My App",
  'country_codes': ['US'],
  'language': 'en',
  'access_token': ACCESS_TOKEN,
})
# Use the generated link_token to initialize Plaid Link
# in update mode for a user's Item so that they can
# provide updated credentials or MFA information.
link_token = response['link_token']
Create link_token response

http code 200
{
  "link_token": "link-sandbox-519a0aba-2724-4d64-b064-20105758aecb",
  "expiration": "2020-07-18T06:07:22Z",
  "request_id": "gR2y4oczAJR6vyC"
}


http code 200
{
  "link_token": "link-sandbox-519a0aba-2724-4d64-b064-20105758aecb",
  "expiration": "2020-07-18T06:07:22Z",
  "request_id": "gR2y4oczAJR6vyC"
}


http code 200
{
  "link_token": "link-sandbox-519a0aba-2724-4d64-b064-20105758aecb",
  "expiration": "2020-07-18T06:07:22Z",
  "request_id": "gR2y4oczAJR6vyC"
}


http code 200
{
  "link_token": "link-sandbox-519a0aba-2724-4d64-b064-20105758aecb",
  "expiration": "2020-07-18T06:07:22Z",
  "request_id": "gR2y4oczAJR6vyC"
}


http code 200
{
  "link_token": "link-sandbox-519a0aba-2724-4d64-b064-20105758aecb",
  "expiration": "2020-07-18T06:07:22Z",
  "request_id": "gR2y4oczAJR6vyC"
}

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

Initialize Link in update mode

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

If your integration is still using a public_token to open Link in update mode, view our migration guide to upgrade to link_tokens. You can also view our maintenance guide to troubleshoot any public_token issues.

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

https://cdn.plaid.com/link/v2/stable/link.html

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:

FieldDescription
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:

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

FieldDescription
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_55
  &institution_name=HSBC
  &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.

Example Link WebView initialization URL

https://cdn.plaid.com/link/v2/stable/link.html
  ?isWebview=true
  &token=GENERATED_LINK_TOKEN
Example Link update mode WebView initialization URL

https://cdn.plaid.com/link/v2/stable/link.html
  ?isWebview=true
  &token=GENERATED_LINK_TOKEN_FOR_UPDATE_MODE

OAuth requirements

Note: The following section is only relevant if you are enabled for any OAuth institutions e.g. when initializing Link with one or more European country codes.

Some institutions use an OAuth authentication flow, in which Plaid Link redirects the end user to their bank's website or mobile app to authenticate. If you are enabled for any OAuth institutions, your integration will likely require changes in order to support these OAuth authentication flows.

Integration typeChanges required?
Desktop web browserNo
Mobile web browserYes
WebViewYes
Android SDKNo
iOS SDKYes
React Native for AndroidNo
React Native for iOSYes
Mobile web browser & WebView

You will need to launch Link twice, once before and once after the OAuth redirect. The first time, set the token parameter to a link_token that has been configured by calling /link/token/create with a redirect_uri. After the user completes the OAuth flow, the redirect URI will be called in order to return control to your application. Finally, re-initialize Link with two configuration parameters, the token from the original Link initialization and the full receivedRedirectUri (including the query parameters and fragment identifiers).

Note that in mobile web browsers, if the end user has their bank’s mobile app installed, they will be redirected to the bank’s mobile app to authenticate, after which they will be redirected back to your web application in a new tab.

If your integration is still using the oauthRedirectUri and oauthNonce for mobile browser or webview OAuth flows, we recommend that you upgrade to the new OAuth flow using the docs above. You can also view our maintenance guide to troubleshoot any issues you have with the old flow.

iOS SDK & React Native for iOS

You will need to launch Link twice, once before and once after the OAuth redirect. The first time, set the token parameter to a link_token that has been configured by calling /link/token/create without a redirect_uri. Now initialize Link using the oauthRedirectUri, oauthNonce and token client-side. After the user completes the OAuth flow, the redirect URI will be called in order to return control to your application. Re-initialize Link using the token from the original Link initialization, oauthNonce, and oauthStateId, Please refer to the OAuth specific documentation for iOS SDK and React Native for iOS for details.

Allowed redirect URIs

To prevent open redirect attacks, your redirect_uri must be configured through the developer dashboard. For security, the redirect_uri cannot contain any query parameters since they are liable to be overwritten.

App links

For mobile app integrations, the redirect_uri must be registered as an app link to enable app-to-app authentication flows. You will need to configure an Android App Link or an Apple App Association File.



Browser & Platform support

Plaid strives to support all major browsers and latest platform versions. For the sake of security and providing the best experience to the majority of customers, we do not support browsers and mobile versions that are no longer receiving security updates and represent a small minority of traffic.

Desktop
BrowserLatest supported version
Google ChromechromeThe current and previous version of Chrome
(Windows, macOS, Linux)
Apple SafarisafariThe current and previous version of Safari
(macOS)
Mozilla FirefoxfirefoxThe current and previous version of Firefox
(Windows, macOS, Linux)
Microsoft Internet Explorerie10Internet Explorer 11 (Windows)
Plaid adheres to Microsoft's lifecycle policy
Microsoft Edgeie-edgeThe current version of Microsoft Edge
(Windows)
iOS
PlatformLatest supported version
iOS SDK (native)ios-native· iOS 9+
· Xcode 7 or greater
WebViewios-webview· WKWebView – iOS 10+, Xcode 8 or greater
· UIWebView – Not supported
Mobile Safariios-mobile-safariSafari on current and previous major version of iOS
Chromeios-mobile-chromeCurrent version of Chrome for iOS
Android
PlatformLatest supported version
Chrome WebViewandroid-webviewChrome WebView on Android 4.4+
Chrome Browserandroid-browserCurrent version of Chrome on Android 4.4+

Item product access

Auth

Test out our new Auth docs

We've been working on a new version of our documentation. Try it out today to get started building with Auth.

BETAVisit beta docs

Auth overview diagram

Plaid offers 4 authentication paths for a user to successfully verify their Auth numbers:

  • Instant Auth: User enters their credentials and are authenticated immediately
  • Instant Match: User enters their credentials, account number, and routing number. Plaid matches user input and authenticates immediately
  • Automated Microdeposits: User enters their credentials, account number, and routing number. Plaid makes 1 micro-deposit and automatically verifies the deposit within 1-2 business days
  • Same Day Microdeposits: User enters account and routing numbers. Plaid makes 2 Same Day ACH micro-deposits and user manually verifies the deposits within 1 business day.

The /auth/get endpoint then 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 when available.

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.

Enabling all Auth features

Your account manager can help you get access to all Auth features as only Instant Auth is enabled by default. Once you have access, you can enable Auth features through your link_token configuration.


plaidClient.createLinkToken({
  user: {
    client_user_id: UNIQUE_USER_ID,
  },
  client_name: 'My App',
  // Include auth to enable Instant Match or Automated Microdeposits.
  // For Same Day Microdeposits, auth must be the only product.
  products: ['auth'],
  // To enable auth flows beyond Instant Auth,
  // country_codes must be set to US.
  country_codes: ['US'],
  language: 'en',
  // We require a webhook for automated microdeposits, for
  // successful or unsuccessful verification.
  webhook: 'https://sample.webhook.com',
}, function(err, response) {
  // Pass this link_token to your app and use it
  // to initialize Link.
  const link_token = response.link_token
});
Verifying Same Day Microdeposits

Once Plaid has posted 2 micro deposits to a user’s institution, the user needs to come back into Link to verify the 2 amounts after 2-3 business days. This is done by creating a new link_token from the associated access_token for the given user, and passing it into the Link configuration under the keyname token. 


curl -X POST https://sandbox.plaid.com/link/token/create \
-H 'Content-Type: application/json' \
-d '{
  "client_id": "CLIENT_ID",
  "secret": "SECRET",
  "client_name": "My App",
  "user": { "client_user_id": "UNIQUE_USER_ID" },
  "country_codes": ["US"],
  "language": "en",
  "access_token": "access-sandbox-de3ce8ef-33f8-452c-a685-8671031fc0f6"
}'

Pass the created link_token into the Link configuration. This will identify the user’s verification state, and open Link directly to the verification view, prompting them to enter 2 amounts to verify.


var linkHandler = Plaid.create({
  ...,
  token: "NEW_LINK_TOKEN" // pass in generated link_token
  onSuccess: function(public_token, metadata) {
    metadata = {
      accounts: [{
        verification_status: 'manually_verified',
      }]
    }
  }
})
linkHandler.open()
Retrieve Auth request
POST /auth/get
FieldRequired?
client_id
String		yes
secret
String		yes
access_token
String		yes
options
Object		no

The following options are available:

FieldDescription
account_ids
[String]		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 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;
  }
  if (results.numbers.eft.length > 0) {
    // Handle EFT numbers (Canadian accounts)
    var eftNumbers = results.numbers.eft;
  }
  if (results.numbers.international.length > 0) {
    // Handle International numbers (Standard International accounts)
    var internationalNumbers = results.numbers.international;
  }
  if (results.numbers.bacs.length > 0) {
    // Handle BACS numbers (British accounts)
    var bacsNumbers = results.numbers.bacs;
  }
});


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]
end
if numbers[:eft].length > 0
  # Handle EFT numbers (Canadian accounts)
  eftNumbers = numbers[:eft]
end
if numbers[:international].length > 0
  # Handle International numbers (Standard International accounts)
  internationalNumbers = numbers[:international]
end
if numbers[:bacs].length > 0
  # Handle BACS numbers (British accounts)
  bacsNumbers = numbers[:bacs]
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()) { ... }
}
if (response.body().getNumbers().getEFT().length() > 0) {
  // Handle EFT numbers (Canadian accounts)
  for (AuthGetResponse.NumberEFT numberEFT : response.body().getNumbers().getEFT()) { ... }
}
if (response.body().getNumbers().getInternational().length() > 0) {
  // Handle International numbers (Standard International accounts)
  for (AuthGetResponse.NumberInternational numberInternational : response.body().getNumbers().getInternational()) { ... }
}
if (response.body().getNumbers().getBACS().length() > 0) {
  // Handle BACS numbers (British accounts))
  for (AuthGetResponse.NumberBACS numberBACS : response.body().getNumbers().getBACS()) { ... }
}


# 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']
if len(numbers['eft']) > 0:
    # Handle EFT numbers (Canadian accounts)
    eftNumbers = numbers['eft']
if len(numbers['international']) > 0:
    # Handle International numbers (Standard International accounts)
    internationalNumbers = numbers['international']
if len(numbers['bacs']) > 0:
    # Handle BACS numbers (British accounts)
    bacsNumbers = numbers['bacs']
Retrieve Auth response

http code 200
{
  "accounts": [{
    "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
    "balances": {
      "available": 100,
      "current": 110,
      "limit": null,
      "iso_currency_code": "USD",
      "unofficial_currency_code": null,
    },
    "mask": "9606",
    "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":[{
      "account": "111122223333",
      "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
      "institution": "021",
      "branch": "01140"
    }],
    "international":[{
      "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
      "bic": "NWBKGB21"
      "iban": "GB29NWBK60161331926819",
    }],
    "bacs":[{
      "account": "31926819",
      "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
      "sort_code": "601613"
    }]
  }
  "item": {Object},
  "request_id": "m8MDnv9okwxFNBV"
}
ACH numbers schema
KeyDescription
account_id
String		The Plaid account ID associated with the account numbers.
account
String		The ACH account number for the account.
routing
String		The ACH routing number for the account.
wire_routing
String, nullable		The ACH wire routing number for the account, if available.
EFT numbers schema
KeyDescription
account_id
String		The Plaid account ID associated with the account numbers.
account
String		The EFT account number for the account.
institution
String		The EFT institution number for the account.
branch
String		The EFT branch number for the account.
International numbers schema
KeyDescription
account_id
String		The Plaid account ID associated with the account numbers.
iban
String		The International Bank Account Number (IBAN) for the account.
bic
String		The Bank Identifier Code (BIC) for the account.
BACS numbers schema
KeyDescription
account_id
String		The Plaid account ID associated with the account numbers.
account
String		The BACS account number for the account.
sort_code
String		The BACS sort code for the account.

Transactions

Test out our new Transactions docs

We've been working on a new version of our documentation. Try it out today to get started building with Transactions.

BETAVisit beta docs

The /transactions/get endpoint allows developers to receive user-authorized transaction data for credit, depository, and some loan-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. 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.

Retrieve Transactions request
POST /transactions/get
FieldRequired?Description
client_id
String		yes
secret
String		yes
access_token
String		yes
start_date
Date		yesDates should be formatted as YYYY-MM-DD
end_date
Date		yesDates should be formatted as YYYY-MM-DD
options
Object		noIf provided, must be non-null.

The following options are available:

FieldDefaultDescription
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		100The number of transactions to fetch, where 0 less than count less than or equal to 500.
offset
Number		0The 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",
    "authorized_date": "2017-01-27",
    "location": {
     "address": "300 Post St",
     "city": "San Francisco",
     "region": "CA",
     "postal_code": "94108",
     "country": "US",
     "lat": null,
     "lon": null,
     "store_number": "1235"
    },
    "merchant_name": "Apple",
    "name": "Apple Store",
    "payment_meta": Object,
    "payment_channel": "in store",
    "pending": false,
    "pending_transaction_id": null,
    "account_owner": null,
    "transaction_id": "lPNjeW1nR6CDn5okmGQ6hEpMo4lLNoSrzqDje",
    "transaction_code": null,
    "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",
    "authorized_date": "2017-01-28"
    "location": {
      "address": "262 W 15th St",
      "city": "New York",
      "region": "NY",
      "postal_code": "10011",
      "country": "US",
      "lat": 40.740352,
      "lon": -74.001761,
      "store_number": "455"
    },
    "merchant_name": "Golden Crepes",
    "name": "Golden Crepes",
    "payment_meta": Object,
    "payment_channel": "in store",
    "pending": false,
    "pending_transaction_id": null,
    "account_owner": null,
    "transaction_id": "4WPD9vV5A1cogJwyQ5kVFB3vPEmpXPS3qvjXQ",
    "transaction_code": null,
    "transaction_type": "place"
  }],
  "item": {Object},
  "total_transactions": Number,
  "request_id": "45QSn"
}
Transaction schema
KeyDescription
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. Please use the payment_channel field, payment_type will be deprecated in the future.
name
String		Description of the transaction.
merchant_name
String, nullable		Clean name of the merchant if applicable.
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. Always null if unofficial_currency_code is non-null.
unofficial_currency_code
String, nullable		The currency code associated with the transaction, if not recognized as an ISO code. For example, cryptocurrencies such as BTC. 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 ). Dates reflect the date posted by the bank and are not standardized to a timezone by Plaid.
authorized_date
String, nullable		The date that the transaction was authorized. 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 a transfer payment. The payment_meta key will always be an Object, but no payment_meta data elements are guaranteed. This object will be deprecated in the future.
payment_channel
String		The channel used to make a payment. Possible values are: online, in store, other. This field will replace the transaction_type field.
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_code
String, nullable		 adjustment: Bank adjustment.
atm: Cash deposit or withdrawal via an automated teller machine.
bank charge: Charge or fee levied by the institution.
bill payment: Payment of a bill.
cash: Cash deposit or withdrawal.
cashback: Cash withdrawal while making a debit card purchase.
cheque: Document ordering the payment of money to another person or organization.
direct debit: Automatic withdrawal of funds initiated by a third party at a regular interval.
interest: Interest earned or incurred.
purchase: Purchase made with a credit or debit card.
standing order: Payment instructed by the account holder to a third party at a regular interval.
transfer: Transfer of money between accounts.

Note: This field is only populated for European institutions. For institutions in the US and Canada, this field is set to null.
Transaction location schema
KeyDescription
address
String, nullable		The street address where the transaction occurred.
city
String, nullable		The city where the transaction occurred.
region
String, nullable		The region or state where the transaction occurred.
postal_code
String, nullable		The postal code where the transaction occurred.
country
String, nullable		The ISO 3166-1 alpha-2 country code where the transaction occurred.
lat
Number, nullable		The latitude where the transaction occurred.
lon
Number, nullable		The longitude where the transaction occurred.
store_number
Number, nullable		The merchant defined store number where the transaction occurred.
Transaction payment_meta schema
KeyDescription
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
String, nullable		For transfers, the party that is receiving the transaction.
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.

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

Transactions Refresh

Transactions Refresh is an optional paid feature for users of the Transactions product. It initiates an on-demand extraction to fetch the newest transactions for an item. If new transactions are discovered after calling /transactions/refresh, Plaid will fire a webhook. New transactions can be fetched by calling /transactions/get. Please reach out to your account manager for access and more information.

POST /transactions/refresh
FieldRequired?
client_id
String		yes
secret
String		yes
access_token
String		yes

If the extraction was successful, you’ll receive a response with a status code of 200 and a request_id. There are no new error types introduced by Transactions Refresh beyond what’s documented in the Errors section. Common errors include exceeding rate limits or credential errors.

Balance

Test out our new Balance docs

We've been working on a new version of our documentation. Try it out today to get started building with Balance.

BETAVisit beta docs

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.

Retrieve Balance request
POST /accounts/balance/get
FieldRequired?
client_id
String		yes
secret
String		yes
access_token
String		yes
options
Object		no

The following options are available:

FieldDefaultDescription
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 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"
}
Balances schema

See Balance object for fields.

Identity

Test out our new Identity docs

We've been working on a new version of our documentation. Try it out today to get started building with Identity.

BETAVisit beta docs

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.

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

// Pull Identity data for an Item
client.getIdentity(accessToken, (err, result) => {
  // Handle err
  const accounts = result.accounts;
  for (const account of accounts) {
    const identities = account.owners;
  }
});


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)
accounts = response[:accounts]
accounts.each do |account|
  identities = account[:owners]
end


// Pull Identity data for an Item
Response<IdentityGetResponse> response = client().service().identityGet(
  new IdentityGetRequest("ACCESS_TOKEN")
).execute();
List<IdentityGetResponse.AccountWithOwners> accounts = response.body().getAccounts();
for (IdentityGetResponse.AccountWithOwners account : accounts) {
  List<IdentityGetResponse.Identity> identities = account.getOwners();
}


# pull identity data for an item
response = client.Identity.get(access_token)
accounts = response['accounts']
for account in accounts:
    identities = account['owners']
Retrieve Identity response

http code 200
{
  "accounts": [
    {
      ...,
      "owners": [
        {
          "addresses": [
            {
              "data": {
                "city": "Malakoff",
                "region": "NY",
                "street": "2992 Cameron Road",
                "postal_code": "14236",
                "country": "US"
              },
              "primary": true
            },
            {
              "data": {
                "city": "San Matias",
                "region": "CA",
                "street": "2493 Leisure Lane",
                "postal_code": "93405-2255",
                "country": "US"
              },
              "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"
}
Identity schema
KeyDescription
names
[String]		A list of names associated with the Item's account(s).
phone_numbers
[Object]		A list of phone numbers associated with the Item's account(s).
emails
[Object]		A list of emails associated with the Item's account(s).
addresses
[Object]		A list of addresses associated with the Item's account(s).
Phone numbers schema
KeyDescription
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"
Emails schema
KeyDescription
data
String		The email address.
primary
Boolean		When true, identifies the email address as the primary email on an account.
type
String		The type of email account as described by the financial institution.

Example: "secondary"
Addresses schema
KeyDescription
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 schema
KeyDescription
city
String		The full city name
region
String		The region or state
Example: "NC"
street
String		The full street address
Example: "564 Main Street, APT 15"
postal_code
String		The postal code
country
String		The ISO 3166-1 alpha-2 country code

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 use the /asset_report/refresh endpoint to create a new Asset Report based on the old one, but updated with the most recent data available from the financial institution(s).

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
FieldDescription
client_id
String		Your client_id
secret
String		Your secret
access_tokens
[String]		An array of access tokens, one token for each Item to be included in the Asset Report.
days_requested
Number		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
Object, optional		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.

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

FieldD1C™Description
client_user_id
String		optionalAn identifier you determine and submit for the user
first_name
String		requiredThe user’s first name
middle_name
String		optionalThe user’s middle name
last_name
String		requiredThe user’s last name
ssn
String		requiredThe user’s social security number
Format: "ddd-dd-dddd"
phone_number
String		optionalThe user’s phone number
Format: “+{country_code}{area code and subscriber number}”
e.g. “+14155555555” (known as E.164 format)
email
String		optionalThe 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 overridden. 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:

Refresh Asset Report request

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. By default, an Asset Report includes transaction descriptions as returned by the bank, as opposed to parsed and categorized by Plaid.

You can also receive cleaned and categorized transactions, as well as additional insights like merchant name or location information. We call this an Asset Report with Insights. An Asset Report with Insights provides transaction category, location, and merchant information in addition to the transaction strings provided in a standard Asset Report. You can read more about our categories here.

To retrieve an Asset Report with Insights, call the /asset_report/get endpoint with include_insights set to true. Note that you will need to contact us to get access to this feature.

FieldDescription
client_id
String		Your client_id
secret
String		Your secret
asset_report_token
String		The Asset Report token from the /asset_report/create response
include_insights
Boolean, optional		 true if you would like to retrieve the Asset Report with Insights, false otherwise. This field defaults to false if omitted. Contact us to get access to this feature.
Retrieve JSON Report request

// ASSET_REPORT_TOKEN is the token from the createAssetReport response.
client.getAssetReport(ASSET_REPORT_TOKEN, false, (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,
   "include_insights": Boolean
 }'


# 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",
                      "region": "NY",
                      "street": "2992 Cameron Road",
                      "postal_code": "14236",
                      "country": "US"
                    },
                    "primary": true
                  },
                  {
                    "data": {
                      "city": "San Matias",
                      "region": "CA",
                      "street": "2493 Leisure Lane",
                      "postal_code": "93405-2255",
                      "country": "US"
                    },
                    "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 SF<strong>POOL</strong>",
                "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 SF<strong>POOL</strong>",
                "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",
                      "region": "NY",
                      "street": "2992 Cameron Road",
                      "postal_code": "14236",
                      "country": "US"
                    },
                    "primary": true
                  },
                  {
                    "data": {
                      "city": "San Matias",
                      "region": "CA",
                      "street": "2493 Leisure Lane",
                      "postal_code": "93405-2255",
                      "country": "US"
                    },
                    "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 <em>//",
                "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 </em>//",
                "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",
                      "region": "NY",
                      "street": "2992 Cameron Road",
                      "postal_code": "14236",
                      "country": "US"
                    },
                    "primary": true
                  },
                  {
                    "data": {
                      "city": "San Matias",
                      "region": "CA",
                      "street": "2493 Leisure Lane",
                      "postal_code": "93405-2255",
                      "country": "US"
                    },
                    "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",
                      "region": "NY",
                      "street": "2992 Cameron Road",
                      "postal_code": "14236",
                      "country": "US"
                    },
                    "primary": true
                  },
                  {
                    "data": {
                      "city": "San Matias",
                      "region": "CA",
                      "street": "2493 Leisure Lane",
                      "postal_code": "93405-2255",
                      "country": "US"
                    },
                    "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 SF<strong>POOL</strong>",
                "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 SF<strong>POOL</strong>",
                "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",
                      "region": "NY",
                      "street": "2992 Cameron Road",
                      "postal_code": "14236",
                      "country": "US"
                    },
                    "primary": true
                  },
                  {
                    "data": {
                      "city": "San Matias",
                      "region": "CA",
                      "street": "2493 Leisure Lane",
                      "postal_code": "93405-2255",
                      "country": "US"
                    },
                    "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 <em>//",
                "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 </em>//",
                "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",
                      "region": "NY",
                      "street": "2992 Cameron Road",
                      "postal_code": "14236",
                      "country": "US"
                    },
                    "primary": true
                  },
                  {
                    "data": {
                      "city": "San Matias",
                      "region": "CA",
                      "street": "2493 Leisure Lane",
                      "postal_code": "93405-2255",
                      "country": "US"
                    },
                    "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",
                      "region": "NY",
                      "street": "2992 Cameron Road",
                      "postal_code": "14236",
                      "country": "US"
                    },
                    "primary": true
                  },
                  {
                    "data": {
                      "city": "San Matias",
                      "region": "CA",
                      "street": "2493 Leisure Lane",
                      "postal_code": "93405-2255",
                      "country": "US"
                    },
                    "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 SF<strong>POOL</strong>",
                "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 SF<strong>POOL</strong>",
                "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",
                      "region": "NY",
                      "street": "2992 Cameron Road",
                      "postal_code": "14236",
                      "country": "US"
                    },
                    "primary": true
                  },
                  {
                    "data": {
                      "city": "San Matias",
                      "region": "CA",
                      "street": "2493 Leisure Lane",
                      "postal_code": "93405-2255",
                      "country": "US"
                    },
                    "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 <em>//",
                "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 </em>//",
                "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",
                      "region": "NY",
                      "street": "2992 Cameron Road",
                      "postal_code": "14236",
                      "country": "US"
                    },
                    "primary": true
                  },
                  {
                    "data": {
                      "city": "San Matias",
                      "region": "CA",
                      "street": "2493 Leisure Lane",
                      "postal_code": "93405-2255",
                      "country": "US"
                    },
                    "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",
                      "region": "NY",
                      "street": "2992 Cameron Road",
                      "postal_code": "14236",
                      "country": "US"
                    },
                    "primary": true
                  },
                  {
                    "data": {
                      "city": "San Matias",
                      "region": "CA",
                      "street": "2493 Leisure Lane",
                      "postal_code": "93405-2255",
                      "country": "US"
                    },
                    "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 SF<strong>POOL</strong>",
                "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 SF<strong>POOL</strong>",
                "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",
                      "region": "NY",
                      "street": "2992 Cameron Road",
                      "postal_code": "14236",
                      "country": "US"
                    },
                    "primary": true
                  },
                  {
                    "data": {
                      "city": "San Matias",
                      "region": "CA",
                      "street": "2493 Leisure Lane",
                      "postal_code": "93405-2255",
                      "country": "US"
                    },
                    "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 <em>//",
                "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 </em>//",
                "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",
                      "region": "NY",
                      "street": "2992 Cameron Road",
                      "postal_code": "14236",
                      "country": "US"
                    },
                    "primary": true
                  },
                  {
                    "data": {
                      "city": "San Matias",
                      "region": "CA",
                      "street": "2493 Leisure Lane",
                      "postal_code": "93405-2255",
                      "country": "US"
                    },
                    "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",
                      "region": "NY",
                      "street": "2992 Cameron Road",
                      "postal_code": "14236",
                      "country": "US"
                    },
                    "primary": true
                  },
                  {
                    "data": {
                      "city": "San Matias",
                      "region": "CA",
                      "street": "2493 Leisure Lane",
                      "postal_code": "93405-2255",
                      "country": "US"
                    },
                    "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 SF<strong>POOL</strong>",
                "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 SF<strong>POOL</strong>",
                "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",
                      "region": "NY",
                      "street": "2992 Cameron Road",
                      "postal_code": "14236",
                      "country": "US"
                    },
                    "primary": true
                  },
                  {
                    "data": {
                      "city": "San Matias",
                      "region": "CA",
                      "street": "2493 Leisure Lane",
                      "postal_code": "93405-2255",
                      "country": "US"
                    },
                    "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 <em>//",
                "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 </em>//",
                "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",
                      "region": "NY",
                      "street": "2992 Cameron Road",
                      "postal_code": "14236",
                      "country": "US"
                    },
                    "primary": true
                  },
                  {
                    "data": {
                      "city": "San Matias",
                      "region": "CA",
                      "street": "2493 Leisure Lane",
                      "postal_code": "93405-2255",
                      "country": "US"
                    },
                    "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).

FieldDescription
report
Object		The data comprising the Asset Report; see Report object below 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
[Object]		See the Warnings object
Report object
FieldDescription
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
Number		The duration of transaction history you requested
user
Object		Data submitted by you about the user whose Asset Report is being compiled; see User object for fields
items
[Object]		Data returned by Plaid about each of the Items included in the Asset Report; see Item object for fields
Item object
FieldDescription
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
[Object]		Data about each of the accounts open on the Item ; see Account object for fields
Account object
FieldDescription
account_id
String		Plaid’s unique identifier for the account
mask
String, nullable		The last 2-4 alphanumeric characters of an account's official account number. Note that the mask may be non-unique between an Item's accounts, it may also not match the mask that the bank displays to the user. This field is nullable.
name
String		The name of the account, either assigned by the user or by the financial institution itself
official_name
String, nullable		The official name of the account as given by the financial institution
type
String		See Account types
subtype
String		See Account subtypes
owners
[Object]		Data returned by the financial institution about the account owner or owners; see Owner object for fields
balances
Object		Data about the various balances on the account; see Balance object for fields.
historical_balances
[Object]		Calculated data about the historical balances on the account; see Historical balance object for fields
transactions
[Object]		Data about the transactions
days_available
Number		The duration of transaction history available for this Item, typically defined as the time since the date of the earliest transaction in that account
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.

FieldDescription
names
[String]		A list of names associated with the account by the financial institution
phone_numbers
[Object]		A list of phone numbers associated with the account by the financial institution; see Phone number object for fields
emails
[Object]		A list of emails associated with the account by the financial institution; see Email object for fields
addresses
[Object]		Data about the various addresses associated with the account by the financial institution; see Address object for fields
Phone number object
FieldDescription
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
FieldDescription
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
FieldDescription
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
KeyDescription
city
String		The full city name
region
String		The region or state
Example: "NC"
street
String		The full street address
Example: "564 Main Street, APT 15"
postal_code
String		The postal code
country
String		The ISO 3166-1 alpha-2 country code
Balance object
KeyDescription
current
Number		The total amount of funds in or owed by the account.
For credit-type accounts, a positive balance indicates the amount owed; a negative amount indicates the lender owing the account holder.
For loan-type accounts, the current balance is the principal remaining on the loan.
For investment-type accounts, the current balance is the total value of assets as presented by the institution.
available
Number, nullable		The amount of funds available to be withdrawn from the account, as determined by the financial institution.
For credit-type accounts, the available balance typically equals the limit less the current balance, less any pending outflows plus any pending inflows.
For depository-type accounts, the available balance typically equals the current balance less any pending outflows plus any pending inflows. For depository-type accounts, the available balance does not include the overdraft limit.
For investment-type accounts, the available balance is the total cash available to withdraw as presented by the institution.
Note that not all institutions calculate the available balance. In the event that available balance is unavailable, Plaid will return an available balance value of null.
limit
Number, nullable		For credit-type accounts, this represents the credit limit. For depository-type accounts, this represents the pre-arranged overdraft limit, which is common for current (checking) accounts in Europe. In North America, this field is typically only available for credit -type accounts.
iso_currency_code
String, nullable		The ISO currency code of the balance, Plaid supports all ISO 4217 currency codes. Always null if unofficial_currency_code is non-null.
unofficial_currency_code
String, nullable		The unofficial currency code associated with the balance, see unofficial currency codes. Always null if iso_currency_code is non-null.
Unofficial currency codes
ValueDescription
ADACardano
BATBasic Attention Token
BCHBitcoin Cash
BNBBinance Coin
BTCBitcoin
BTGBitcoin Gold
CNHChinese Yuan (offshore)
DASHDash
DOGEDogecoin
ETCEtherium Classic
ETHEthereum
GBXPence sterlin, i.e. British penny
LSKLisk
NEONeo
OMGOmiseGo
QTUMQtum
USDTTetherUS
XLMStellar Lumen
XMRMonero
XRPRipple
ZECZcash
ZRX0x
Historical balance object
FieldDescription
date
Date		The date of the calculated historical balance
current
Number		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 transaction

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 balance, Plaid supports all ISO 4217 currency codes. Always null if unofficial_currency_code is non-null.
unofficial_currency_code
String		The unofficial currency code associated with the balance, see unofficial currency codes. Always null if iso_currency_code is non-null.
Transaction object
FieldDescription
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
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, while credit card payments, direct deposits, and refunds are negative
iso_currency_code
String		The ISO currency code of the transaction, Plaid supports all ISO 4217 currency codes. Always null if unofficial_currency_code is non-null.
unofficial_currency_code
String, nullable		The unofficial currency code associated with the transaction, see unofficial currency codes. Always null if iso_currency_code is non-null.
account_owner
String, nullable		The name of the account owner. This field is not typically populated and only relevant when dealing with sub-accounts. This field only appears in an Asset Report with Insights.
category
[String], nullable		A hierarchical array of the categories to which this transaction belongs. See Categories. This field only appears in an Asset Report with Insights.
category_id
String, nullable		The ID of the category to which this transaction belongs. See Categories. This field only appears in an Asset Report with Insights.
date_transacted
String, nullable		The date of the transaction. This field will only exist if it is non-null. This field only appears in an Asset Report with Insights.
location
Object, nullable		Information about where the transaction occurred. The location key will always be an Object, but no location data elements are guaranteed. This field only appears in an Asset Report with Insights.
name
String, nullable		The merchant name or transaction description. This field only appears in an Asset Report with Insights.
payment_meta
Object, nullable		Information about where the transaction occurred. The payment_meta key will always be an Object, but no payment_meta data elements are guaranteed. This field only appears in an Asset Report with Insights.
pending_transaction_id
String, nullable		The ID of a posted transaction's associated pending transaction—where applicable. This field only appears in an Asset Report with Insights.
transaction_type
String, nullable		 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. This field only appears in an Asset Report with Insights.
Transaction location schema
KeyDescription
address
String, nullable		The street address where the transaction occurred.
city
String, nullable		The city where the transaction occurred.
region
String, nullable		The region or state where the transaction occurred.
postal_code
String, nullable		The postal code where the transaction occurred.
country
String, nullable		The ISO 3166-1 alpha-2 country 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 schema
KeyDescription
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
String, nullable		For transfers, the party that is receiving the transaction.
Warning object
FieldDescription
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
Object		The underlying cause of this warning. See Cause object
Cause object
FieldDescription
error
Object		The underlying error. See Error schema.
item_id
String		The item ID.

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.

Retrieve PDF Report request

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

Investments

Test out our new Investments docs

We've been working on a new version of our documentation. Try it out today to get started building with Investments.

BETAVisit beta docs

The /investments/holdings/get and /investments/transactions/get endpoints allow developers to retrieve user-authorized Holding, Security, and InvestmentTransactions data for a wide array of investment account and security types. Both Investments endpoints are only compatible with Items having Accounts of type investment.

Holdings represent the different types of securities that can be held in investment accounts and have quantity, value, cost basis, as well as other ownership details. Each security held in an account is represented by a corresponding Holding. For example, a brokerage account containing shares of the equity “AAPL” and mutual fund “VTSAX” would be represented with two holdings.

InvestmentTransactions represent the different types of activity in an investment account, including buying and selling securities, earning dividends, cash contributions, and more. Transactions are described by quantity, price, amount and other descriptive fields.

Securities are descriptive features of a security, including identifiers that reconcile assets across institutions and account types. Publicly traded securities are provided with the ISO-6166 ISIN identifier when possible. Private securities, alternatives, or asset types where no ISIN is available (e.g. cryptocurrencies, real estate, etc.) are normalized with an internally generated, unique identifier. In all cases, we will return the identifiers—typically a trading symbol—offered by the institution. Other Securities fields include security naming and pricing details.

Retrieve Holdings request

The /investments/holdings/get endpoint allows developers to receive user-authorized stock position data for investment-type Accounts. Holding data is standardized across financial institutions, and Holdings are linked to Securities which conform to the schema provided below.

Every /investments/holdings/get response will contain a list of Securities, providing definitions for all security_id references in the response.


POST /investments/holdings/get
FieldRequired?Description
client_id
String		yes
secret
String		yes
access_token
String		yes
options
Object		noIf provided, must be non-null.

The following options are available:

FieldDescription
account_ids
[String]		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 Investment Holdings request

// Pull Holdings for an Item
client.getHoldings(accessToken, (err, result) => {
  // Handle err
  const holdings = result.holdings;
  const securities = result.securities;
});


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


# Pull Holdings for an Item
response = @client.investments.holdings.get(@access_token)

# Handle Holdings response
holdings = response['holdings']

# Handle Securities response
securities = response['securities']


// Pull Holdings for an Item
Response<InvestmentsHoldingsGetResponse> response =
client().service().investmentsHoldingsGet(
  new InvestmentsHoldingsGetRequest(accessToken))
  .execute();

// Handle Holdings response
List<InvestmentsHoldingsGetResponse.Holding> holdings =
  response.body().getHoldings();

// Handle Securities response
List<InvestmentsHoldingsGetResponse.Security> securities =
  response.body().getSecurities();


# Pull Holdings for an Item
response = client.Holdings.get(access_token)

# Handle Holdings response
holdings = response['holdings']

# Handle Securities response
securities = response['securities']
Retrieve Investment Holdings response

http code 200

{
  "item": {...},
  "request_id": "...",
  "accounts": [...],
  "securities": [{
    "security_id": "8jJwoCrH3nXNsk5OMSGLAf3hjoAv7fkSAXb5K",
    "isin": "US31617H1023",
    "sedol": null,
    "cusip": "31617H102",
    "ticker_symbol": "SPAXX",
    "name": "Fidelity Government Money Market Fund",
    "is_cash_equivalent": true,
    "type": "money market",
    "close_price": 1.00,
    "close_price_as_of": "2018-12-20",
    "iso_currency_code": "USD",
    "unofficial_currency_code": null,
  },{
    "security_id": "pvVE25eHesoPtl46qGk0T98dodkAd6jNuAmeO",
    "isin": "US17275R1023",
    "sedol": null,
    "cusip": "17275R102",
    "ticker_symbol": "CSCO",
    "name": "CISCO SYSTEMS INC",
    "is_cash_equivalent": false,
    "type": "equity",
    "close_price": 42.438,
    "close_price_as_of": "2018-12-20",
    "iso_currency_code": "USD",
    "unofficial_currency_code": null,
  },{
    "security_id": "WuQDPY287v21GuokVScQTffuAEM2ppXiq4VwI",
    "isin": null,
    "sedol": null,
    "cusip": null,
    "institution_security_id": "bitcoin",
    "institution_id": "ins_18014",
    "ticker_symbol": "BTC",
    "name": "Bitcoin",
    "is_cash_equivalent": false,
    "type": "equity",
    "close_price": 6485.39,
    "close_price_as_of": "2018-12-20",
    "iso_currency_code": "USD",
    "unofficial_currency_code": null,
  },{
    "security_id": "xeAuh4GUzAYuGaqwhZE3Fspih2K4AMOvtHQve",
    "isin": "US46625H1005",
    "sedol": null,
    "cusip": "46625H100",
    "ticker_symbol": "JPM",
    "name": "JPMorgan Chase & Co",
    "is_cash_equivalent": false,
    "type": "equity",
    "close_price": 96.450,
    "close_price_as_of": "2018-12-20",
    "iso_currency_code": "USD",
    "unofficial_currency_code": null,
  }],
  "holdings": [{
    "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
    "security_id": "8jJwoCrH3nXNsk5OMSGLAf3hjoAv7fkSAXb5K",
    "institution_price": 1.00,
    "institution_price_as_of": "2018-12-20",
    "institution_value": 2107.07,
    "cost_basis": 2107.07,
    "quantity": 2107.07
    "iso_currency_code": "USD",
    "unofficial_currency_code": null,
  },{
    "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
    "security_id": "pvVE25eHesoPtl46qGk0T98dodkAd6jNuAmeO",
    "institution_price": 42.490,
    "institution_price_as_of": "2018-12-20",
    "institution_value": 6373.50,
    "cost_basis": 6247.73,
    "quantity": 150.00
    "iso_currency_code": "USD",
    "unofficial_currency_code": null,
  },{
    "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
    "security_id": "xeAuh4GUzAYuGaqwhZE3Fspih2K4AMOvtHQve",
    "institution_price": 96.450,
    "institution_price_as_of": "2018-12-20",
    "institution_value": 5015.40,
    "cost_basis": 3680.14,
    "quantity": 52.00
    "iso_currency_code": "USD",
    "unofficial_currency_code": null,
  },{
    "account_id": "QPO8Jo8vdDHMepg41PBwckXm4KdK1yUdmXOwK",
    "security_id": "WuQDPY287v21GuokVScQTffuAEM2ppXiq4VwI",
    "institution_price": 4005.38,
    "institution_price_as_of": "2018-12-20",
    "institution_value": 6481.51,
    "cost_basis": 6112.09,
    "quantity": 1.6182
    "iso_currency_code": "USD",
    "unofficial_currency_code": null,
  },
  ...]
}
Security schema
KeyDescription
security_id
String		A unique Plaid identifier for the holding.
isin
String, nullable		12-character ISIN, a globally unique securities identifier.
cusip
String, nullable		9-character CUSIP, an identifier assigned to North American securities.
sedol
String, nullable		7-character SEDOL, an identifier assigned to securities in the UK.
institution_security_id
String, nullable		An identifier that is meaningful within the institution’s own schema.
institution_id
String, nullable		If institution_security_id is present, this field indicates the Plaid institution_id of the institution referenced.
proxy_security_id
String, nullable		In certain cases, Plaid will provide the ID of another security whose performance resembles this security—typically when the original security has low volume, or when a private security can be modeled with a publicly traded security.
name
String, nullable		A descriptive name for the security, suitable for display.
ticker_symbol
String, nullable		The security’s trading symbol for publicly traded securities, and otherwise a short identifier if available.
is_cash_equivalent
boolean		Indicates that a security is a highly liquid asset, and can be treated as cash.
type
String		The security type of the holding. See Security Types
close_price
float, nullable		Price of the security at the close of the previous trading session. null for non-public securities.
close_price_as_of
string, nullable		Date for which close_price is accurate. Always null if close_price_as_of is null.
iso_currency_code
String, nullable		The ISO-4217 currency code of the price given. Always null if unofficial_currency_code is non-null.
unofficial_currency_code
String, nullable		The unofficial currency of the given price. Always null if iso_currency_code is non-null. This is present if the price is denominated in an unrecognized currency e.g. Bitcoin, rewards points.
Holding schema
KeyDescription
account_id
String		The Plaid Account ID associated with the holding.
security_id
String		The Plaid Security ID of the security associated with the holding.
institution_price
float		The last price given by the institution for this security.
institution_price_as_of
String, nullable		The date at which institution_price was current.
institution_value
float		The value of the holding, as stated by the institution.
cost_basis
float, nullable		The total cost of acquiring the holding.
quantity
float		The total quantity of the asset held, as reported by the financial institution.
iso_currency_code
String, nullable		The ISO-4217 currency code of the holding. Always null if unofficial_currency_code is non-null.
unofficial_currency_code
String, nullable		The unofficial currency of the holding. Always null if iso_currency_code is non-null. This is present if the price is denominated in an unrecognized currency e.g. Bitcoin, rewards points.
Security types

Security types classify assets held within an account. The table below displays the value returned from the Plaid API and the corresponding description and grouping of securities that have a similar structure in the marketplace.

TypeName & Description
cash Cash & Cash Equivalent
Cash, currency, and money market funds.
derivative Derivatives
Options, warrants, and other derivative instruments.
equity Equities
Domestic and foreign equities.
etf Exchange-Traded Funds
Multi-asset investment funds traded on exchanges.
fixed income Fixed Income
Bonds and CDs.
loan Loans
Loans and loan receivables.
mutual fund Mutual Funds
Open- and closed-end vehicles pooling funds of multiple investors.
other Other/Alternative
Any unknown or unclassified investment vehicle.
Retrieve Investment Transactions request

The /investments/transactions/get endpoint allows developers to retrieve user-authorized transaction data for investment accounts. Transaction data is standardized across financial institutions, and InvestmentTransactions are related to Securities, which are included in the response and conform to the Security schema.

Due to the potentially large number of InvestmentTransactions 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 InvestmentTransactions. 


POST /investments/transactions/get
FieldRequired?Description
client_id
String		yes
secret
String		yes
access_token
String		yes
start_date
Date		yesDates should be formatted as YYYY-MM-DD.
end_date
Date		yesDates should be formatted as YYYY-MM-DD.
options
Object		noIf provided, must be non-null.

The following options are available:

FieldDefaultDescription
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 less than count less than or equal to 500.
offset
Number		 0 The number of transactions to skip,
where offset >= 0.
Retrieve Investment Transactions request

client.getInvestmentTransactions(
  accessToken,
  '2019-03-01',
  '2019-04-30',
  { count: 250, offset: 0 },
  (err, result) => {
  // Handle err
  const investmentTransactions = result.investment_transactions;
});


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


# Pull investment transactions for a date range
response = @client.investments.transactions.get(@access_token,
                                                '2019-03-01',
                                                '2019-04-30')

# Manipulate the count and offset parameters to paginate
# transactions and retrieve all available data
response = @client.investments.transactions.get(@access_token,
                                                '2019-03-01',
                                                '2019-04-30',
                                                count: 250,
                                                offset: 0)

total = response['total_investment_transactions']


SimpleDateFormat simpleDateFormat =
  new SimpleDateFormat("yyyy-MM-dd");
startDate = simpleDateFormat.parse("2019-03-01");
endDate = simpleDateFormat.parse("2019-04-30");

// Pull transactions for a date range
Response<InvesmentTransactionsGetResponse> response = client().service().investmentsTransactionsGet(
  new InvestmentsTransactionsGetRequest(
    accessToken,
    startDate,
    endDate))
  .execute();

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

for (InvestmentsTransactionsGetResponse.InvestmentTransaction txn :
  response.body().getInvestmentTransactions()) { ... }


response = client.InvestmentTransactions.get(
    access_token,
    start_date='2019-03-01',
    end_date='2010-04-30')
investment_transactions = response['investment_transactions']

# Manipulate the count and offset parameters to paginate
# transactions and retrieve all available data
while len(investment_transactions) < response['total_investment_transactions']:
    response = client.InvestmentTransactions.get(
        access_token,
        start_date='2019-03-01',
        end_date='2019-04-30',
        offset=len(transactions))
    transactions.extend(response['transactions'])
Retrieve Investment Transactions response

http code 200

{
  "item": {...},
  "request_id": "...",
  "accounts": [...],
  "securities": [...],
  "investment_transactions": [
    {
      "investment_transaction_id": "VaYBeiw3H9AhAHw53vQYkmkn2s2qJOGcY9hhs",
      "account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D",
      "security_id": "8jJwoCrH3nXNsk5OMSGLAf3hjoAv7fkSAXb5K",
      "cancel_transaction_id": "yNLYVbYWyAuzVnOnV6aOh0Qz1nzOr3I0A1w5X",
      "date": "2018-10-18",
      "name": "Buy CSCO",
      "quantity": 12,
      "amount": 551.28,
      "price": 45.94,
      "fees": 5.95,
      "type": "buy",
      "iso_currency_code": "USD",
      "unofficial_currency_code": null,
    },
    ...
  ],
  "total_investment_transactions": 28
}
Investment Transaction schema
KeyDescription
investment_transaction_id
String		The ID of the Investment transaction, unique across all Plaid transactions.
account_id
String		The ID of the account against which this transaction posted.
security_id
String, nullable		The ID of the security to which this transaction is related.
date
Date		The ISO-8601 posting date for the transaction, or transacted date for pending transactions.
name
String		The Institution’s description of the transaction.
quantity
float		The Amount of the security involved in this transaction.
amount
float		The complete value of the transaction. Positive values when cash is debited, e.g. purchases of stock; negative values when cash is credited, e.g. sales of stock. Treatment remains the same for cash-only movements unassociated with securities.
price
float		The price of the security at which this transaction occurred.
fees
float, nullable		The combined value of all fees applied to this transaction.
type
String		See Investment Transaction Types.
subtype
String		See Investment Transaction Subtypes.
iso_currency_code
String, nullable		The ISO-4217 currency code of the transaction. Always null if unofficial_currency_code is non-null.
unofficial_currency_code
String, nullable		The unofficial currency of the transaction. Always null if iso_currency_code is non-null. This is present if the price is denominated in an unrecognized currency e.g. Bitcoin, rewards points.
cancel_transaction_id
String, nullable		Present only when the transaction type is cancel, and indicates the investment_transaction_id of the transaction which was cancelled.
Investment Transaction types

The type property encodes information that informs users how to treat an InvestmentTransaction. The definitions here explain how to interpret a transaction's effect on the value of an account.

TypeDescription
buy Activity that increases the quantity of a holding.
cancel Transaction cancels a previous transaction.
cash Activity which modifies the cash position.
fee Fees on the account, e.g. commission, bookkeeping, options-related.
sell Activity that decreases the quantity of a holding.
transfer Activity which modifies a position, not through buy/sell activity e.g. options exercise, portfolio transfer
Investment Transaction subtypes

The subtype property encodes information that informs users how to treat an InvestmentTransaction. The definitions here explain how to interpret a transaction's effect on outcomes like investment performance, tax impact, fee categorization etc.

SubtypeDescription
account fee Fees paid for account maintenance.
assignment Assignment of short option holding.
buy Purchase to open or increase a position.
buy to cover Purchase to close a short position.
contribution Inflow of assets into a tax-advantaged account.
deposit Inflow of cash into an account.
distribution Outflow of assets from a tax-advantaged account.
dividend Inflow of cash from a dividend.
dividend reinvestment Purchase using proceeds from a cash dividend.
exercise Exercise of an option or warrant contract.
expire Expiration of an option or warrant contract.
fund fee Fees paid for administration of a mutual fund or other pooled investment vehicle.
interest Inflow of cash from interest.
interest receivable Inflow of cash from interest receivable.
interest reinvestment Purchase using proceeds from a cash interest payment.
legal fee Fees paid for legal charges or services.
loan payment Inflow of cash related to payment on a loan.
long-term capital gain Long-term capital gain received as cash.
long-term capital gain reinvestment Purchase using long-term capital gain cash proceeds.
management fee Fees paid for investment management of a mutual fund or other pooled investment vehicle.
margin expense Fees paid for maintaining margin debt.
merger Stock exchanged at a pre-defined ratio as part of a merger between companies.
miscellaneous fee Fees associated with various account or holding actions.
non-qualified dividend Inflow of cash from a non-qualified dividend.
non-resident tax Taxes paid on behalf of the investor for non-residency in investment jurisdiction.
pending credit Pending inflow of cash.
pending debit Pending outflow of cash.
qualified dividend Inflow of cash from a qualified dividend.
rebalance Rebalancing transaction (buy or sell) with no net impact to value in the account.
return of principal Repayment of loan principal.
sell Sell to close or decrease an existing holding.
sell short Sell to open a short position.
short-term capital gain Short-term capital gain received as cash.
short-term capital gain reinvestment Purchase using short-term capital gain cash proceeds.
spin off Inflow of stock from spin-off transaction of an existing holding.
split Inflow of stock from a forward split of an existing holding.
stock distribution Inflow of stock from a distribution.
tax Taxes paid on behalf of the investor.
tax withheld Taxes withheld on behalf of the customer.
transfer Movement of assets into or out of an account.
transfer fee Fees incurred for transfer of a holding or account.
trust fee Fees related to adminstration of a trust account.
unqualified gain Unqualified capital gain received as cash.
withdrawal Outflow of cash from an account.

Liabilities

Test out our new Liabilities docs

We've been working on a new version of our documentation. Try it out today to get started building with Liabilities.

BETAVisit beta docs

The /liabilities/get endpoint returns various details about an Item with loan or credit accounts. The currently supported Account types are available here.

The types of information returned by Liabilities can include:

  • Balances: how much is owed and over what pay period
  • Payment timing: last payment date and next payment due date
  • Current loan terms: interest rate, maturity, limits
  • Account details: original loan amount, guarantor, and more

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

Creating Liabilities Items with Link

To access any Plaid product, including Liabilities, you need an Item .

Create new Items with Liabilities by initializing Link with the product parameter set to liabilities. This configuration will filter the queryable institutions to display those institutions currently supported for Liabilities, across all account types. Today, that means both student loan servicers and credit cards issuers.

Create Liabilities items

plaidClient.createLinkToken({
  user: {
    client_user_id: UNIQUE__USER_ID,
  },
  client_name: 'My App',
  products: ['liabilities'],
  country_codes: ['US'],
  language: 'en',
  ...
}, (err, res) => {
  // Send link_token to your app to initialize Link
  const link_token = res.link_token;
});

The table below shows all currently supported Account types and subtypes in Liabilities. For all possible Account types and subtypes, see here.

Supported Liabilities Account Types
Account typeSubtypes
creditcredit card, paypal
loanstudent
Updating Liabilities Items

Plaid regularly updates an Item’s liabilities data, typically on a daily basis. To retrieve the most up-to-date liabilities information available, make a call to the /liabilities/get endpoint.

Liabilities Payment History

If you are interested in retrieving payment history for a Liabilities item, you can use the /transactions/get endpoint.

Note: Transactions are returned per account number. For some of our student loan providers, multiple loans that share the same account_id can share a common history. Calling /transactions/get with an account_id that corresponds to multiple loans will return the same transaction history for all loans. This behavior applies only to the following institutions: Nelnet ( ins_116528), EdFinancial Services (ins_116304), Granite State (ins_116308), and Oklahoma Student Loan Authority (ins_116945 ).

Retrieve Liabilities Request

POST /liabilities/get
FieldRequired?Description
client_id
String		yes
secret
String		yes
access_token
String		yes
options
Object		noIf provided, must be non-null.

The following options are available:

FieldDefaultDescription
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 Liabilities request

// Retrieve Liabilities data for an Item
client.getLiabilities(accessToken, (err, result) => {
  // Handle err
  var liabilities = result.liabilities;
});


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


# retrieve Liabilities data for an item
response = client.liabilities.get(access_token)
liabilities = response[:liabilities]


// Retrieve Liabilities data for an Item
Response<LiabilitiesGetResponse> response =
  client().service().liabilitiesGet(new LiabilitiesGetRequest(ACCESS_TOKEN)).execute();
Liabilities liabilities = response.getLiabilities();
List<LiabilitiesStreams> liabilitiesStreams = liabilities.getLiabilitiesStreams();


# retrieve Liabilities data for an item
response = client.Liabilities.get(access_token)
liabilities = response['liabilities']
Retrieve Student Loans Response

To find the current account balance, check the balances field under the Account schema.

Retrieve student loans response

http code 200
{
  "accounts": [...],
  "item": {...},
  "liabilities": {
    "student": [
      {
        "account_id": "vokyE5Rn6vHKqDLRXEn5fne7LwbKPLIXGK98d",
        "account_number": "3735928559",
        "disbursement_dates": [
          "2017-05-20",
          "2017-06-20"
        ],
        "expected_payoff_date": "2030-04-21",
        "guarantor": "Gingham Guarantor",
        "interest_rate_percentage": 18.25,
        "is_overdue": false,
        "last_payment_amount": 420.10,
        "last_payment_date": "2019-03-15",
        "last_statement_balance": 2345.6,
        "last_statement_issue_date": "2019-03-01",
        "loan_name": "Direct Subsidized Stafford",
        "loan_status": {
          "end_date": "2019-09-24",
          "type": "repayment"
        },
        "minimum_payment_amount": 123.99,
        "next_payment_due_date": "2019-04-01",
        "origination_date": "2017-04-21",
        "origination_principal_amount": 12345.6,
        "outstanding_interest_amount": 1234.5,
        "payment_reference_number": "4277009102",
        "pslf_status": {
          "estimated_eligibility_date": "2021-01-01",
          "payments_made": 42,
          "payments_remaining": 78
        },
        "repayment_plan": {
          "description": "STANDARD REPAYMENT",
          "type": "standard"
        },
        "sequence_number": "1",
        "servicer_address": {
          "city": "San Matias",
          "country": "US",
          "postal_code": "93405-2255",
          "region": "CA",
          "street": "2493 Leisure Lane"
        },
        "ytd_interest_paid": 123.4,
        "ytd_principal_paid": 1234.5
      },
      ...
    ]
  }
      "request_id": "9GMVig"
}
Student Loan liability schema
KeyDescription
account_id
String, nullable		The ID of the account that this liability belongs to.
account_number
String, nullable		The account number of the loan.
disbursement_dates
[Date], nullable		The dates on which loaned funds were disbursed or will be disbursed. These are often in the past. Dates are returned in an ISO 8601 format (YYYY-MM-DD).
expected_payoff_date
Date, nullable		The date when the student loan is expected to be paid off. Availability for this field is limited.
guarantor
String, nullable		The guarantor of the student loan.
interest_rate_percentage
Float		The interest rate on the loan as a percentage.
is_overdue
Boolean, nullable		true if a payment is currently overdue. Availability for this field is limited.
last_payment_amount
Number, nullable		The amount of the last payment.
last_payment_date
Date, nullable		The date of the last payment.
last_statement_balance
Float, nullable		The outstanding balance on the last statement. This field could also be interpreted as the next payment due. Availability for this field is limited.
last_statement_issue_date
Date, nullable		The date of the last statement.
loan_name
String, nullable		The type of loan, e.g., "Consolidation Loans".
loan_status
Object		The status of the loan. See Student Loan Status schema below.
minimum_payment_amount
Float, nullable		The minimum payment due for the next billing cycle. There are some exceptions:
  • Some institutions require a minimum payment across all loans associated with an account number. Our API presents that same minimum payment amount on each loan. The institutions that do this are: Great Lakes ( ins_116861), Firstmark (ins_116295), Nelnet (ins_116528), EdFinancial Services (ins_116304), Granite State (ins_116308), and Oklahoma Student Loan Authority (ins_116945).
  • Firstmark (ins_116295 ) will display as $0 if there is an autopay program in effect.
next_payment_due_date
Date, nullable		The due date for the next payment. The due date is null if a payment is not expected. A payment is not expected if loan_status.type is deferment, in_school, consolidated, paid in full, or transferred.
origination_date
Date, nullable		The date on which the loan was initially lent.
origination_principal_amount
Float, nullable		The original principal balance of the loan.
outstanding_interest_amount
Float, nullable		The total dollar amount of the accrued interest balance. For Sallie Mae ( ins_116944), this amount is included in the current balance of the loan, so this field will return as null.
payment_reference_number
String, nullable		The relevant account number that should be used to reference this loan for payments. In the majority of cases, payment_reference_number will match account_number, but in some institutions like Great Lakes (ins_116861 ) it will be different.
pslf_status
Object		Information about the student's eligibility in the Public Service Loan Forgiveness program. This is only returned if the institution is Fedloan ( ins_116527 ). See PSLF Status schema below.
repayment_plan
Object		The type of repayment plan. See Student Repayment Plan schema below.
sequence_number
String, nullable		The sequence number of the student loan. Heartland ECSI ( ins_116948 ) does not make this field available.
servicer_address
Object		The address of the student loan servicer. See Servicer Address schema below.
ytd_interest_paid
Float, nullable		The year to date (YTD) interest paid. Availability for this field is limited.
ytd_principal_paid
Float, nullable		The year to date (YTD) principal paid. Availability for this field is limited.
Student Loan Status schema
KeyDescription
end_date
Date, nullable		The date until which the loan will be in its current status.
type
String, nullable		Enumerated response from the following options: "cancelled", "charged off", "claim", "consolidated", "deferment", "delinquent", "discharged", "extension", "forbearance", "in grace", "in military", "in school", "not fully disbursed", "other", "paid in full", "refunded", "repayment", or "transferred".
Student Repayment Plan schema
KeyDescription
description
String, nullable		This field will return the description of the repayment plan as provided by the servicer.
type
String, nullable		Enumerated response from the following options: "extended graduated", "extended standard", "graduated", "income-contingent repayment", "income-based repayment", "interest only", "other", "pay as you earn", "revised pay as you earn", or "standard".
PSLF Status schema
KeyDescription
estimated_eligibility_date
String, nullable		The estimated date borrower will have completed 120 qualifying monthly payments. Returned in ISO 8601 format (YYYY-MM-DD).
payments_made
Number, nullable		The number of qualifying payments that have been made.
payments_remaining
Number, nullable		The number of qualifying payments that are remaining.
Servicer Address schema
KeyDescription
city
String, nullable		The full city name.
country
String, nullable		The ISO 3166-1 alpha-2 country code
postal_code
String, nullable		The five or nine digit postal code.
region
String, nullable		The region or state
Example: "NC"
street
String, nullable		The full street address Example: "564 Main Street, APT 15"
Retrieve Credit Card Response
Retrieve credit card response

http code 200
{
  "accounts": [...],
  "item": {...},
  "liabilities": {
    "credit": [
      {
        "account_id": "LgDOJbZz7pFKpaPNgRpZU57zY395q1I0Lxpew",
        "aprs": [
          {
            "apr_percentage": 23.99,
            "apr_type": "purchase_apr",
            "balance_subject_to_apr": 2345.6,
            "interest_charge_amount": 27.01
          }
        ],
        "is_overdue": false,
        "last_payment_amount": 420,
        "last_payment_date": "2019-03-15",
        "last_statement_balance": 2345.6,
        "last_statement_issue_date": "2019-03-01",
        "minimum_payment_amount": 123,
        "next_payment_due_date": "2019-04-01",
      }
    ]
  }
    "request_id": "9GMVig"
}
Credit card liability schema
KeyDescription
account_id
String, nullable		The ID of the account that this liability belongs to.
aprs
Object		See the APR object schema.
is_overdue
Boolean, nullable		true if a payment is currently overdue. Availability for this field is limited.
last_payment_amount
Number, nullable		The amount of the last payment.
last_payment_date
Date, nullable		The date of the last payment.
last_statement_balance
Float, nullable		The outstanding balance on the last statement. Availability for this field is limited.
last_statement_issue_date
Date, nullable		The date of the last statement.
minimum_payment_amount
Float, nullable		The minimum payment due for the next billing cycle.
next_payment_due_date
Date, nullable		The due date for the next payment. The due date is null if a payment is not expected.
APR schema
KeyDescription
apr_percentage
Number		Annual Percentage Rate applied.
apr_type
String		Enumerated response from the following options: “balance_transfer_apr”, “cash_apr”, “purchase_apr”, or “special”.
balance_subject_to_apr
Number, nullable		Amount of money that is subjected to the APR if a balance was carried beyond payment due date. How it is calculated can vary by card issuer. It is often calculated as an average daily balance.
interest_charge_amount
Number, nullable		Amount of money charged due to interest from last statement.

Payment Initiation (Europe)

Test out our new Payment Initiation docs

We've been working on a new version of our documentation. Try it out today to get started building with Payment Initiation.

BETAVisit beta docs

The Payment Initiation API enables payment transfers within your app. Right now, the API only supports payments originating from UK bank accounts but we are working to support payment initiation from other geographies in the near future. Each time a client wants to receive a payment, the end user must authorize the payment in Link before the payment can be initiated.

Note: The revised EU Directive on Payment Services ("PSD2") regulations require strong customer authentication ("SCA") for each payment order.

Single Immediate Payments

Plaid supports both domestic single immediate payments denominated in pound sterling (typically via the Faster Payments network, although this is up to the institution) and international single immediate payments denominated in euro (typically via SEPA Credit Transfer).

In order to initiate single immediate payments, follow the Payment Initiation instructions below. Do not specify a schedule field when creating a single immediate payment.

Standing Orders

Plaid currently only supports domestic standing orders denominated in pound sterling. All standing orders will be open ended without a set end date or predefined number of payments. Standing orders can also only be modified or canceled by the end user through the bank that they were set up with.

In order to set up standing orders, follow the Payment Initiation instructions below. A schedule field is required when creating a standing order.

iOS Integration

Link token support for Payment Initiation using the iOS SDK is coming in September. In the meantime, iOS-based Payment Initiation integrations should continue to use the legacy integration . This requires the use of public_key and payment_token instead of link_token to initialize Link. This only applies to integrations using the iOS SDK. If you're building for LinkWeb and have iOS users, you can still use Link tokens.

High-level flow
  1. Register recipient: A client registers themselves as a recipient by providing a name, IBAN or BACS, and address and receives a new recipient_id.
  2. Pay with Plaid: An end user decides to pay the client using Plaid.
  3. Configure the payment: The client configures the payment by specifying a recipient_id, reference, amount, and currency to create a Plaid payment resource. The Plaid API returns a payment_id for the client’s backend.
  4. Create link token: The client calls link/token/create with the payment_id configured to create a link_token for payment initiation.
  5. Initialize Link: The client initializes Link using the link_token.
  6. Payment and account details: The end user selects an institution and authenticates with that institution to authorize the payment. Since we only support one-time payments, these steps are necessary for every payment initiation attempt, regardless of any previous payments made by the end user.
  7. Payment initiation: Plaid initiates the payment on the end user’s behalf. If the payment is successfully initiated, Plaid bills the client. Because Plaid is not in the flow of funds, we cannot provide confirmation when the funds leave the end user account or arrive in the client account.
  8. Confirmation: The end user is presented with a confirmation or error, along with the reference.
  9. Retrieve payment status: The client can use an API endpoint to retrieve the status of a payment by providing the payment_id.
  10. Verify funds: The client verifies that the funds reach the recipient account.

To initialize Link for Payment Initiation, pass in a link_token that is confgured for payment_initiation. See an example of how to do this below.

Initializing Link
Create recipient request

POST /payment_initiation/recipient/create

The endpoint is idempotent: if a developer has already made a request with the same payment details, Plaid will return the same recipient_id. Recipients are scoped per environment.

In the sandbox environment, you can use the /payment_initiation/recipient/create endpoint to generate recipients. Programmatic recipient creation in the development and production environments can be done after approval by our compliance team. Please contact sales when you are ready to test payment initiation and we will enable you in the relevant environments.

FieldRequired?Description
client_id
String		yesYour client_id.
secret
String		yesYour secret.
name
String		yesThe name of the recipient.
iban
String		noThe International Bank Account Number (IBAN) for the recipient. One of IBAN or BACS is required.
bacs
Object		noThe Bacs Payment Schemes Limited (BACS) for the recipient. One of IBAN or BACS is required.
address
Object		noThe address for the recipient.

The following address fields are required:

KeyDescription
street
[String]		An array of length 1-2 representing the street address where the recipient is located.
city
String		The city where the recipient is located.
postal_code
String		The postal code where the recipient is located.
country
String		The ISO 3166-1 alpha-2 country code where the recipient is located.

The following bacs fields are required:

KeyDescription
account
String		The account number of the recipient
sort_code
String		The sort code of the recipient
Create recipient request

client.createPaymentRecipient(
  name,
  iban, // or bacs
  address,
  (err, response) => {
  // Handle err
  var recipientID = response.recipient_id;
});


curl -X POST https://sandbox.plaid.com/payment_initiation/recipient/create \
-H 'Content-Type: application/json' \
-d '{
  "client_id": String,
  "secret": String,
  "name": String,
  "iban": String, # or bacs
  "address": Object
}'


response = @client.payment_initiation.create_recipient(
  @name,
  @iban, # or bacs
  @address
)
recipient_id = response.recipient_id


Response<PaymentRecipientCreateResponse> response =
  client.service().paymentRecipientCreate(
    new PaymentRecipientCreateRequest(
      name,
      iban, // or bacs
      address
    )).execute();


response = client.PaymentInitiation.create_recipient(
  name,
  iban, # or bacs
  address
)
recipient_id = response["recipient_id"]
Create recipient response

http code 200
{
  "recipient_id": "recipient-id-sandbox-9b6b4679-914b-445b-9450-efbdb80296f6",
  "request_id": "4zlKapIkTm8p5KM"
}
Get recipient request

POST /payment_initiation/recipient/get
FieldRequired?Description
client_id
String		yesYour client_id.
secret
String		yesYour secret.
recipient_id
String		yesThe ID of the recipient.
Get recipient request

client.getPaymentRecipient(recipientID, (err, response) => {
  // Handle err
  var recipientID = response.recipient_id;
  var name = response.name;
  var iban = response.iban;
  var address = response.address;
});


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


response = @client.payment_initiation.get_recipient(@recipient_id)
recipient_id = response.recipient_id
name = response.name
iban = response.iban
address = response.address


Response<PaymentRecipientGetResponse> response =
  client.service().paymentRecipientGet(new PaymentRecipientGetRequest(recipientID)).execute();


response = client.PaymentInitiation.get_recipient(recipient_id)
recipient_id = response["recipient_id"]
name = response["name"]
iban = response["iban"]
address = response["address"]
Get recipient response

http code 200
{
  "recipient_id": "recipient-id-sandbox-9b6b4679-914b-445b-9450-efbdb80296f6",
  "name": "Wonder Wallet",
  "iban": "GB29NWBK60161331926819",
  "address": {
    "street": [
      "96 Guild Street",
      "9th Floor"
    ],
    "city": "London",
    "postal_code": "SE14 8JW",
    "country": "GB"
  }
  "request_id": "4zlKapIkTm8p5KM"
}
Recipient schema
FieldDescription
recipient_id
String		The ID of the recipient.
name
String		The name of the recipient.
iban
String		The International Bank Account Number (IBAN) for the recipient.
address
Object		The address for the recipient.
List recipients request

POST /payment_initiation/recipient/list
FieldRequired?Description
client_id
String		yesYour client_id.
secret
String		yesYour secret.
List recipients request

client.listPaymentRecipients((err, response) => {
  // Handle err
  var recipients = response.recipients;
});


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


response = @client.payment_initiation.list_recipients()
recipients = response.recipients


Response<PaymentRecipientListResponse> response =
  client.service().paymentRecipientList(new PaymentRecipientListRequest()).execute();


response = client.PaymentInitiation.list_recipients()
recipients = response["recipients"]
List recipients response

http code 200
{
  "recipients": [
    {
      "recipient_id": "recipient-id-sandbox-9b6b4679-914b-445b-9450-efbdb80296f6",
      "name": "Wonder Wallet",
      "iban": "GB29NWBK60161331926819",
      "address": {
        "street": [
          "96 Guild Street",
          "9th Floor"
        ],
        "city": "London",
        "postal_code": "SE14 8JW",
        "country": "GB"
      }
    }
  ],
  "request_id": "4zlKapIkTm8p5KM"
}

For more information on the recipient schema, see the Get recipient request

Create payment request

POST /payment_initiation/payment/create
FieldRequired?Description
client_id
String		yesYour client_id.
secret
String		yesYour secret.
recipient_id
String		yesThe ID of the recipient the payment is for.
reference
String		yesA reference for the payment. This must be an alphanumeric string with at most 18 characters and must not contain special characters (since not all institutions support them).
amount
Object		yesThe amount of the payment.
schedule
Object		noThe schedule that the payment will be executed on. If a schedule is provided, the payment is automatically set up as a standing order.

The following amount fields are required:

KeyDescription
currency
String		The currency of the payment.
value
Float		The value of the payment.

The following schedule fields are required:

KeyDescription
interval
String		The interval of the payment. See below for more details on valid intervals.
interval_execution_day
Number		The day of the week or day of the month that the payment should be made. The value for this field depends on the interval. See below for valid values to use for this field.
start_date
String		The date to start the standing order formatted as YYYY-MM-DD. The start date cannot be in the past.

Payment Intervals:

IntervalDescription
WEEKLYEach payment within a standing order is made weekly. In this case the interval_execution_day should be thought of as the day of the week and should be an integral number in the range [1, 7] where 1 represents Monday.
MONTHLYEach payment within a standing order is made monthly. In this case the interval_execution_day should be thought of as the day of the month and should be an integral number in the range [-5, -1] or [1, 28]. Negative numbers can be used to count backwards from the end of a month.
Create payment request

client.createPayment(
  recipientID,
  reference,
  amount,
  (err, response) => {
  // Handle err
  var paymentID = response.payment_id;
  var status = response.status;
});


curl -X POST https://sandbox.plaid.com/payment_initiation/payment/create \
-H 'Content-Type: application/json' \
-d '{
  "client_id": String,
  "secret": String,
  "recipient_id": String,
  "reference": String,
  "amount": Object
}'


response = @client.payment_initiation.create_payment(
  @recipient_id,
  @reference,
  @amount
)
payment_id = response.payment_id
status = response.status


Response<PaymentCreateResponse> response =
  client.service().paymentCreate(
    new PaymentCreateRequest(
      recipientID,
      reference,
      amount
    )).execute();


response = client.PaymentInitiation.create_payment(
  recipient_id,
  reference,
  amount
)
payment_id = response["payment_id"]
status = response["status"]
Create payment response

http code 200
{
  "payment_id": "payment-id-sandbox-feca8a7a-5591-4aef-9297-f3062bb735d3",
  "status": "PAYMENT_STATUS_INPUT_NEEDED",
  "request_id": "4ciYVmesrySiUAB"
}


POST /link/token/create

You can create a link_token configured for payment initiation. The link_token will allow for at most one payment initiation. If this attempt fails, the end user aborts the flow, or the token expires, the developer will need to create a new link_token. Creating a new link_token does not require end user input. For more info, refer to the /link/token/create docs.

Create link token request
Create link token response

If your integration is still using a payment_token to launch Link for the Payment Initiation product, view our migration guide to upgrade to link_tokens. You can also view our maintenance guide to troubleshoot any payment_token issues.

Get payment request

POST /payment_initiation/payment/get
FieldRequired?Description
client_id
String		yesYour client_id.
secret
String		yesYour secret.
payment_id
String		yesThe payment_id returned from /payment_initiation/payment/create.
Get payment request

client.getPayment(paymentID, (err, response) => {
  // Handle err
  var paymentID = response.payment_id;
  var reference = response.reference;
  var amount = response.amount;
  var status = response.status;
  var lastStatusUpdate = response.last_status_update;
  var recipientID = response.recipient_id;
});


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


response = @client.payment_initiation.get_payment(@payment_id)
payment_id = response.payment_id
reference = response.reference
amount = response.amount
status = response.status
last_status_update = response.last_status_update
recipient_id = response.recipient_id


Response<PaymentGetResponse> response =
  client.service().paymentGet(new PaymentGetRequest(paymentID)).execute();


response = client.PaymentInitiation.get_payment(payment_id)
payment_id = response["payment_id"]
reference = response["reference"]
amount = response["amount"]
status = response["status"]
last_status_update = response["last_status_update"]
recipient_id = response["recipient_id"]
Get payment response

http code 200
{
  "payment_id": "payment-id-sandbox-feca8a7a-5591-4aef-9297-f3062bb735d3",
  "reference": "Account Funding 99744",
  "amount": {
    "currency": "GBP",
    "value": 100.00
  },
  "status": "PAYMENT_STATUS_INPUT_NEEDED",
  "last_status_update": "2019-11-06T21:10:52Z",
  "recipient_id": "recipient-id-sandbox-9b6b4679-914b-445b-9450-efbdb80296f6",
  "request_id": "aEAQmewMzlVa1k6"
}
Payment schema
FieldDescription
payment_id
String		The ID of the payment.
reference
String		A reference for the payment.
amount
Object		The amount of the payment. See Create payment request for more details.
schedule
Object		The schedule of the payment. If a payment has a schedule it is a standing order. See Create payment request for more details.
status
String		The status of the payment.
last_status_update
Date		The last time the status was updated.
recipient_id
String		The ID of the recipient.
Payment statuses
Payment statusDescription
PAYMENT_STATUS_INPUT_NEEDED
Initial state		This is the initial state of all payments. It indicates that the payment is waiting on user input to continue processing. A payment may re-enter this state later on if further input is needed.
PAYMENT_STATUS_PROCESSING
Intermediate state		The payment is currently being processed by Plaid and the relevant financial institution. The payment will automatically exit this state when processing is complete.
PAYMENT_STATUS_FAILED
Retryable state		The payment has failed to be initiated due to certain known errors (i.e. the financial institution's internal service was down) and is retryable once the root cause is resolved.
PAYMENT_STATUS_BLOCKED
Retryable state		The payment has been blocked.
PAYMENT_STATUS_UNKNOWN
Terminal state		The payment is in an unknown state as the result of a downstream error. This is a catch-all status that is unrecoverable but rare. If a payment is in an unknown state, it is possible that the payment was initiated.
PAYMENT_STATUS_INITIATED
Terminal state		The payment has been successfully initiated. This should be the terminal state for single immediate payments. Please ensure that the payment has been received by the recipient bank account.
PAYMENT_STATUS_COMPLETED
Terminal state		The payment has been successfully set up and completed. This should be the terminal state for standing orders. Over the course of a standing order, please ensure that each individual payment within the standing order is received by the recipient bank account.
List payments request

POST /payment_initiation/payment/list
FieldRequired?Description
client_id
String		yesYour client_id.
secret
String		yesYour secret.
options
Object		noIf provided, must be non-null.

The following options are available:

FieldDefaultDescription
count
Number, nullable		 null Limit for how many payments to return, 0 < count <= 200.
cursor
String, nullable		 null A string in RFC 3339 format (i.e. "2019-12-06T22:35:49Z"). Only payments created before the cursor will be returned.
List payments request

client.listPayments({count: 10, cursor: "2019-12-06T22:35:49Z"} (err, response) => {
  // Handle err
  var payments = response.payments;
  var nextCursor = response.next_cursor;
});


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


response = @client.payment_initiation.list_payments(count: 10, cursor: "2019-12-06T22:35:49Z")
payments = response.payments
next_cursor = response.next_cursor


Response<PaymentListResponse> response =
  client.service().paymentList(
    new PaymentListRequest()
      .withCount(10)
      .withCursor("2019-12-06T22:35:49Z")
    ).execute();


response = client.PaymentInitiation.list_payments({count: 10, cursor: "2019-12-06T22:35:49Z"})
payments = response["payments"]
next_cursor = response["next_cursor"]
List payments response

http code 200
{
  "payments": [
    "payment_id": "payment-id-sandbox-feca8a7a-5591-4aef-9297-f3062bb735d3",
    "reference": "Account Funding 99744",
    "amount": {
      "currency": "GBP",
      "value": 100.00
    },
    "status": "PAYMENT_STATUS_INPUT_NEEDED"
    "last_status_update": "2019-11-06T21:10:52Z",
    "recipient_id": "recipient-id-sandbox-9b6b4679-914b-445b-9450-efbdb80296f6"
  ],
  "next_cursor": "2020-01-01T00:00:00Z",
  "request_id": "aEAQmewMzlVa1k6"
}

For more information on the payment schema, see the Get payment request

Item management

Accounts

Retrieve Accounts request

The following endpoint can be used to retrieve information for any linked bank account, note that some information is nullable. Plaid will only return active bank accounts, i.e. accounts that are not closed and are capable of carrying a balance, closed accounts will not be returned in our API.


POST /accounts/get
FieldRequired?
client_id
String		yes
secret
String		yes
access_token
String		yes
Retrieve Accounts request

// Pull the accounts associated with the Item
client.getAccounts(ACCESS_TOKEN, (err, result) => {
  // Handle err
  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)
accounts = response[:accounts]


// 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
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",
    "verification_status": null
  }, {
    "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": "m8MDnv9okwxFNBV"
}
Account schema
KeyDescription
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		See Balance object for fields.
name
String		The name of the Account, either assigned by the user or the financial institution itself.
mask
String, nullable		The last 2-4 alphanumeric characters of an account's official account number. Note that the mask may be non-unique between an Item's accounts, it may also not match the mask that the bank displays to the user. This field is nullable.
official_name
String, nullable		The official name of the Account as given by the financial institution.
type
String		See account types below.
subtype
String		See account subtypes below.
verification_status
String		The current verification status of an Auth Item initiated through Automated or Manual microdeposits. See account verification statuses below.
Account balances schema

See Balance object for fields.

Account types
Account typeDescription
investmentInvestment account
creditCredit card
depositoryChecking or savings accounts
loanLoan account
otherNon-specified account type
Account subtypes
Account typeSubtypesDescription
investmentSee Investment account subtypes below.
creditcredit cardBank issued credit card
paypalPayPal issued credit card
depositorycash managementCash management account
cdCertificate of deposit
checkingStandard checking account
hsaHealth Savings Account that may only hold cash
savingsStandard savings account
money marketSimilar to checking accounts
paypalPayPal held depository account
prepaidPrepaid debit card
loanautoAutomobile loan
commercialCommercial loan
constructionConstruction loan
consumerConsumer loan
home equityHome Equity Line of Credit (HELOC)
loanGeneral loan
mortgageMortgage loan
overdraftPre-approved overdraft account, usually tied to a checking account
line of creditPre-approved line of credit
studentStudent loan
otherotherPlaid was unable to properly categorize this account or the account does not fit into our current schema.
Account subtypes – investment

The following is a list of possible investment Account subtypes and their respective description.

Investment subtypeDescription
401a Employer-sponsored money-purchase retirement plan
401k Standard 401k account
403b Tax-advantaged retirement savings plan
457b Tax-advantaged deferred-compensation retirement plan
529 College savings plans and prepaid tuition plans
brokerage Standard Brokerage account
cash isa UK account that pays interest tax-free
education savings account Tax-advantaged Education Savings Account (ESA)
fixed annuity Fixed Annuity
gic Canadian Guaranteed Investment Certificate
health reimbursement arrangement Tax-advantaged health benefit plan
hsa Tax-advantaged medical Health Savings Account
ira Traditional IRA
isa UK 'Individual Savings Account'
keogh Keogh self-employed pension plan
lif Canadian registered Retirement Income Fund
lira Canadian Locked-In Retirement Account
lrif Canadian Locked-in Retirement Income Fund
lrsp Canadian Locked-in Retirement Savings Plan
mutual fund Account that holds mutual fund positions
non-taxable brokerage account A non-taxable brokerage account that is not covered by a more specific subtype
pension Standard Pension account
prif Canadian Prescribed Registered Retirement Income Fund
profit sharing plan Plan gives employees share of company profits
qshr Qualifying share account
rdsp Canadian Registered Disability Savings Plan
resp Canadian Registered Education Savings Plan
retirement A retirement account not covered by other subtypes
rlif Canadian Restricted Life Income Fund
roth Roth IRA
roth 401k Employer-sponsored investment savings account
rrif Canadian Registered Retirement Income Fund
rrsp Canadian Registered Retirement Savings Plan (equivalent to 401k)
sarsep Salary Reduction Simplified Employee Pension Plan
sep ira Simplified Employee Pension IRA
simple ira Savings Incentive Match Plan for Employees IRA
sipp UK Self-Invested Personal Pension
stock plan Standard Stock Plan account
tfsa Canadian tax-free savings account, equivalent to roth
thrift savings plan Defined contribution plan for US civil servants
trust Account representing funds or assets held by a trustee for the benefit of a beneficiary
ugma 'Uniform Gift to Minors Act' (brokerage account for minors)
utma 'Uniform Transfers to Minors Act' (brokerage account for minors)
variable annuity Tax-deferred capital accumulation annuity contract
Account verification statuses

Returned for Auth Items only.

Account verification statusDescription
pending_automatic_verificationAn Item is pending automated microdeposit verification
automatically_verifiedAn Item was successfully automatically verified
verification_expiredAn Item failed automatic verification within 7 days. Users may retry by submitting their information again through Link.
pending_manual_verificationAn Item is pending manual microdeposit verification
manually_verifiedAn Item was successfully manually verified

Retrieve Item

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

Retrieve Item request

POST /item/get
FieldRequired?
client_id
String		yes
secret
String		yes
access_token
String		yes
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)
# the item has a list of available products, billed products,
# error status, webhook information, and more.
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)
# the item has a list of available products, billed products,
# error status, webhook information, and more.
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",
    "consent_expiration_time": null
  },
  "status": {
    "transactions": {
      "last_successful_update": "2019-02-15T15:10:00",
      "last_failed_update": "2019-01-22T04:32:00"
    },
    "last_webhook": {
      "sent_at": "2019-02-15T15:53:00",
      "code_sent": "DEFAULT_UPDATE"
    }
  },
  "request_id": "m8MDnv9okwxFNBV"
}
Response schema
KeyDescription
item
Object		Metadata about the item. View schema.
status
Object		An object with information about the status of the Item. View schema.
Item schema
KeyDescription
item_id
String		The Plaid Item ID.
institution_id
String		The Plaid Institution ID associated with the Item.

Note: institution_id is null only for Items created via Same Day Microdeposits
webhook
String, nullable		The URL registered to receive webhooks for the Item.
error
Object		An object with information about the error status of the Item. If there is no error, all values will be null. View schema.
available_products
[String]		A list of products available for the Item that have not yet been accessed.
billed_products
[String]		A list of products that have been billed for the Item.

Note: billed_products is populated in all environments but only requests in Production are billed.
consent_expiration_time
String, nullable		The RFC 3339 timestamp after which the consent provided by the end user will expire. Upon consent expiration, the item will enter the ITEM_LOGIN_REQUIRED error state. To circumvent the ITEM_LOGIN_REQUIRED error and maintain continuous consent, the end user can reauthenticate via Link’s update mode in advance of the consent expiration time.

Note: This is only relevant for European institutions subject to PSD2 regulations mandating a 90-day consent window. For all other institutions, this field will be null.
Item error schema
FieldDescription
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.

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 to the newly specified webhook.

Update webhook request

POST /item/webhook/update
FieldRequired?Description
client_id
String		yes
secret
String		yes
access_token
String		yes
webhook
String		YesThe new webhook to associate with the Item.
Update Webhook request

// Update the webhook associated with an Item
client.updateItemWebhook(ACCESS_TOKEN, "https://plaid.com/updated/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://plaid.com/updated/webhook')


// Update the webhook associated with an Item
Response<ItemWebhookUpdateResponse> webhookResponse = client().service().itemWebhookUpdate(
    new ItemWebhookUpdateRequest(ACCESS_TOKEN, "https://plaid.com/updated/webhook")).execute();
// A successful response indicates that the webhook has been
// updated. An acknowledgement webhook will also be fired.
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://plaid.com/updated/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",
    "consent_expiration_time": null
  },
  "request_id": "m8MDnv9okwxFNBV"
}

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.

Rotate Access Token request

POST /item/access_token/invalidate
FieldRequired?
client_id
String		yes
secret
String		yes
access_token
String		yes
Rotate access_token request

// Generate a new access_token for an Item, invalidating 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, invalidating 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']


// Generate a new access_token for an Item, invalidating the old one
Response<ItemAccessTokenInvalidateResponse> response = client().service().itemAccessTokenInvalidate(
  new ItemAccessTokenInvalidateRequest("ACCESS_TOKEN")).execute();

String newAccessToken;
if (response.isSuccessful()) {
  // Store the new access_token in a persistent, secure datastore
  newAccessToken = response.body().getNewAccessToken();
}


# generate a new access_token for an item, invalidating 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": "m8MDnv9okwxFNBV"
}

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.

Remove Item request

POST /item/remove
FieldRequired?
client_id
String		yes
secret
String		yes
access_token
String		yes
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": "m8MDnv9okwxFNBV",
}

Item status

The status of an Item provides information about its most recent successful and failed transactions updates as well as the most recent webhook fired.

You can access the status of an Item in the Dashboard or via the API using the /item/get endpoint.

Item status example

"status": {
  "investments": {
    "last_successful_update": "2019-05-23T19:51:00Z",
    "last_failed_update": "2019-03-15T02:10:00Z"
  },
  "transactions": {
    "last_successful_update": "2019-02-15T15:10:00Z",
    "last_failed_update": "2019-01-22T04:32:00Z"
  },
  "last_webhook": {
    "sent_at": "2019-02-15T15:53:00Z",
    "code_sent": "DEFAULT_UPDATE"
  }
}
Item status schema
FieldDescription
investments
Object		Information about the last successful and failed investments update for the Item. View schema.
transactions
Object		Information about the last successful and failed transactions update for the Item. View schema.
last_webhook
Object		Information about the last webhook fired for the Item. View schema.
Investments status schema

The investments status object will always be returned, but its individual values may be null if investments is not a billed product for the Item. A response indicates the update status of the investments products billed for the respective item.

FieldDescription
last_successful_update
String, nullable		 ISO 8601 timestamp of the last successful investments update for the Item.
last_failed_update
String, nullable		 ISO 8601 timestamp of the last failed investments update for the Item.
Transactions status schema

The transactions status object will always be returned, but its individual values may be null if transactions is not a billed product for the Item.

FieldDescription
last_successful_update
String, nullable		 ISO 8601 timestamp of the last successful transactions update for the Item.
last_failed_update
String, nullable		 ISO 8601 timestamp of the last failed transactions update for the Item.
Webhook status schema
FieldDescription
sent_at
String		 ISO 8601 timestamp of when the webhook was fired.
code_sent
String		The last webhook code sent. View webhooks.

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:

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

Invalid request errors

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

Invalid input errors

{
  "error_type": "INVALID_INPUT",
  "http_code": 400,
  "error_code": Enum (
    "INVALID_API_KEYS",
    "INVALID_LINK_TOKEN"
    "UNAUTHORIZED_ENVIRONMENT",
    "INVALID_ACCESS_TOKEN",
    "INVALID_PUBLIC_TOKEN",
    "INVALID_PRODUCT",
    "INVALID_ACCOUNT_ID",
    "INVALID_INSTITUTION",
    "TOO_MANY_VERIFICATION_ATTEMPTS"
  )
  "error_message": String
  "display_message": Null,
  "request_id": String
}
Error codeNotes
INVALID_API_KEYS
HTTP 400		The client ID and secret included in the request body were invalid. Find your API keys in the Dashboard.
INVALID_LINK_TOKEN
HTTP 400		The link_token used to open Link has expired, has already been used to initialize Link, or has been used for too many attempts. Create a new link_token with the /link/token/create request.
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.
TOO_MANY_VERIFICATION_ATTEMPTS
HTTP 400		The user attempted to verify their Manual Same-Day micro-deposit amounts more than 3 times and their Item is now permanently locked. The user must retry submitting their account information in Link.

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.

Rate limit errors

{
  "error_type": "RATE_LIMIT_EXCEEDED",
  "http_code": 429,
  "error_code": Enum (
    "ACCOUNTS_LIMIT",
    "ADDITION_LIMIT",
    "AUTH_LIMIT",
    "IDENTITY_LIMIT",
    "ITEM_GET_LIMIT",
    "RATE_LIMIT"
    "TRANSACTIONS_LIMIT",
  )
  "error_message": String
  "display_message": nullable String,
  "request_id": String
}
Error codeNotes
ACCOUNTS_LIMIT
HTTP 429		Too many requests were made to the /accounts/get endpoint.
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.
IDENTITY_LIMIT
HTTP 429		Too many requests were made to the /identity/get endpoint.
ITEM_GET_LIMIT
HTTP 429		Too many requests were made to the /item/get endpoint.
RATE_LIMIT
HTTP 429		Too many requests were made.
TRANSACTIONS_LIMIT
HTTP 429		Too many requests were made to the /transactions/get endpoint.

API errors

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

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

Item error schema

{
  "error_type": "ITEM_ERROR",
  "http_code": 400,
  "error_code": Enum (
    "INSUFFICIENT_CREDENTIALS",
    "INVALID_CREDENTIALS",
    "INVALID_MFA",
    "INVALID_SEND_METHOD",
    "INVALID_UPDATED_USERNAME",
    "ITEM_LOCKED",
    "ITEM_LOGIN_REQUIRED",
    "ITEM_NO_ERROR",
    "ITEM_NOT_SUPPORTED",
    "ITEM_NOT_FOUND",
    "INCORRECT_DEPOSIT_AMOUNTS",
    "USER_SETUP_REQUIRED",
    "MFA_NOT_SUPPORTED",
    "NO_ACCOUNTS",
    "NO_AUTH_ACCOUNTS",
    "NO_INVESTMENT_ACCOUNTS",
    "NO_LIABILITY_ACCOUNTS",
    "PRODUCT_NOT_READY",
    "PRODUCTS_NOT_SUPPORTED",
    "INSTANT_MATCH_FAILED",
  )
  "error_message": String
  "display_message": nullable String,
  "request_id": String
}
Error codeNotes
INSUFFICIENT_CREDENTIALS
HTTP 400		The user did not provide sufficient authorization in order to link their account via an OAuth login flow.
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_SEND_METHOD
HTTP 400		Plaid could not match up the MFA OTP send method to one of the ones we sent to the user or the institution rejected it as invalid for some reason.
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.
ITEM_NOT_FOUND
HTTP 400		The Item you requested cannot be found. This Item does not exist, has been previously removed via /item/remove, or has had access removed by the user.
INCORRECT_DEPOSIT_AMOUNTS
HTTP 400		The user submitted incorrect Manual Same-Day micro-deposit amounts during Item verification in Link.
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.
NO_INVESTMENT_ACCOUNTS
HTTP 400		Returned from POST /investments/holdings/get or POST /investments/transactions/get when there are no valid investment account(s) for which holdings or transactions could be retrieved.
NO_LIABILITY_ACCOUNTS
HTTP 400		Returned from POST /liabilities/get when there are no valid liability account(s) for which liabilities 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.
INSTANT_MATCH_FAILED
HTTP 400		Returned when an account cannot be verified using Instant Match. To resolve, ensure you are correctly enabling all Auth features when initializing Link.

Auth errors

The AUTH_ERROR error type identifies a class of issues related to verifying and pulling Auth numbers data.

Auth error schema

{
  "error_type": "AUTH_ERROR",
  "http_code": Enum (
    400,
    404,
    500
  ),
  "error_code": Enum (
    "PRODUCT_NOT_READY",
    "VERIFICATION_EXPIRED"
  ),
  "error_message": String,
  "display_message": nullable String,
  "request_id": String,
  "account_id": String
}
Error codeNotes
PRODUCT_NOT_READY
HTTP 400		Calling /auth/get on an Item that has not been verified will return this error. Verify the Item manually, or wait for automated verification to succeed.
VERIFICATION_EXPIRED
HTTP 400		If an Item cannot be verified after 7 days, an error webhook will be sent to the webhook specified in the Link configuration

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.

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",
    "INSIGHTS_NOT_ENABLED",
    "INSIGHTS_PREVIOUSLY_NOT_ENABLED"
  ),
  "error_message": String,
  "display_message": nullable String,
  "causes": optional []Cause,
  "request_id": String
}
Error codeNotes
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).
INSIGHTS_NOT_ENABLED
HTTP 400		You tried to retrieve an Asset Report with Insights but you do not have access to this feature. Contact us for more information.
INSIGHTS_PREVIOUSLY_NOT_ENABLED
HTTP 400		You tried to retrieve an Asset Report with Insights and you do have access to the feature, but you did not have permission to create an Asset Report with Insights at the time of Asset Report creation. To retrieve this Asset Report as an Asset Report with Insights, you will need to recreate the Asset Report.
Asset Report warning schema

{
  "warning_type": "ASSET_REPORT_WARNING",
  "warning_code": Enum (
    "OWNERS_UNAVAILABLE"
  ),
  "cause": Cause
}
Warning codeNotes
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.

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

Auth webhooks

When an Automated microdeposit Item is created, Plaid verifies the Item and sends a webhook upon successful verification, 1 to 2 business days later. Occasionally when verification does not succeed, Plaid sends an expired webhook. Please note, if you attempt to retrieve an Automated microdeposit Item before verification succeeds, you’ll receive a response with the HTTP status code 400 and a Plaid error code of PRODUCT_NOT_READY.

Auth webhooks will be sent to the URL supplied when creating an Item .

CodeDetails
AUTOMATICALLY_VERIFIEDFired when an Item is automatically verified after 1 to 2 business days. We recommend communicating to your users when this event is received to notify them that their account is verified and ready for use.
VERIFICATION_EXPIREDFired when an Item cannot be verified automatically after 7 days.
Automated microdeposit successful webhook

{
  "webhook_type": "AUTH",
  "webhook_code": "AUTOMATICALLY_VERIFIED",
  "item_id": String,
  "account_id": String
}
Automated microdeposit verification failed webhook

{
  "webhook_type": "AUTH",
  "webhook_code": "ERROR",
  "item_id": String,
  "account_id": String,
  "error": {
    "display_message": String,
    "error_code": String,
    "error_message": String,
    "error_type": "VERIFICATION_EXPIRED"
  },
}

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.

CodeDetails
INITIAL_UPDATEFired when an Item's initial transaction pull is completed.

Note: The default pull is 30 days.
HISTORICAL_UPDATEFired when an Item's historical transaction pull is completed. Plaid fetches as much data as is available from the financial institution.
DEFAULT_UPDATEFired when new transaction data is available as Plaid performs its regular updates of the Item.
TRANSACTIONS_REMOVEDFired when 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.

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.

CodeDetails
WEBHOOK_UPDATE_ACKNOWLEDGED Fired when an Item ’s webhook is updated. This will be sent to the newly specified webhook.
PENDING_EXPIRATION Fired when an Item’s access consent is expiring in 7 days. Some Items have explicit expiration times and we try to relay this when possible to reduce service disruption. This can be resolved by having the user go through Link’s update mode.
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.
USER_PERMISSION_REVOKED Fired when a consumer has revoked access to that Item via my.plaid.com. This error cannot be resolved, and if the user subsequently returns to your application, a new Item should be created.
Item's webhook updated webhook

{
  "webhook_type": "ITEM",
  "webhook_code": "WEBHOOK_UPDATE_ACKNOWLEDGED",
  "item_id": "wz666MBjYWTp2PDzzggYhM6oWWmBb",
  "error": null,
  "new_webhook_url": "https://plaid.com/example/webhook"
}
Item pending expiration webhook

{
  "webhook_type": "ITEM",
  "webhook_code": "PENDING_EXPIRATION",
  "item_id": "wz666MBjYWTp2PDzzggYhM6oWWmBb",
  "consent_expiration_time": "2020-01-15T13:25:17.766Z"
  }
}
Item user permission revoked webhook

{
  "error": {
    "error_code": "USER_PERMISSION_REVOKED",
    "error_message": "the holder of this account has revoked their permission for your application to access it",
    "error_type": "ITEM_ERROR",
    "status": 400
  },
  "item_id": "gAXlMgVEw5uEGoQnnXZ6tn9E7Mn3LBc4PJVKZ",
  "webhook_code": "USER_PERMISSION_REVOKED",
  "webhook_type": "ITEM"
}
Item error webhook

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

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

Investments webhooks

You can receive notifications via a webhook whenever there is freshly updated holdings data or new investment transactions associated with an Item. Webhooks indicating an update to holdings data will have a webhook_type of HOLDINGS. Webhooks related to investments transactions will have a webhook_type of INVESTMENTS_TRANSACTIONS.

CodeDetails
DEFAULT_UPDATEFired when updated holdings data or new investments transactions are available as Plaid performs its regular updates of the Item.
Investments holdings webhook

{
  "webhook_type": "HOLDINGS",
  "webhook_code": "DEFAULT_UPDATE",
  "item_id": "wz666MBjYWTp2PDzzggYhM6oWWmBb",
  "error": null,
  "new_holdings": 19,
  "updated_holdings": 0
}
Investments transactions webhook

{
  "webhook_type": "INVESTMENTS_TRANSACTIONS",
  "webhook_code": "DEFAULT_UPDATE",
  "item_id": "wz666MBjYWTp2PDzzggYhM6oWWmBb",
  "error": null,
  "new_investments_transactions": 16,
  "cancelled_investments_transactions": 0
}

Payment Initiation webhooks

You can receive notifications via a webhook when there are changes related to the Payment Initiation product. Webhooks indicating an update to payment data will have a webhook_type of PAYMENT_INITIATION.

CodeDetails
PAYMENT_STATUS_UPDATEFired when the status of a payment has changed. The statuses of a payment can be found here .
Payment Initiation Webhook

{
  "webhook_type": "PAYMENT_INITIATION",
  "webhook_code": "PAYMENT_STATUS_UPDATE",
  "payment_id": "payment-id-production-2ba30780-d549-4335-b1fe-c2a938aa39d2",
  "new_payment_status": "PAYMENT_STATUS_INITIATED",
  "old_payment_status": "PAYMENT_STATUS_PROCESSING",
  "timestamp": "2017-09-14T14:42:19.350Z"
}

Webhook verification

Plaid signs all outgoing webhooks so that you can verify the authenticity of any incoming webhooks to your application. A message signature is included in the Plaid-Verification header.

The verification process requires understanding JSON Web Tokens (JWTs) and JSON Web Keys (JWKs). More information about these specifications can be found at jwt.io.

Libraries for interpreting and verifying JWKs and JWTs most likely exist in your preferred language. It is highly recommended that you utilize well-tested libraries rather than trying to implement these specifications from scratch.

See our help center article for a reference implementation of webhook verification.

Steps for verification

Extract the Plaid-Verification HTTP header from any Plaid webhook (see Firing webhooks for testing). The value of the Plaid-Verification header is a JWT, and will be referred to as "the JWT" in following steps.

Extract the JWT header value without validating the signature. This functionality most likely exists in your preferred JWT library. An example JWT header is shown below.

Plaid-Verification header JWT header

{
  "alg": "ES256",
  "kid": "bfbd5111-8e33-4643-8ced-b2e642a72f3c",
  "typ": "JWT"
}

Ensure that the alg (algorithm) field in the header is ES256. Reject the webhook if this is not the case.

Extract the value corresponding to the kid (key ID) field. This will be used to retrieve the public key corresponding to the private key that was used to sign this request.

Webhook verification key endpoint

POST /webhook_verification_key/get
FieldRequired?Description
client_id
String		yes
secret
String		yes
key_id
String		yesThe key ID ( kid ) from the JWT header.
Webhook verification key request

// Get the webhook verification key
client.getWebhookVerificationKey(keyId, (err, result) => {
  // Handle err
  const key = result.key;
});


curl -X POST https://production.plaid.com/webhook_verification_key/get \
  -H 'content-type: application/json' \
  -d '{
    "client_id": String,
    "secret": String,
    "key_id": String
  }'


response = client.webhooks.get_verification_key(key_id)


Response<WebhookVerificationKeyGetResponse> getWebhookVerificationKeyResponse =
  client()
  .service()
  .getWebhookVerificationKey(
    new WebhookVerificationKeyGetRequest(keyId)
  ).execute();
WebhookVerificationKey key = response.body().getKey();


response = client.Webhooks.get_verification_key(key_id)
Webhook verification key response

http code 200
{
  "key": {
    "alg": "ES256",
    "created_at": 1560466150,
    "crv": "P-256",
    "expired_at": null,
    "kid": "bfbd5111-8e33-4643-8ced-b2e642a72f3c",
    "kty": "EC",
    "use": "sig",
    "x": "hKXLGIjWvCBv-cP5euCTxl8g9GLG9zHo_3pO5NN1DwQ",
    "y": "shhexqPB7YffGn6fR6h2UhTSuCtPmfzQJ6ENVIoO4Ys"
  },
  "request_id": "RZ6Omi1bzzwDaLo"
}

Interpret key as a JWK, and use your preferred library to validate that the signature of the JWK is valid. If the signature is not valid, reject the webhook. Otherwise, extract the payload of the JWT. It will look something like the JSON below.

JWT Payload

{
  "iat": 1560211755,
  "request_body_sha256": "bbe8e9...",
}

Use the issued at time denoted by the iat field to verify that the webhook is not more than 5 minutes old. Rejecting outdated webhooks can help prevent replay attacks.

Extract the value of the request_body_sha256 field. This will be used to check the integrity and authenticity of the webhook body.

Compute the SHA-256 of the webhook body and ensure that it matches what is specified in the request_body_sha256 field of the validated JWT. If not, reject the webhook. It is best practice to use a constant time string/hash comparison method in your preferred language to prevent timing attacks.

Caching and Key rotation

It is recommended that your application caches the public key for a given key ID, but for no more than 24 hours. This reduces the likelihood of using an expired key to validate incoming webhooks.

It may be possible that a key rotation will take place. If your application encounters a webhook with a key ID that it does not have in its cache, it should make an API request to fetch the associated public key. In addition, your application must refetch any keys from the API that are currently in the cache but not yet expired. This helps to ensure that expired keys are not being used for live validation of webhooks by refreshing the expired_at field.

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:

AuthTransactionsBalanceIdentityAssets
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

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

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

Institution search request

POST /institutions/search
FieldRequired?Description
query
String		YesThe search query. Institutions with names matching the query are returned.
products
[String]		YesFilter the Institutions based on whether they support all products listed in products. Provide null to get institutions regardless of supported products.
client_id
String		Yes
secret
String		Yes
options
Object		NoIf provided, must be non-null.

The following options are available:

FieldDefaultDescription
include_optional_metadata
Boolean		 false When true, return an institution's logo, brand color, and URL. When available, the bank's logo is returned as a base64 encoded 152x152 PNG, the brand color is in hexadecimal format. Learn more.
country_codes
[String]		 null Specify an array of Plaid-supported country codes using the ISO-3166-1 alpha-2 country code standard.
routing_numbers
[String]		 null Specify an array of routing numbers to filter institutions. Note, this list is not comprehensive and should never be treated as a complete list of routing numbers for an institution.
oauth
Boolean		 null Limit results to institutions with or without OAuth login flows. This is only relevant to institutions with European country codes.
Institutions search request

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"],
    "client_id": String
    "secret": 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
{
  "institution": {
    "country_codes": [
      "US"
    ],
    "credentials": [
      {
        "label": "Username",
        "name": "username",
        "type": "text"
      },
      {
        "label": "Password",
        "name": "password",
        "type": "password"
      }
    ],
    "has_mfa": true,
    "input_spec": "fixed",
    "institution_id": "ins_109509",
    // included when options.include_optional_metadata is true
    "logo": null,
    "mfa": [
      "code",
      "list",
      "questions",
      "selections"
    ],
    "mfa_code_type": "numeric",
    "name": "First Gingham Credit Union",
    "oauth": false,
    // included when options.include_optional_metadata is true
    "primary_color": "#004966",
    "products": [
      "assets",
      "auth",
      "balance",
      "transactions",
      "credit_details",
      "identity",
      "investments",
      "liabilities"
    ],
    "routing_numbers": [],
    // included when options.include_optional_metadata is true
    "url": "https://www.plaid.com/"
  },
  "request_id": "1oCZkS6UPBqXMVH"
}

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.

Retrieve all Institutions request

 POST /institutions/get
FieldRequired?Description
client_id
String		Yes
secret
String		Yes
count
Number		YesThe total number of Institutions to return, with 0 less than count less than equal to 500.
offset
Number		YesThe number of Institutions to skip before returning results, with offset >= 0.
options
Object		NoIf provided, must be non-null.

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

The following options are available:

FieldDefaultDescription
products
[String]		 null Filter the Institutions based on whether they support all products listed in products.
include_optional_metadata
Boolean		 false When true, return an institution's logo, brand color, and URL. When available, the bank's logo is returned as a base64 encoded 152x152 PNG, the brand color is in hexadecimal format. Learn more.
country_codes
[String]		 null Specify an array of Plaid-supported country codes using the ISO-3166-1 alpha-2 country code standard.
routing_numbers
[String]		 null Specify an array of routing numbers to filter institutions. Note, this list is not comprehensive and should never be treated as a complete list of routing numbers for an institution.
oauth
Boolean		 null Limit results to institutions with or without OAuth login flows. This is only relevant to institutions with European country codes.
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']
All institutions response

http code 200
{
  "institution": {
    "country_codes": [
      "US"
    ],
    "credentials": [
      {
        "label": "Username",
        "name": "username",
        "type": "text"
      },
      {
        "label": "Password",
        "name": "password",
        "type": "password"
      }
    ],
    "has_mfa": true,
    "input_spec": "fixed",
    "institution_id": "ins_109509",
    // included when options.include_optional_metadata is true
    "logo": null,
    "mfa": [
      "code",
      "list",
      "questions",
      "selections"
    ],
    "mfa_code_type": "numeric",
    "name": "First Gingham Credit Union",
    "oauth": false,
    // included when options.include_optional_metadata is true
    "primary_color": "#004966",
    "products": [
      "assets",
      "auth",
      "balance",
      "transactions",
      "credit_details",
      "identity",
      "investments",
      "liabilities"
    ],
    "routing_numbers": [],
    // included when options.include_optional_metadata is true
    "url": "https://www.plaid.com/"
  },
  "request_id": "1oCZkS6UPBqXMVH"
}

Institutions by ID

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

Institutions by ID request

 POST /institutions/get_by_id
FieldRequired?Description
institution_id
String		Yes
client_id
String		Yes
secret
String		Yes
options
Object		NoIf provided, must be non-null.

The following options are available:

FieldDefaultDescription
include_optional_metadata
Boolean		 false When true, return an institution's logo, brand color, and URL. When available, the bank's logo is returned as a base64 encoded 152x152 PNG, the brand color is in hexadecimal format. Learn more.
include_status
Boolean		 false If true, the response will include status information about the institution.
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",
    "client_id": String
    "secret": 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": {
    "country_codes": ["US"],
    "credentials": [{
      "label": "User ID",
      "name": "username",
      "type": "text"
     }, {
      "label": "Password",
      "name": "password",
      "type": "password"
    }],
    "has_mfa": true,
    "institution_id": "ins_109512",
    "mfa": [
      "code",
      "list",
      "questions",
      "selections"
    ],
    "name": "Houndstooth Bank",
    "products": [
      "auth",
      "balance",
      "identity",
      "transactions"
    ],
    "routing_numbers": ["110000000"],
    "oauth": false,
    // included when options.include_status is true
    "status": {
      "item_logins": {
        "status": "HEALTHY",
        "last_status_change": "2019-02-15T15:53:00Z",
        "breakdown": {
          "success": 0.90,
          "error_plaid": 0.01,
          "error_institution": 0.09
        }
      },
      "transactions_updates": {
        "status": "HEALTHY",
        "last_status_change": "2019-02-12T08:22:00Z",
        "breakdown": {
          "success": 0.95,
          "error_plaid": 0.02,
          "error_institution": 0.03,
          "refresh_interval": "NORMAL"
      },
      "auth": {
        "status": "HEALTHY",
        "last_status_change": "2019-02-15T15:53:00Z",
        "breakdown": {
          "success": 0.91,
          "error_plaid": 0.01,
          "error_institution": 0.08
        }
      },
      "balance": {
        "status": "HEALTHY",
        "last_status_change": "2019-02-15T15:53:00Z",
        "breakdown": {
          "success": 0.89,
          "error_plaid": 0.02,
          "error_institution": 0.09
        }
      },
      "identity": {
        "status": "DEGRADED",
        "last_status_change": "2019-02-15T15:50:00Z",
        "breakdown": {
          "success": 0.42,
          "error_plaid": 0.08,
          "error_institution": 0.50
        }
      }
    },
    // included when options.include_optional_metadata is true
    "primary_color": "#004966",
    "url": "https://plaid.com",
    "logo": null
  },
  "request_id": "m8MDnv9okwxFNBV"
}
Institution schema
FieldDescription
institution_id
String		Unique identifier for the institution.
name
String		The official name of the institution.
products
[String]		A list of the Plaid products supported by the institution.
country_codes
[String]		A list of the country codes supported by the institution.
status
Object		Information about the institution's current status. View schema.
url
String, nullable		The URL for the institution's website.
primary_color
String, nullable		Hexadecimal representation of the primary color used by the institution.
logo
String, nullable		Base64 encoded representation of the institution's logo.
routing_numbers
[String], nullable		A partial list of routing numbers associated with the institution. This list is provided to facilitate looking up institutions by routing number. It is not comprehensive and should never be treated as a complete list of routing numbers for an institution.
oauth
Boolean		Indicates that the institution has an OAuth login flow. This is only relevant to institutions with European country codes.
Institution status schema
FieldDescription
item_logins
Object		Status information regarding Item adds via Link. View schema.
transactions_updates
Object		Status information regarding Transactions updates. View schema.
auth
Object		Status information regarding Auth requests. View schema.
balance
Object		Status information regarding Balance requests. View schema.
identity
Object		Status information regarding Identity requests. View schema.

Institution status

The status of an institution is determined by the health of its Item logins, Transactions updates, Auth requests, Balance requests, and Identity requests. A login attempt is conducted during the initial Item add in Link. If there is not enough traffic to accurately calculate an institution's status, Plaid will return null rather than potentially inaccurate data.

Institution status is accessible in the Dashboard and via the API using the /institutions/get_by_id endpoint with the include_status option set to true. Note that institution status is not available in the sandbox environment.

Institution status example

"status": {
  "item_logins": {
    "status": "HEALTHY",
    "last_status_change": "2019-02-15T15:53:00Z",
    "breakdown": {
      "success": 0.90,
      "error_plaid": 0.01,
      "error_institution": 0.09
    }
  },
  "transactions_updates": {
    "status": "HEALTHY",
    "last_status_change": "2019-02-12T08:22:00Z",
    "breakdown": {
      "success": 0.95,
      "error_plaid": 0.02,
      "error_institution": 0.03,
      "refresh_interval": "NORMAL"
  },
  "auth": {
    "status": "HEALTHY",
    "last_status_change": "2019-02-15T15:53:00Z",
    "breakdown": {
      "success": 0.91,
      "error_plaid": 0.01,
      "error_institution": 0.08
    }
  },
  "balance": {
    "status": "HEALTHY",
    "last_status_change": "2019-02-15T15:53:00Z",
    "breakdown": {
      "success": 0.89,
      "error_plaid": 0.02,
      "error_institution": 0.09
    }
  },
  "identity": {
    "status": "DEGRADED",
    "last_status_change": "2019-02-15T15:50:00Z",
    "breakdown": {
      "success": 0.42,
      "error_plaid": 0.08,
      "error_institution": 0.50
    }
  }
}
Item logins status schema
FieldDescription
status
String		One of the following three values:
- HEALTHY: the majority of requests are successful
- DEGRADED: only some requests are successful
- DOWN: all requests are failing
last_status_change
String		 ISO 8601 timestamp of the last status change for the institution.
breakdown
Object		A detailed breakdown of the institution's performance for Item logins. View schema.
Item logins breakdown status schema

The following breakdown rates add up to 1 and are returned as decimals.

FieldDescription
success
Number		Proportion of Item logins that were successful.
error_plaid
Number		Proportion of Item logins that are failing due to an internal Plaid issue.
error_institution
Number		Proportion of Item logins that are failing due to an issue in the institution's system.

Link proactively lets users know if an institution's connection isn't performing well. Below are the three views a user will see depending on the status of the institution they select.

When the status of item_logins of an institution is DEGRADED, Link will warn users that they may experience issues and allow them to continue. Once the status of item_logins becomes DOWN, Link will block users from attempting to login and suggest they find another bank.

Institution status in Link

Transactions updates status schema
FieldDescription
status
String		One of the following three values:
- HEALTHY: the majority of updates are successful
- DEGRADED: only some updates are successful
- DOWN: all updates are failing
last_status_change
String		 ISO 8601 timestamp of the last status change for the institution.
breakdown
Object		A detailed breakdown of the institution's performance for Transactions updates. View schema.
Transactions updates breakdown status schema

The success, error_plaid, and error_institution breakdown rates add up to 1 and are returned as decimals.

FieldDescription
refresh_interval
String		One of the following three values:
- NORMAL
- DELAYED
- STOPPED

The refresh_interval may be DELAYED or STOPPED even when the success rate is high.
success
Number		Proportion of Transactions updates that were successful.
error_plaid
Number		Proportion of Transactions updates that failed due to an internal Plaid issue.
error_institution
Number		Proportion of Transactions updates that failed due to an issue in the institution's system.
Auth status schema
FieldDescription
status
String		One of the following three values:
- HEALTHY: the majority of requests are successful
- DEGRADED: only some requests are successful
- DOWN: all requests are failing
last_status_change
String		 ISO 8601 timestamp of the last status change for the institution.
breakdown
Object		A detailed breakdown of the institution's performance for Auth requests. View schema.
Auth breakdown status schema

The success, error_plaid, and error_institution breakdown rates add up to 1 and are returned as decimals.

FieldDescription
success
Number		Proportion of Auth requests that are successful.
error_plaid
Number		Proportion of Auth requests that are failing due to an internal Plaid issue.
error_institution
Number		Proportion of Auth requests that are failing due to an issue in the institution's system.
Balance status schema
FieldDescription
status
String		One of the following three values:
- HEALTHY: the majority of requests are successful
- DEGRADED: only some requests are successful
- DOWN: all requests are failing
last_status_change
String		 ISO 8601 timestamp of the last status change for the institution.
breakdown
Object		A detailed breakdown of the institution's performance for Balance requests. View schema.
Balance breakdown status schema

The success, error_plaid, and error_institution breakdown rates add up to 1 and are returned as decimals.

FieldDescription
success
Number		Proportion of Balance requests that are successful.
error_plaid
Number		Proportion of Balance requests that are failing due to an internal Plaid issue.
error_institution
Number		Proportion of Balance requests that are failing due to an issue in the institution's system.
Identity status schema
FieldDescription
status
String		One of the following three values:
- HEALTHY: the majority of requests are successful
- DEGRADED: only some requests are successful
- DOWN: all requests are failing
last_status_change
String		 ISO 8601 timestamp of the last status change for the institution.
breakdown
Object		A detailed breakdown of the institution's performance for Identity requests. View schema.
Identity breakdown status schema

The success, error_plaid, and error_institution breakdown rates add up to 1 and are returned as decimals.

FieldDescription
success
Number		Proportion of Identity requests that are successful.
error_plaid
Number		Proportion of Identity requests that are failing due to an internal Plaid issue.
error_institution
Number		Proportion of Identity requests that are failing due to an issue in the institution's system.

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.

All Categories request

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

Sandbox

Creating Items in the Sandbox

You can create Items in the Sandbox via Link or programmatically via the API. In both cases, make sure that your server-side integration is configured to make requests to the Sandbox API environment.

Sandbox API host

https://sandbox.plaid.com

To use Link in the Sandbox, initialize Link with the env parameter set to sandbox. Then select any institution and use one of the test credentials.

Programmatically

You can also create Items in the Sandbox environment without using Link. Use the /sandbox/public_token/create endpoint to create a valid public_token for an arbitrary institution ID, initial products, and test credentials. 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
FieldRequired?Description
institution_id
String		Yes
client_id
String		Yes
secret
String		Yes
initial_products
[String]		YesThe products to initially pull for the Item. May be any products that the specified institution_id supports.
options
Object, optional		NoIf provided, must be non-null.

The following options are available:

FieldDefaultDescription
webhook
String		Specify a webhook to associate with the new Item.
override_username
String		 user_good Test username to use for the creation of the Sandbox item.
override_password
String		 pass_good Test password to use for the creation of the Sandbox 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, exchangeResponse) {
    // 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 '{
  "client_id": String,
  "secret": 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": "public-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d",
  "request_id": "m8MDnv9okwxFNBV"
}

Test credentials: user_custom

Each institution in the Sandbox works with Plaid's test credentials. These special credentials allow you to simulate successful requests, requests that require various types of MFA, and failed requests. We recommend using the user_custom test credential as it gives you both flexible item configurations and realistic-looking data.

With user_custom as the username, you can use a JSON password conforming to a schema that allows you to configure behavior and traits of the item. If the password is not valid stringified JSON or does not conform to the schema, an error will be returned. The example below shows how you can create sandbox items programmatically in this way using one of our client libraries.

user_custom example

// Generate a public_token for an Item with customized accounts
client.sandboxPublicTokenCreate(INSTITUTION_ID, INITIAL_PRODUCTS, {
  override_username: 'user_custom',
  override_password: JSON.stringify({
    override_accounts: [{
      starting_balance: 10000,
      type: "depository",
      subtype: "checking",
      meta: {
        name: "Checking Name 1"
      }
    }, {
      starting_balance: 20000,
      type: "depository",
      subtype: "savings",
      meta: {
        name: "Savings Name 2"
      }
    }]
  })
}, function(err, createResponse) {
  // Handle error, if present
  var publicToken = createResponse.public_token;
});


curl -X POST https://sandbox.plaid.com/sandbox/public_token/create \
-H 'Content-Type: application/json' \
-d '{
  "client_id": "CLIENT_ID",
  "secret": "SECRET",
  "institution_id": "ins_109508",
  "initial_products": ["transactions"],
  "options": {
    "override_username": "user_custom",
    "override_password": "{\"override_accounts\":[{\"starting_balance\":10000,\"type\":\"depository\",\"subtype\":\"checking\"}]}"
  }
}'


# Generate a public_token for an Item with customized accounts
create_response = client.sandbox.sandbox_public_token.create(
  institution_id: SANDBOX_INSTITUTION,
  initial_products: ['transactions'],
  override_username: 'user_custom',
  override_password: '{"override_accounts":[{"starting_balance":10000,"type":"depository","subtype":"checking","meta":{"name":"Checking Name 1"}},{"starting_balance":20000,"type":"depository","subtype":"savings","meta":{"name":"Savings Name 2"}}]}'
)


curl -X POST https://sandbox.plaid.com/sandbox/public_token/create \
-H 'Content-Type: application/json' \
-d '{
  "client_id": "CLIENT_ID",
  "secret": "SECRET",
  "institution_id": "ins_109508",
  "initial_products": ["transactions"],
  "options": {
    "override_username": "user_custom",
    "override_password": "{\"override_accounts\":[{\"starting_balance\":10000,\"type\":\"depository\",\"subtype\":\"checking\"}]}"
  }
}'


# Generate a public_token for an Item with customized accounts
create_response = \
    client.Sandbox.public_token.create(
        INSTITUTION_ID,
        ['transactions'],
        {
            override_username: 'user_custom',
            override_password: '{"override_accounts":[{"starting_balance":10000,"type":"depository","subtype":"checking","meta":{"name":"Checking Name 1"}},{"starting_balance":20000,"type":"depository","subtype":"savings","meta":{"name":"Savings Name 2"}}]}'
        }
    )

Below are username/password combination examples for some typical scenarios.

Creating an item with randomized account and transaction data

By passing through an empty json object as the password alongside the username user_custom, an item will be randomly created using the default configuration. Accounts and transactions will be generated randomly, while other products will return either fixed or empty data. Reference the documentation below on how to configure these products. At present, not all products are configurable in the custom sandbox but support will be coming soon.


username: user_custom
password: {}
Creating an item with a seed

By passing a seed, you can ensure that accounts and transactions are deterministic. This can be helpful for consistency during integration tests. For transactions - they will be deterministic relative to date of item creation.

Note: determinism is loosely guaranteed and may not hold if the item is configured with certain traits such as a monthly inflow model that breaks determinism relative to item creation date.


username: user_custom
password: { "seed": "some seed" }
Configuring account balances

Account balances on a sandbox item will update as time passes taking into account new transactions posted into the account. However, it is possible to configure the starting balance of an account:


username: user_custom
password:  {
  "override_accounts": [
    {
      "type": "depository",
      "subtype": "checking",
      "starting_balance": 1000
    }
  ]
}

By default the available balance is computed depending on the account type. However for testing purposes you can force the available balance of an account to be fixed at a given value.


username: user_custom
password:  {
  "override_accounts": [
    {
      "type": "credit",
      "subtype": "credit card",
      "force_available_balance": 555
    }
  ]
}
Configuring the /auth/get response

You can override account numbers as well as other pieces account information for an account.

Note: some account numbers go through validation before the item is created. If the account numbers specified do not pass validation an error will be returned on item creation.


username: user_custom
password: {
  "override_accounts": [
    {
      "type": "depository",
      "subtype": "checking",
      "currency": "CAD",
      "meta": {
        "name": "My Checking",
        "official_name": "Plaid Bank Checking Plus"
      },
      "numbers": {
        "account": "123456333",
        "ach_routing": "011401533",
        "ach_wire_routing": "021000021"
      }
    },
    {
      "type": "credit",
      "subtype": "credit card",
      "meta": {
        "limit": 10000
      }
    }
  ]
}
Configuring the /transactions/get response

Transactions are produced at random based on the account type and subtype. Although we are not yet able to generate transactions for all possible account type/subtypes - most depository and credit account types are supported. If you find that you need to test specific transactions on an account with a specific type, or if you want fine-grained control over the transactions present in an account, then you can pass through a list of transactions.

Note: some account types do not support transactions and will not return any transactions even when using this configuration.


username: user_custom
password: {
  "override_accounts": [
    {
      "type": "depository",
      "subtype": "checking",
      "transactions": [
        {
          "date_transacted": "2019-10-01",
          "date_posted": "2019-10-03",
          "currency": "USD",
          "amount": 100,
          "description": "1 year Netflix subscription"
        },
        {
          "date_transacted": "2019-10-01",
          "date_posted": "2019-10-02",
          "currency": "USD",
          "amount": 100,
          "description": "1 year mobile subscription"
        }
      ]
    }
  ]
}
Configuring the /identity/get response

By default, a hardcoded list of identity information (account owner addresses, emails, names, phone numbers etc.) will be returned when the identity product is requested for a custom sandbox item. This identity information will be duplicated across each account.

You can override the identity information returned for each account.


username: user_custom
password: {
  "override_accounts": [
    {
      "type": "depository",
      "subtype": "checking",
      "identity": {
        "names": [
          "John Doe"
        ],
        "phone_numbers": [
          {
            "primary": true,
            "type": "home",
            "data": "4673956022"
          }
        ],
        "emails": [
          {
            "primary": true,
            "type": "primary",
            "data": "accountholder0@example.com"
          }
        ],
        "addresses": [
          {
            "primary": true,
            "data": {
              "city": "Malakoff",
              "region": "NY",
              "street": "2992 Cameron Road",
              "postal_code": "14236",
              "country": "US"
            }
          }
        ]
      }
    }
  ]
}
Configuring the /liabilities/get response for credit liabilities

For supported credit liability account types you can specify APR information that is used to calculate interest charges. You can simulate payments by specifying the appropriate inflow_model. As a simplification there is no grace period, interest will accrue daily and only the purchase_apr will be used for interest charge calculations.


username: user_custom
password: {
  "override_accounts": [
    {
      "type": "credit",
      "subtype": "credit card",
      "starting_balance": 10000,
      "inflow_model": {
        "type": "monthly-interest-only-payment",
        "payment_day_of_month": 15,
        "statement_day_of_month": 13,
        "transaction_name": "Interest Payment"
      },
      "liability": {
        "type": "credit",
        "purchase_apr": 12.9,
        "balance_transfer_apr": 15.24,
        "cash_apr": 28.45,
        "special_apr": 0,
        "last_payment_amount": 500,
        "last_statement_balance": 300,
        "minimum_payment_amount": 10
      }
    }
  ]
}
Configuring the /liabilities/get response for student loan liabilities

Any user_custom student loan account will support the /liabilities/get endpoint. By default a standard student loan will be generated. You can override the parameters using the liability field.


username: user_custom
password: {
  "override_accounts": [
    {
      "type": "loan",
      "subtype": "student",
      "liability": {
        "type": "student",
        "origination_date": "2020-01-01",
        "principal": 10000,
        "nominal_apr": 6.25,
        "loan_name": "Plaid Student Loan",
        "repayment_model": {
          "type": "standard",
          "non_repayment_months": 12,
          "repayment_months": 120
        }
      }
    }
  ]
}
Configuring the /asset_report/get and /asset_report/pdf/get responses

Asset reports contain a snapshot of an item's accounts, transactions and identity information. Therefore it is possible to configure asset reports by providing a combination of the fields used in the examples above.

Testing MFA

Use the mfa field to configure the MFA flow upon Item creation. For example, device MFA:


username: user_custom
password: { "mfa": { "type": "device" } }
Testing reCAPTCHA

You may trigger a reCAPTCHA in Plaid Link in the Sandbox environment by using the recaptcha field. Possible values are good or bad, both values will trigger a reCAPTCHA, a value of good will result in successful Item creation and bad will result in a RECAPTCHA_BAD error to simulate a failed reCAPTCHA. Both values require a reCAPTCHA to be manually solved within Plaid Link.


username: user_custom
password: { "recaptcha": "good" }

username: user_custom
password: { "recaptcha": "bad" }
Testing errors

You can force a subset of errors upon item creation using the force_error field. Please see the sandbox overridable errors list for a list of errors that can be simulated.


username: user_custom
password: { "force_error": "INSTITUTION_NOT_RESPONDING" }
Custom sandbox full JSON password schema
KeyDescription
version
Number, optional		Version of the schema, either 1 or 2. Defaults to the latest version. We recommend setting this for integration testing.
seed
String, optional		The seed that will be used to randomly generate the Item. This is a freeform string.
override_accounts
Array, optional		A list of account overrides to configure the accounts for the item. View schema.
mfa
Object, optional		Determines the MFA flow that will be used for this Item on creation. View possible values.
recaptcha
Object, optional		Prompts for reCAPTCHA during Item creation. View possible values
force_error
String, optional		Force an error on item creation. View possible values.

Note: the maximum utf-8 encoded byte size for JSON passwords is 2MB, INVALID_CREDENTIALS will be returned if this limit is exceeded.

override_accounts schema
KeyDescription
type
String, required		This will be used as the account type.
subtype
String, required		This will be used as the account subtype.
starting_balance
Number, optional		If provided, the account will start with this amount as the current_balance.
force_available_balance
Number, optional		If provided, the account will always have this amount as its available_balance, regardless of current balance or changes in transactions over time.
currency
String, optional		ISO-4217 currency code. If provided, the account will be denominated in the given currency. Transactions will also be in this currency by default.
meta
Object, optional		If provided, the metadata for this account will be overriden. View schema.
numbers
Object, optional		Allows overriding account numbers. View schema.
transactions
Array, optional		Specify the list of transactions on the account. View schema.
identity
Object, optional		Specify the identity metadata for the account. View schema.
liability
Object, optional		Allows overriding liability data. View schema.
inflow_model
Object, optional		If provided, the inflow model used by this account will be overridden. View schema.
meta schema
KeyDescription
name
String, optional		This will be used as the account’s name.
official_name
String, optional		This will be used as the account’s official name.
limit
Number, optional		This will be used as the account’s limit.
numbers schema
KeyDescription
account
String, optional		Will be used for the account number.
ach_routing
String, optional		Must be a valid ACH routing number.
ach_wire_routing
String, optional		Must be a valid ACH routing number.
eft_institution
String, optional		EFT institution number. Must be specified alongside eft_branch.
eft_branch
String, optional		EFT branch number. Must be specified alongside eft_institution.
international_bic
String, optional		Bank identifier code (BIC). Must be specified alongside international_iban.
international_iban
String, optional		International bank account number (IBAN). Will also be used as the account number by default. Must be specified alongside international_bic.
bacs_sort_code
String, optional		BACS sort code.
transactions schema
KeyDescription
date_transacted
String, required		Must be an ISO8601 date. The transaction date.
date_posted
String, required		Must be an ISO8601 date. The posted date.
amount
Number, required		The transaction amount. Can be negative.
description
String, required		The transaction description.
currency
String, optional		ISO-4217 currency code. Currency for the transaction.
identity schema
KeyDescription
names
Array, required		A list of names associated with the account.
phone_numbers
Array, optional		A list of phone numbers associated with the account. View schema
emails
Array, optional		A list of emails associated with the account. View schema
addresses
Array, optional		A list of physical addresses associated with the account. View schema
identity.phone_numbers schema
KeyDescription
primary
Boolean, required		Flag that indicates whether or not it is primary.
type
String, required		One of home, work, office, mobile, other.
data
String, required		The phone number value.
identity.emails schema
KeyDescription
primary
Boolean, required		Flag that indicates whether or not it is primary.
type
String, required		One of primary, secondary, other.
data
String, required		The email address value.
identity.addresses schema
KeyDescription
primary
Boolean, required		Flag that indicates whether or not it is primary.
data.country
String, required		The address country.
data.city
String, required		The address city.
data.street
String, required		The address street.
data.postal_code
String, optional		The address postal code.
data.region
String, optional		The address region.
liability schema

The liability field accepts a set of possible objects, discriminated by the type field.

KeyDescription
type
String, required		The type of the liability, either credit or student.

The following fields are applicable to type=credit, which configures the /liabilities/get response for supported credit accounts types.

KeyDescription
type
String, required		 credit
purchase_apr
Number, optional		The purchase apr percentage value. For simplicity, this is the only interest rate used to calculate interest charges.
cash_apr
Number, optional		The cash apr percentage value.
balance_transfer_apr
Number, optional		The balance transfer apr percentage value.
special_apr
Number, optional		The special apr percentage value.
last_payment_amount
Number, optional		Override the last_payment_amount field.
last_statement_balance
Number, optional		Override the last_statement_balance field.
minimum_payment_amount
Number, optional		Override the minimum_payment_amount field.
is_overdue
Boolean, optional		Override the is_overdue field.

The following fields are applicable to type=student, which configure how the student loan account is generated for the /liabilities/get response.

KeyDescription
type
String, required		 student
origination_date
Date, optional		The loan origination date.
principal
Number, optional		The original loan principal.
nominal_apr
Number, optional		The interest rate on the loan as a percentage.
interest_capitalization_grace_period_months
Number, optional		If set, interest capitalization begins at the given number of months after loan origination. By default interest is never capitalized.
repayment_model
Object, optional		Configure the model used for repayments. By default it is a standard student loan with a 3 year non-repayment period followed by a 10 year repayment plan. View schema
expected_payoff_date
Date, optional		Override the expected_payoff_date field.
guarantor
String, optional		Override the guarantor field.
is_federal
Boolean, optional		Override the is_federal field.
is_overdue
Boolean, optional		Override the is_overdue field.
loan_name
String, optional		Override the loan_name field.
loan_status
Object, optional		Override the loan_status field. View schema.
minimum_payment_amount
Number, optional		Override the minimum_payment_amount field.
payment_reference_number
String, optional		Override the payment_reference_number field.
pslf_status
Object, optional		Override the pslf_status field. View schema.
repayment_plan_description
String, optional		Override the repayment_plan.description field.
repayment_plan_type
String, optional		Override the repayment_plan.type field. Use one of the possible type values in this schema.
sequence_number
Number, optional		Override the sequence_number and field.
servicer_address
Object, optional		Override the servicer_address field. View schema.
student loan repayment model schema

Currently, only the type=standard repayment model is supported.

KeyDescription
type
String, required		 standard
non_repayment_months
Number, required		Configures the number of months before repayment starts.
repayment_months
Number, required		Configures the number of months of repayments before the loan is paid off.
inflow_model schema

The inflow_model field accepts a set of possible objects, discriminated by the type field.

KeyDescription
type
String, required		Inflow model, either none, monthly-income, monthly-balance-payment or monthly-interest-only-payment.

No additional fields are required for type=none, where no inflows will be applied to the account.

The following fields are applicable to type=monthly-income, which models income at a certain point in time each month.

KeyDescription
type
String, required		 monthly-income
income_amount
Number, required		Amount of income per month.
payment_day_of_month
Number or String, required		Number between 1 and 28, or last meaning the last day of the month. The day of the month on which the income transaction will appear.
transaction_name
String, required		The name of the income transaction.

The following fields are applicable to type=monthly-balance-payment, which pays off the balance on a liability account at the given statement day of month.

KeyDescription
type
String, required		 monthly-balance-payment
statement_day_of_month
Number or String, required		Number between 1 and 28, or last meaning the last day of the month. The day of the month on which the balance is calculated for the next payment.
payment_day_of_month
Number or String, required		Number between 1 and 28, or last meaning the last day of the month. The day of the month on which the payment transaction will appear.
transaction_name
String, required		The name of the payment transaction.

The following fields are applicable to type=monthly-interest-only-payment, which will pay the any interest accrued on a liability account every month. Note that only account types that support the credit liabilities product will accrue interest in the sandbox.

KeyDescription
type
String, required		 monthly-interest-only-payment
statement_day_of_month
Number or String, required		Number between 1 and 28, or last meaning the last day of the month. The day of the month on which the balance is calculated for the next payment.
payment_day_of_month
Number or String, required		Number between 1 and 28, or last meaning the last day of the month. The day of the month on which the payment transaction will appear.
transaction_name
String, required		The name of the payment transaction.
mfa schema

The mfa field accepts a set of possible objects, discriminated by the type field.

KeyDescription
type
String, required		Must be set to device, questions, or selections.

No additional fields are required for type=device, the correct answer is 1234 for device MFA.

The following fields are applicable to type=questions. The correct answer to each question is answer_<i>_<j> for the j-th question in the i-th round, starting from 0.

KeyDescription
type
String, required		 questions
question_rounds
Number, required		Number of rounds of questions.
questions_per_round
Number, required		Number of questions per round.

The following fields are applicable to type=selections. The correct selection is always the first answer for each question.

KeyDescription
type
String, required		 selections
selection_rounds
Number, optional		Number of rounds of selections. Defaults to 1.
questions_per_round
Number, optional		Number of questions per round. Defaults to 2.
selections_per_question
Number, optional		Number available answers per question. Defaults to 2.
recaptcha schema

The following values are available to supply along with recaptcha to test the reCAPTCHA flow in Plaid Link.

KeyDescription
good
String, required		Will trigger a reCAPTCHA in Plaid Link and result in a successful Item add.
bad
String, required		Will trigger a reCAPTCHA in Plaid Link and return a RECAPTCHA_BAD error response.
Sandbox overridable errors

The following errors are supported when using either error_ERROR_CODE alongside user_good or the force_error field alongside user_custom to trigger an error in the sandbox.


"INSTITUTION_DOWN"
"INSTITUTION_NOT_AVAILABLE"
"INSTITUTION_NOT_RESPONDING"
"INSTITUTION_NO_LONGER_SUPPORTED"
"INVALID_CREDENTIALS"
"INVALID_LINK_TOKEN"
"INVALID_MFA"
"ITEM_LOCKED"
"ITEM_LOGIN_REQUIRED"
"ITEM_NOT_SUPPORTED"
"MFA_NOT_SUPPORTED"
"NO_ACCOUNTS"
"PLAID_ERROR"
"PRODUCTS_NOT_SUPPORTED"
"USER_SETUP_REQUIRED"
Custom Sandbox users BETA

You can now save the JSON passwords used with user_custom by creating Custom Sandbox users in the Dashboard. A Sandbox user maps a username of your choosing to your custom JSON configuration. Then, when creating Items, use the saved username as credentials to create an Item with the corresponding configuration.

Notes:

  • When using Sandbox users to create an Item, only the username matters. Any non-empty password is accepted.
  • Configurations saved in the dashboard are currently not guaranteed to be fully valid. If this happens, INVALID_CREDENTIALS will be returned when creating an Item.

Test credentials: user_good

An older method of creating items in the sandbox exists by using the username user_good. This gives you some limited control over sandbox item creation flow, however it is not as flexible as the custom sandbox as item details such as accounts and transactions are hardcoded.

Testing the default flow

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

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

PasswordNotes
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
Testing Auth

You can trigger specific Auth flows by using the following credentials:

StepInstant
Match		Automated
Micro-deposits		Same Day
Micro-deposits
InstitutionHoundstooth BankHoundstooth BankN/A
Username user_good user_good N/A
Password pass_good microdeposits_good N/A
Account Plaid Saving (****1111) Plaid Checking (****0000) Checking or Savings
Routing number 011401533 011401533 011401533
Account number 1111222233331111 1111222233330000 1111222233330000
Micro-deposit #1N/AN/A $0.01
Micro-deposit #2N/AN/A $0.02
Sandbox timelineInstantApproximately 6 hoursVerify within minutes
Testing errors

You can trigger a subset of errors that you would typically receive when creating an Item. Do so by using username user_good and modifying the password: 


username: user_good
password: error_ERROR_CODE // ex: error_INVALID_CREDENTIALS

Integration tests

All institutions that are available in our Development and Production environments are available in our Sandbox. There are six supported Sandbox-only Institutions that are suitable to write integration tests against:

NameID
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

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.

FieldRequired?
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 and use it to
  // initialize Link in update mode.
  client.createPublicToken(access_token, function(err, public_token_response) {
    // Handle err
  });
});


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

Firing webhooks

Webhooks are fired for different Item lifecycle events such as when new transaction data is available. The /sandbox/item/fire_webhook endpoint enables testing these events on demand.

Fire webhook request

POST /sandbox/item/fire_webhook
FieldRequired?
client_id
String		Yes
secret
String		Yes
access_token
String		Yes
webhook_code
String		Yes

The following webhook_codes are supported:

Webhook code
DEFAULT_UPDATE
Fire webhook request

  // Fire a DEFAULT_UPDATE webhook for an Item
  client.sandboxItemFireWebhook(access_token, 'DEFAULT_UPDATE', function(err, fire_webhook_response) {
    // Handle err, if present
  });
  

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

  # fire a DEFAULT_UPDATE webhook for an item
  client.sandbox.sandbox_item.fire_webhook(
    access_token,
    'DEFAULT_UPDATE'
  )
  

  // fire a DEFAULT_UPDATE webhook for an Item
  Response<SandboxItemFireWebhookResponse> response = client().service().sandboxItemFireWebhook(
    new SandboxItemFireWebhookRequest(ACCESS_TOKEN, "DEFAULT_UPDATE")
  ).execute();
  

  # fire a DEFAULT_UPDATE webhook for an item
  client.Sandbox.item.fire_webhook(access_token, 'DEFAULT_UPDATE')
Fire webhook response

  http code 200
  {
    "webhook_fired": true,
    "request_id": "1vwmF5TBQwiqfwP"
  }

In order to test webhooks fired for Automated Microdeposits, you first will need to create an Item through Link and then use the /sandbox/item/set_verification_status endpoint to trigger the webhook

Set Verification Status

POST /sandbox/item/set_verification_status
FieldRequired?
client_id
String		Yes
secret
String		Yes
access_token
String		Yes
account_id
String		Yes
verification_status
"automatically_verified" or "verification_expired"		Yes
Set verification status request

  // Set the verification_status for an Item created using Automated Microdeposits, triggering a webhook
  client.sandboxItemSetVerificationStatus(access_token, account_id, 'automatically_verified', function(err, response) {
    // Handle err, if present
  });
  

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

  # Set the verification_status for an Item created using Automated Microdeposits, triggering a webhook
  response = client.sandbox.sandbox_item.set_verification_status(
    access_token,
    account_id,
    'automatically_verified'
  )
  

  // Set the verification_status for an Item created using Automated Microdeposits, triggering a webhook
  Response<SandboxItemSetVerificationStatusResponse> response = client.service()
    .sandboxItemSetVerificationStatus(new SandboxItemSetVerificationStatusRequest(
      accessToken,
      accountId,
      "automatically_verified",
    )
  ).execute();
  

  # Set the verification_status for an Item created using Automated Microdeposits, triggering a webhook
  response = client.Sandbox.item.set_verification_status(access_token, account_id, "automatically_verified")
Set verification status response

  http code 200
  {
    "request_id": "1vwmF5TBQwiqfwP"
  }

We use cookies to improve your experience and our websites. By using this site, you agree to the use of cookies as described in our Cookie Policy.