Docs - Plaid

Overview

Introduction

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

Product	Endpoint
Auth	POST /auth/get
Transactions	POST /transactions/get
Identity	POST /identity/get
Income	POST /income/get
Balance	POST /accounts/balance/get
Assets	POST /assets/get
Investments	POST /investments/holdings/get POST /investments/transactions/get
Liabilities	POST /liabilities/get

Glossary

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

API keys and access

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

API protocols

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

API host

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	`/item/public_token/exchange` `/item/public_token/create`
Item management	`/accounts/get` `/item/get` `/item/webhook/update` `/item/access_token/invalidate` `/item/remove`
Product access	`/auth/get` `/transactions/get` `/accounts/balance/get` `/identity/get` `/income/get` `/asset_report/get` `/asset_report/pdf/get` `/investments/holdings/get` `/investments/transactions/get`
Report management	`/asset_report/create` `/asset_report/remove` `/asset_report/audit_copy/create` `/asset_report/audit_copy/remove`
Institutions	`/institutions/get` `/institutions/get_by_id` `/institutions/search`
Categories	`/categories/get`

Versioning

We periodically release new, dated versions of the API whenever we make breaking changes. The current version is 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 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.

          
var plaid = require('plaid');

var plaidClient = new plaid.Client(
  PLAID_CLIENT_ID,
  PLAID_SECRET,
  PLAID_PUBLIC_KEY,
  plaid.environments.sandbox,
  {
    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,
                           public_key: PLAID_PUBLIC_KEY)

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

          
from plaid import Client

client = Client(
    client_id=PLAID_CLIENT_ID,
    secret=PLAID_SECRET,
    public_key=PLAID_PUBLIC_KEY,
    environment='sandbox',
    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.

access_token

Included in any response that successfully creates an Item.

"access_token": "access-sandbox-5cd6e1b1-1b5b-459d-9284-366e2da89755"

item_id

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

"item_id": "Jv785paMV8hRGWNBRjbjUybw8N9B3yTBDdkwV"

asset_report_token

Included in any response that successfully creates an Asset Report.

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

asset_report_id

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

"asset_report_id": "1f414183-220c-44f5-b0c8-bc0e6d4053bb"

Log API request identifiers

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

request_id

Included in all Plaid API success and error responses.

"request_id": "m8MDnv9okwxFNBV"

link_session_id

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

"link_session_id": "f6e63556-7ed9-4d98-b6b1-bfc9f0473593"

Retrieve transaction or account ids

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

account_id

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

"account_id": "yL8je73GrjTZogRqZLrLHLaX3Kb8a1s5z6Jlg"

transaction_id

Included in successful responses for Plaid’s Transactions product.

"transaction_id": "ZXmN54gvBNIJq1aPJrGrFjGg8VJB36IzeWayW"

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.

Creating Items with Plaid Link

Integrating with Link

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.

Note: If you want to initialize Link for European countries, you must specify a European country code using the ISO-3166-1 alpha-2 standard. This will also require the European consent panel to display to end users during item add flows.

          
<button id="link-button">Link Account</button>
<script src="https://cdnjs.cloudflare.com/ajax/libs/jquery/2.2.3/jquery.min.js"></script>
<script src="https://cdn.plaid.com/link/v2/stable/link-initialize.js"></script>
<script type="text/javascript">
(function($) {
  var handler = Plaid.create({
    clientName: 'Plaid Quickstart',
    // Optional, specify an array of ISO-3166-1 alpha-2 country
    // codes to initialize Link; European countries will have GDPR
    // consent panel
    countryCodes: ['US'],
    env: 'sandbox',
    // Replace with your public_key from the Dashboard
    key: 'PUBLIC_KEY',
    product: ['transactions'],
    // Optional, use webhooks to get transaction and error updates
    webhook: 'https://requestb.in',
    // Optional, specify a language to localize Link
    language: 'en',
    // Optional, specify userLegalName and userEmailAddress to
    // enable all Auth features
    userLegalName: 'John Appleseed',
    userEmailAddress: 'jappleseed@yourapp.com',
    onLoad: function() {
      // Optional, called when Link loads
    },
    onSuccess: function(public_token, metadata) {
      // Send the public_token to your app server.
      // The metadata object contains info about the institution the
      // user selected and the account ID or IDs, if the
      // Select Account view is enabled.
      $.post('/get_access_token', {
        public_token: public_token,
      });
    },
    onExit: function(err, metadata) {
      // The user exited the Link flow.
      if (err != null) {
        // The user encountered a Plaid API error prior to exiting.
      }
      // metadata contains information about the institution
      // that the user selected and the most recent API request IDs.
      // Storing this information can be helpful for support.
    },
    onEvent: function(eventName, metadata) {
      // Optionally capture Link flow events, streamed through
      // this callback as your users connect an Item to Plaid.
      // For example:
      // eventName = "TRANSITION_VIEW"
      // metadata  = {
      //   link_session_id: "123-abc",
      //   mfa_type:        "questions",
      //   timestamp:       "2017-09-14T14:42:19.350Z",
      //   view_name:       "MFA",
      // }
    }
  });

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


<button id="link-button">Link Account</button>
<script src="https://cdnjs.cloudflare.com/ajax/libs/jquery/2.2.3/jquery.min.js"></script>
<script src="https://cdn.plaid.com/link/v2/stable/link-initialize.js"></script>
<script type="text/javascript">
(function($) {
  var handler = Plaid.create({
    clientName: 'Plaid Quickstart',
    // Optional, specify an array of ISO-3166-1 alpha-2 country
    // codes to initialize Link; European countries will have GDPR
    // consent panel
    countryCodes: ['US'],
    env: 'sandbox',
    // Replace with your public_key from the Dashboard
    key: 'PUBLIC_KEY',
    product: ['transactions'],
    // Optional, use webhooks to get transaction and error updates
    webhook: 'https://requestb.in',
    // Optional, specify a language to localize Link
    language: 'en',
    // Optional, specify userLegalName and userEmailAddress to
    // enable all Auth features
    userLegalName: 'John Appleseed',
    userEmailAddress: 'jappleseed@yourapp.com',
    onLoad: function() {
      // Optional, called when Link loads
    },
    onSuccess: function(public_token, metadata) {
      // Send the public_token to your app server.
      // The metadata object contains info about the institution the
      // user selected and the account ID or IDs, if the
      // Select Account view is enabled.
      $.post('/get_access_token', {
        public_token: public_token,
      });
    },
    onExit: function(err, metadata) {
      // The user exited the Link flow.
      if (err != null) {
        // The user encountered a Plaid API error prior to exiting.
      }
      // metadata contains information about the institution
      // that the user selected and the most recent API request IDs.
      // Storing this information can be helpful for support.
    },
    onEvent: function(eventName, metadata) {
      // Optionally capture Link flow events, streamed through
      // this callback as your users connect an Item to Plaid.
      // For example:
      // eventName = "TRANSITION_VIEW"
      // metadata  = {
      //   link_session_id: "123-abc",
      //   mfa_type:        "questions",
      //   timestamp:       "2017-09-14T14:42:19.350Z",
      //   view_name:       "MFA",
      // }
    }
  });

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


<button id="link-button">Link Account</button>
<script src="https://cdnjs.cloudflare.com/ajax/libs/jquery/2.2.3/jquery.min.js"></script>
<script src="https://cdn.plaid.com/link/v2/stable/link-initialize.js"></script>
<script type="text/javascript">
(function($) {
  var handler = Plaid.create({
    clientName: 'Plaid Quickstart',
    // Optional, specify an array of ISO-3166-1 alpha-2 country
    // codes to initialize Link; European countries will have GDPR
    // consent panel
    countryCodes: ['US'],
    env: 'sandbox',
    // Replace with your public_key from the Dashboard
    key: 'PUBLIC_KEY',
    product: ['transactions'],
    // Optional, use webhooks to get transaction and error updates
    webhook: 'https://requestb.in',
    // Optional, specify a language to localize Link
    language: 'en',
    // Optional, specify userLegalName and userEmailAddress to
    // enable all Auth features
    userLegalName: 'John Appleseed',
    userEmailAddress: 'jappleseed@yourapp.com',
    onLoad: function() {
      // Optional, called when Link loads
    },
    onSuccess: function(public_token, metadata) {
      // Send the public_token to your app server.
      // The metadata object contains info about the institution the
      // user selected and the account ID or IDs, if the
      // Select Account view is enabled.
      $.post('/get_access_token', {
        public_token: public_token,
      });
    },
    onExit: function(err, metadata) {
      // The user exited the Link flow.
      if (err != null) {
        // The user encountered a Plaid API error prior to exiting.
      }
      // metadata contains information about the institution
      // that the user selected and the most recent API request IDs.
      // Storing this information can be helpful for support.
    },
    onEvent: function(eventName, metadata) {
      // Optionally capture Link flow events, streamed through
      // this callback as your users connect an Item to Plaid.
      // For example:
      // eventName = "TRANSITION_VIEW"
      // metadata  = {
      //   link_session_id: "123-abc",
      //   mfa_type:        "questions",
      //   timestamp:       "2017-09-14T14:42:19.350Z",
      //   view_name:       "MFA",
      // }
    }
  });

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


<button id="link-button">Link Account</button>
<script src="https://cdnjs.cloudflare.com/ajax/libs/jquery/2.2.3/jquery.min.js"></script>
<script src="https://cdn.plaid.com/link/v2/stable/link-initialize.js"></script>
<script type="text/javascript">
(function($) {
  var handler = Plaid.create({
    clientName: 'Plaid Quickstart',
    // Optional, specify an array of ISO-3166-1 alpha-2 country
    // codes to initialize Link; European countries will have GDPR
    // consent panel
    countryCodes: ['US'],
    env: 'sandbox',
    // Replace with your public_key from the Dashboard
    key: 'PUBLIC_KEY',
    product: ['transactions'],
    // Optional, use webhooks to get transaction and error updates
    webhook: 'https://requestb.in',
    // Optional, specify a language to localize Link
    language: 'en',
    // Optional, specify userLegalName and userEmailAddress to
    // enable all Auth features
    userEmailAddress: 'John Appleseed',
    userEmailAddress: 'jappleseed@yourapp.com',
    onLoad: function() {
      // Optional, called when Link loads
    },
    onSuccess: function(public_token, metadata) {
      // Send the public_token to your app server.
      // The metadata object contains info about the institution the
      // user selected and the account ID or IDs, if the
      // Select Account view is enabled.
      $.post('/get_access_token', {
        public_token: public_token,
      });
    },
    onExit: function(err, metadata) {
      // The user exited the Link flow.
      if (err != null) {
        // The user encountered a Plaid API error prior to exiting.
      }
      // metadata contains information about the institution
      // that the user selected and the most recent API request IDs.
      // Storing this information can be helpful for support.
    },
    onEvent: function(eventName, metadata) {
      // Optionally capture Link flow events, streamed through
      // this callback as your users connect an Item to Plaid.
      // For example:
      // eventName = "TRANSITION_VIEW"
      // metadata  = {
      //   link_session_id: "123-abc",
      //   mfa_type:        "questions",
      //   timestamp:       "2017-09-14T14:42:19.350Z",
      //   view_name:       "MFA",
      // }
    }
  });

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


<button id="link-button">Link Account</button>
<script src="https://cdnjs.cloudflare.com/ajax/libs/jquery/2.2.3/jquery.min.js"></script>
<script src="https://cdn.plaid.com/link/v2/stable/link-initialize.js"></script>
<script type="text/javascript">
(function($) {
  var handler = Plaid.create({
    clientName: 'Plaid Quickstart',
    // Optional, specify an array of ISO-3166-1 alpha-2 country
    // codes to initialize Link; European countries will have GDPR
    // consent panel
    countryCodes: ['US'],
    env: 'sandbox',
    // Replace with your public_key from the Dashboard
    key: 'PUBLIC_KEY',
    product: ['transactions'],
    // Optional, use webhooks to get transaction and error updates
    webhook: 'https://requestb.in',
    // Optional, specify a language to localize Link
    language: 'en',
    // Optional, specify userLegalName and userEmailAddress to
    // enable all Auth features
    userLegalName: 'John Appleseed',
    userEmailAddress: 'jappleseed@yourapp.com',
    onLoad: function() {
      // Optional, called when Link loads
    },
    onSuccess: function(public_token, metadata) {
      // Send the public_token to your app server.
      // The metadata object contains info about the institution the
      // user selected and the account ID or IDs, if the
      // Select Account view is enabled.
      $.post('/get_access_token', {
        public_token: public_token,
      });
    },
    onExit: function(err, metadata) {
      // The user exited the Link flow.
      if (err != null) {
        // The user encountered a Plaid API error prior to exiting.
      }
      // metadata contains information about the institution
      // that the user selected and the most recent API request IDs.
      // Storing this information can be helpful for support.
    },
    onEvent: function(eventName, metadata) {
      // Optionally capture Link flow events, streamed through
      // this callback as your users connect an Item to Plaid.
      // For example:
      // eventName = "TRANSITION_VIEW"
      // metadata  = {
      //   link_session_id: "123-abc",
      //   mfa_type:        "questions",
      //   timestamp:       "2017-09-14T14:42:19.350Z",
      //   view_name:       "MFA",
      // }
    }
  });

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

          
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

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

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

var client = new plaid.Client(
  'PLAID_CLIENT_ID',
  'PLAID_SECRET',
  'PLAID_PUBLIC_KEY',
  plaid.environments.sandbox
);

// Accept the public_token sent from Link
var app = express();
app.post('/get_access_token', function(request, response, next) {
  PUBLIC_TOKEN = request.body.public_token;
  client.exchangePublicToken(PUBLIC_TOKEN, function(error, tokenResponse) {
    if (error != null) {
      console.log('Could not exchange public_token!' + '\n' + error);
      return response.json({error: msg});
    }
    ACCESS_TOKEN = tokenResponse.access_token;
    ITEM_ID = tokenResponse.item_id;
    console.log('Access Token: ' + ACCESS_TOKEN);
    console.log('Item ID: ' + ITEM_ID);
    response.json({'error': false});
  });
});
app.listen(8000);
          
        
      

                  
require 'sinatra'
require 'plaid'

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

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

access_token = nil

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

                  
import 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;


public class PlaidExample {
  private static final String PUBLIC_KEY = "PLAID_PUBLIC_KEY";
  private static final String CLIENT_ID = "PLAID_CLIENT_ID";
  private static final String SECRET = "PLAID_SECRET";

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

  static class GetAccessToken implements HttpHandler {
    private static PlaidClient plaidClient;

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

      // Build your Plaid client
      PlaidClient plaidClient = PlaidClient.newBuilder()
        .clientIdAndSecret(CLIENT_ID, SECRET)
        .publicKey(PUBLIC_KEY)
        .sandboxBaseUrl() // sandbox Plaid environment
        .logLevel(HttpLoggingInterceptor.Level.BODY)
        .build();

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

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

access_token = None
public_token = None

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

    return jsonify(exchange_response)

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

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

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

Parameter reference

Parameter	Description
`clientName` required	Displayed once a user has successfully linked their `Item`.
`product` required	A list of Plaid product(s) you wish to use. Valid products are: `transactions`, `auth`, `identity`, `income`, `assets`, `investments`, and `liabilities`. Only institutions that support all requested products will be shown. In Production, you will be billed for each product that you specify when initializing Link. Example: `['auth', 'transactions']`
`key` required	The `public_key` associated with your account; available from the Dashboard.
`env` required	The Plaid API environment on which to create user accounts. For Development and Sandbox, use `development` or `sandbox`, respectively. For Production use, use `production`. Note: all Production requests are billed.
`onSuccess` required	A function that is called when a user has successfully onboarded an `Item`. The function should expect two arguments, the `public_token` and a `metadata` object.
`onExit` optional	A function that is called when a user has specifically exited the Link flow. The function should expect two arguments, a nullable `error` object and a `metadata` object. See onExit.
`onEvent` optional	A function that is called when a user reaches certain points in the Link flow. The function should expect two arguments, an `eventName` string and a `metadata` object. See onEvent.
`onLoad` optional	A function that is called when the Link module has finished loading. Calls to `plaidLinkHandler.open()` prior to the `onLoad` callback will be delayed until the module is fully loaded.
`language` optional	Specify a Plaid-supported language to localize Link. English will be used by default. Supported languages: English (`'en'`) French (`'fr'`) Spanish (`'es'`)
`countryCodes` optional	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.
`webhook` 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.
`userLegalName` optional	Specify a `userLegalName` to enable all `Auth` features. Note that `userEmailAddress` must also be set.
`userEmailAddress` optional	Specify a `userEmailAddress` to enable all `Auth` features. Note that `userLegalName` must also be set.
`token` optional	Specify a `public_token` to launch Link in update mode for a particular `Item`. This will cause Link to open directly to the authentication step for that `Item's` institution. Use the `/item/public_token/create` endpoint to generate a `public_token` for an `Item`.
`isWebview` optional	Set to `true` if launching Link within a WebView.

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

onSuccess callback

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

Parameter Description

link_session_id
String A unique identifier associated with a user's actions and events through the Link flow. Include this identifier when opening a support ticket for faster turnaround.

Parameter	Description
`link_session_id` String	A unique identifier associated with a user's actions and events through the Link flow. Include this identifier when opening a support ticket for faster turnaround.
`institution` Object	An object with two properties: `name`: The full institution name, such as 'Bank of America' `institution_id`: The institution ID, such as `ins_100000`
`accounts` [Object]	A list of objects with the following properties: `id`: the id of the selected account `name`: the name of the selected account `mask`: the last four digits of the selected account `type`: the account type `subtype`: the account subtype When all `Auth` features are enabled by initializing Link with the `user` object , the `accounts` object includes an Item's `verification_status`, with available status: `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 Checkout the Accounts section for more detailed documentation. To collect accounts data, you must enable the Select Account view via the Plaid Dashboard.

institution
Object

An object with two properties:

name: The full institution name, such as 'Bank of America'
institution_id: The institution ID, such as ins_100000

accounts
[Object]

A list of objects with the following properties:

id: the id of the selected account
name: the name of the selected account
mask: the last four digits of the selected account
type: the account type
subtype: the account subtype

When all Auth features are enabled by initializing Link with the user object , the accounts object includes an Item's verification_status, with available status:

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

Checkout the Accounts section for more detailed documentation. To collect accounts data, you must enable the Select Account view via the Plaid Dashboard.

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


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

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

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

Metadata `status`

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

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

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

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

      


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


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

onEvent callback

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

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

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

Event names

Event	Description
`ERROR`	A recoverable error occurred in the Link flow, see the `error_code` metadata.
`EXIT`	The user has exited without completing the Link flow and the `onExit` callback is fired.
`HANDOFF`	The user has completed the Link flow and the `onSuccess` callback is fired.
`OPEN`	The user has opened Link.
`OPEN_MY_PLAID`	The user has opened my.plaid.com. This event is only sent when Link is initialized with `assets` as a product
`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

Field	Description
`error_code`	The error code that the user encountered. Emitted by: `ERROR`, `EXIT`.
`error_message`	The error message that the user encountered. Emitted by: `ERROR`, `EXIT`.
`error_type`	The error type that the user encountered. Emitted by: `ERROR`, `EXIT`.
`exit_status`	The status key indicates the point at which the user exited the Link flow. Emitted by: `EXIT`.
`institution_id`	The ID of the selected institution. Emitted by: all events.
`institution_name`	The name of the selected institution. Emitted by: all events.
`institution_search_query`	The query used to search for institutions. Emitted by: `SEARCH_INSTITUTION`.
`request_id`	The request ID for the last request made by Link. This can be shared with Plaid Support to expedite investigation. Emitted by: all events.
`link_session_id`	The `link_session_id` is a unique identifier for a single session of Link. It's always available and will stay constant throughout the flow. Emitted by: all events.
`mfa_type`	If set, the user has encountered one of the following MFA types: `code`, `device`, `questions`, `selections`. Emitted by: `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`

View	Displayed when
`CONNECTED`	The user has connected their account.
`CREDENTIAL`	Asking the user for their account credentials.
`ERROR`	An error has occurred.
`EXIT`	Confirming if the user wishes to close Link.
`LOADING`	Link is making a request to our servers.
`MFA`	The user is asked by the institution for additional MFA authentication.
`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.

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

      


enum (
  "ERROR"
  "EXIT"
  "HANDOFF"
  "OPEN"
  "OPEN_MY_PLAID"
  "SEARCH_INSTITUTION"
  "SELECT_INSTITUTION"
  "TRANSITION_VIEW"
)


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

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

// Open Link
linkHandler.open();

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

// Open Link
linkHandler.open();

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

// Open Link
linkHandler.open();

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

// Open Link
linkHandler.open();

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

// Open Link
linkHandler.open();

exit() function

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Exchange Token flow

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

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

Field	Required?
`client_id` String	yes
`secret` String	yes
`public_token` String	yes

Exchange Token

POST /item/public_token/exchange


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


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


response = client.item.public_token.exchange(public_token)
access_token = response['access_token']
item_id = response['item_id']

          
Response response =
  client()
  .service()
  .itemPublicTokenExchange(new ItemPublicTokenExchangeRequest(publicToken))
  .execute();
String accessToken = response.body().getAccessToken();

          
response = client.Item.public_token.exchange(public_token)
access_token = response['access_token']
item_id = response['item_id']

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

      


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

      


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

      


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

      


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

      

Creating Public Tokens

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

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

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

Field	Required?
`client_id` String	yes
`secret` String	yes
`access_token` String	yes

Create Public Token

POST /item/public_token/create


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


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


# create a public_token for use with Plaid Link's update mode
response = client.item.public_token.create(access_token)
# use the generated public_token to initialize Plaid Link in update
# mode for a user's Item so that they can provide updated
# credentials or MFA information
public_token = response['public_token']

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

          
# create a public_token for use with Plaid Link's update mode
create_response = client.Item.public_token.create(access_token)
# use the generated public_token to initialize Plaid Link in update
# mode for a user's Item so that they can provide updated
# credentials or MFA information
public_token = response['public_token']

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

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

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

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

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

Updating Items via Link

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

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

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


<script src="https://cdn.plaid.com/link/v2/stable/link-initialize.js">
</script>
<script>
// Initialize Link with the token parameter
// set to the generated public_token for the Item
var linkHandler = Plaid.create({
  env: 'sandbox',
  clientName: 'Client Name',
  key: 'PUBLIC_KEY',
  product: ['transactions'],
  token: 'GENERATED_PUBLIC_TOKEN',
  onSuccess: function(public_token, metadata) {
    // You do not need to repeat the /item/public_token/exchange
    // process when a user uses Link in update mode.
    // The Item's access_token has not changed.
  },
  onExit: function(err, metadata) {
    // The user exited the Link flow.
    if (err != null) {
      // The user encountered a Plaid API error prior
      // to exiting.
    }
    // metadata contains the most recent API request ID and the
    // Link session ID. Storing this information is helpful
    // for support.
  }
});
// Trigger the authentication view
document.getElementById('linkButton').onclick = function() {
  // Link will automatically detect the institution ID
  // associated with the public token and present the
  // credential view to your user.
  linkHandler.open();
};
</script>


<script src="https://cdn.plaid.com/link/v2/stable/link-initialize.js">
</script>
<script>
// Initialize Link with the token parameter
// set to the generated public_token for the Item
var linkHandler = Plaid.create({
  env: 'sandbox',
  clientName: 'Client Name',
  key: 'PUBLIC_KEY',
  product: ['transactions'],
  token: 'GENERATED_PUBLIC_TOKEN',
  onSuccess: function(public_token, metadata) {
    // You do not need to repeat the /item/public_token/exchange
    // process when a user uses Link in update mode.
    // The Item's access_token has not changed.
  },
  onExit: function(err, metadata) {
    // The user exited the Link flow.
    if (err != null) {
      // The user encountered a Plaid API error prior
      // to exiting.
    }
    // metadata contains the most recent API request ID and the
    // Link session ID. Storing this information is helpful
    // for support.
  }
});
// Trigger the authentication view
document.getElementById('linkButton').onclick = function() {
  // Link will automatically detect the institution ID
  // associated with the public token and present the
  // credential view to your user.
  linkHandler.open();
};
</script>


<script src="https://cdn.plaid.com/link/v2/stable/link-initialize.js">
</script>
<script>
// Initialize Link with the token parameter
// set to the generated public_token for the Item
var linkHandler = Plaid.create({
  env: 'sandbox',
  clientName: 'Client Name',
  key: 'PUBLIC_KEY',
  product: ['transactions'],
  token: 'GENERATED_PUBLIC_TOKEN',
  onSuccess: function(public_token, metadata) {
    // You do not need to repeat the /item/public_token/exchange
    // process when a user uses Link in update mode.
    // The Item's access_token has not changed.
  },
  onExit: function(err, metadata) {
    // The user exited the Link flow.
    if (err != null) {
      // The user encountered a Plaid API error prior
      // to exiting.
    }
    // metadata contains the most recent API request ID and the
    // Link session ID. Storing this information is helpful
    // for support.
  }
});
// Trigger the authentication view
document.getElementById('linkButton').onclick = function() {
  // Link will automatically detect the institution ID
  // associated with the public token and present the
  // credential view to your user.
  linkHandler.open();
};
</script>


<script src="https://cdn.plaid.com/link/v2/stable/link-initialize.js">
</script>
<script>
// Initialize Link with the token parameter
// set to the generated public_token for the Item
var linkHandler = Plaid.create({
  env: 'sandbox',
  clientName: 'Client Name',
  key: 'PUBLIC_KEY',
  product: ['transactions'],
  token: 'GENERATED_PUBLIC_TOKEN',
  onSuccess: function(public_token, metadata) {
    // You do not need to repeat the /item/public_token/exchange
    // process when a user uses Link in update mode.
    // The Item's access_token has not changed.
  },
  onExit: function(err, metadata) {
    // The user exited the Link flow.
    if (err != null) {
      // The user encountered a Plaid API error prior
      // to exiting.
    }
    // metadata contains the most recent API request ID and the
    // Link session ID. Storing this information is helpful
    // for support.
  }
});
// Trigger the authentication view
document.getElementById('linkButton').onclick = function() {
  // Link will automatically detect the institution ID
  // associated with the public token and present the
  // credential view to your user.
  linkHandler.open();
};
</script>


<script src="https://cdn.plaid.com/link/v2/stable/link-initialize.js">
</script>
<script>
// Initialize Link with the token parameter
// set to the generated public_token for the Item
var linkHandler = Plaid.create({
  env: 'sandbox',
  clientName: 'Client Name',
  key: 'PUBLIC_KEY',
  product: ['transactions'],
  token: 'GENERATED_PUBLIC_TOKEN',
  onSuccess: function(public_token, metadata) {
    // You do not need to repeat the /item/public_token/exchange
    // process when a user uses Link in update mode.
    // The Item's access_token has not changed.
  },
  onExit: function(err, metadata) {
    // The user exited the Link flow.
    if (err != null) {
      // The user encountered a Plaid API error prior
      // to exiting.
    }
    // metadata contains the most recent API request ID and the
    // Link session ID. Storing this information is helpful
    // for support.
  }
});
// Trigger the authentication view
document.getElementById('linkButton').onclick = function() {
  // Link will automatically detect the institution ID
  // associated with the public token and present the
  // credential view to your user.
  linkHandler.open();
};
</script>

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

iOS bindings

Plaid Link WebView example

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

Looking to get started right away?

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

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


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 Link and your app

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

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

`connected` event

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

Field	Description
`public_token`	Link `public_token` that is exchanged for an API `access_token`
`accounts`	JSON-stringified representation of the account(s) selected by the user in the shape of `[Object]`. Enable the Select Account view to collect this data.
`institution_id`	The institution ID, such as `'ins_100000'`
`institution_name`	The full institution name, such as `'Bank of America'`


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

`exit` event

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

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


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

`event` event

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

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


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

WebView examples

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

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


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


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

Browser & 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

Browser		Latest supported version
Google Chrome		The current and previous version of Chrome (Windows, macOS, Linux)
Apple Safari		The current and previous version of Safari (macOS)
Mozilla Firefox		The current and previous version of Firefox (Windows, macOS, Linux)
Microsoft Internet Explorer		Internet Explorer 11 (Windows) Plaid adheres to Microsoft's lifecycle policy
Microsoft Edge		The current version of Microsoft Edge (Windows)

iOS

Platform		Latest supported version
iOS SDK (native)		· iOS 9+ · Xcode 7 or greater
WebView		· WKWebView – iOS 10+, Xcode 8 or greater · UIWebView – Not supported
Mobile Safari		Safari on current and previous major version of iOS
Chrome		Current version of Chrome for iOS

Android

Platform		Latest supported version
Chrome WebView		Chrome WebView on Android 4.4+
Chrome Browser		Current version of Chrome on Android 4.4+

Item product access

Auth

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

By default, only Instant Auth is enabled for your Plaid account. Please reach out to your account manager to get started. If you are not yet a Plaid customer, please contact our sales team to learn more. Once enabled, you can trigger all Auth features by including a user object in your Link configuration. See the Link parameter reference above for more details.


Plaid.create({
  ...,
  product: ['auth'],
  // we require a webhook for automated microdeposits,
  // for successful or unsuccessful verification
  webhook: 'https://your_app_url.com/webhook',
  // we require your application’s user information
  userLegalName: 'John Appleseed',
  userEmailAddress: 'jappleseed@youapp.com'
});

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 public_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/item/public_token/create \
  -H 'Content-Type: application/json' \
  -d '{
    "client_id": String,
    "secret": String,
    "access_token": "access-sandbox-de3ce8ef-33f8-452c-a685-8671031fc0f6"
  }'

Pass the created public_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_PUBLIC_TOKEN" // pass in generated public_token
  onSuccess: function(public_token, metadata) {
    metadata = {
      accounts: [{
        verification_status: 'manually_verified',
      }]
    }
  }
})
linkHandler.open()

Retrieve Auth request

POST /auth/get

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

The following options are available:

Field	Description
`account_ids` [String]	A list of `account_id`s to retrieve for the `Item`. Note: An error will be returned if a provided `account_id` is not associated with the `Item`.


// 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']


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

Key	Description
`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

Key	Description
`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

Key	Description
`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

Key	Description
`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

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

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

The following options are available:

Field	Default	Description
`account_ids` [String]	`null`	A list of `account_id`s to retrieve for the `Item`. Note: An error will be returned if a provided `account_id` is not associated with the `Item`
`count` Number	100	The number of transactions to fetch, where 0 < `count` <= 500.
`offset` Number	0	The number of transactions to skip, where `offset` >= 0.


// 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'])


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

Transaction schema

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

Transaction location schema

Key	Description
`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

Key	Description
`reference_number` String, nullable	The transaction reference number supplied by the financial institution.
`ppd_id` String, nullable	The ACH PPD ID for the payer.
`payee_name` String, nullable	For transfers, the party that is receiving the transaction.

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.

Balance

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

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

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

Retrieve Balance request

POST /accounts/balance/get

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

The following options are available:

Field	Default	Description
`account_ids` [String]	`null`	A list of `account_id`s to retrieve for the `Item`. Note: An error will be returned if a provided `account_id` is not associated with the `Item`.


// 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']


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

Key	Description
`current` Number	The total amount of funds in the account.
`available` Number, nullable	The amount of funds available to be withdrawn from an account, as determined by the financial institution. The available balance typically, but not always, equals the current balance less any pending outflows plus any pending inflows.
`limit` Number, nullable	The limit for the account, primarily populated for `credit`-type accounts.
`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 unofficial currency code associated with the transaction. Always `null` if `iso_currency_code` is non-null.

Identity

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

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

Retrieve Identity request

POST /identity/get

Field	Required?
`client_id` String	yes
`secret` String	yes
`access_token` String	yes


// 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']


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

Key	Description
`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

Key	Description
`data` String	The phone number.
`primary` Boolean	When `true`, identifies the phone number as the primary number on an account.
`type` String	The type of phone number as described by the financial institution. Example: `"mobile"`

Emails schema

Key	Description
`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

Key	Description
`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

Key	Description
`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

Income

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

Retrieve Income request

POST /income/get

Field	Required?
`client_id` String	yes
`secret` String	yes
`access_token` String	yes


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


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


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


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


# retrieve income data for an item
response = client.Income.get(access_token)
income = response['income']


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

Income data schema

Key	Description
`last_year_income` Number	The sum of the `Item’s` income over the past 365 days. If we have less than 365 days of data this will be less than a full year's income.
`last_year_income_before_tax` Number	`last_year_income` interpolated to value before taxes. This is the minimum pre-tax salary that assumes a filing status of single with zero dependents.
`projected_yearly_income` Number	`Item’s` income extrapolated over a year based on current, active income streams. Income streams become inactive if they have not recurred for more than two cycles. For example, if a weekly paycheck hasn’t been seen for the past two weeks, it's no longer active.
`projected_yearly_income_before_tax` Number	`projected_yearly_income` interpolated to value before taxes. This is the minimum pre-tax salary that assumes a filing status of single with zero dependents.
`income_streams` [Object]	An array of income streams with detailed information on each. View schema.
`max_number_of_overlapping_income_streams` Number	Max number of income streams present at the same time over the past 365 days.
`number_of_income_streams` Number	Total number of distinct income streams received over the past 365 days.

Income stream schema

Key	Description
`monthly_income` Number	The monthly income associated with the income stream
`confidence` Number	A numeric representation of our confidence in the income data associated with this particular income stream, with 0 being the lowest confidence and 1 being the highest
`days` Number	Extent of data found for this income stream
`name` String	Name of the entity associated with this income stream

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:

Create Items for each of the user’s institutions, using Plaid Link
Create the Asset Report using the access_tokens for each of those Items
Retrieve the Asset Report in your desired format
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.


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

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

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


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


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

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


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

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


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

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

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

Create Asset Report request parameters

Field	Description
`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.

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

User object

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

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

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:


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']

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


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']

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.

Field	Description
`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.


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


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 SFPOOL",
                "pending": false,
                "transaction_id": "GM4K4LJqGBu5g8yqjkQJuVnry6rz6zh8Qwkv9",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              },
              {
                "account_id": "jW4r4QvdeXcAZNj8J3Dni68DqxQ3laHZwGyBD",
                "amount": 6.33,
                "date": "2018-04-09",
                "original_description": "Uber 072515 SFPOOL",
                "pending": false,
                "transaction_id": "DekykZJWrjf5g7kjRaLvceLZb4avg5CVBDGz5x",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              }
            ],
            "type": "depository"
          },
          {
            "account_id": "V3EkERBQXGF5z6Jb9NDkupNeoy1b81cjpWVDe",
            "balances": {
              "available": 200,
              "current": 210
            },
            "days_available": 730,
            "historical_balances": [
              {
                "current": 210,
                "date": "2018-04-12",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              },
              {
                "current": 210,
                "date": "2018-04-11",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              },
              {
                "current": 210,
                "date": "2018-04-10",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              },
              ...
            ],
            "mask": "1111",
            "name": "Plaid Saving",
            "official_name": "Plaid Silver Standard 0.1% Interest Saving",
            "owners": [
              {
                "addresses": [
                  {
                    "data": {
                      "city": "Malakoff",
                      "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 //",
                "pending": false,
                "transaction_id": "LkexeEJ3Ryf5Vw3evRMMIXlLjkRkawIdzm6Ak",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              },
              {
                "account_id": "V3EkERBQXGF5z6Jb9NDkupNeoy1b81cjpWVDe",
                "amount": -4.22,
                "date": "2018-03-22",
                "original_description": "INTRST PYMNT",
                "pending": false,
                "transaction_id": "y7EJEmwgazsjJDVdMZ3QSQBKpaKnQzSjElP71M",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              },
              {
                "account_id": "V3EkERBQXGF5z6Jb9NDkupNeoy1b81cjpWVDe",
                "amount": 25,
                "date": "2018-03-27",
                "original_description": "CREDIT CARD 3333 PAYMENT //",
                "pending": false,
                "transaction_id": "dLz7z41KlaSWLbmJqpxXiaqPgJPbn5IgMwymJ",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              }
            ],
            "type": "depository"
          },
          {
            "account_id": "4RWyWq143jIEm7BaqJNKCQyG9Ndnv5iJaENyV",
            "balances": {
              "available": null,
              "current": 5000
            },
            "days_available": 730,
            "historical_balances": [
              {
                "current": 5000,
                "date": "2018-04-12",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              },
              {
                "current": 1000,
                "date": "2018-04-11",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              },
              {
                "current": 1000,
                "date": "2018-04-10",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              },
              ...
            ],
            "mask": "2222",
            "name": "Plaid CD",
            "official_name": "Plaid Bronze Standard 0.2% Interest CD",
            "owners": [
              {
                "addresses": [
                  {
                    "data": {
                      "city": "Malakoff",
                      "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 SFPOOL",
                "pending": false,
                "transaction_id": "GM4K4LJqGBu5g8yqjkQJuVnry6rz6zh8Qwkv9",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              },
              {
                "account_id": "jW4r4QvdeXcAZNj8J3Dni68DqxQ3laHZwGyBD",
                "amount": 6.33,
                "date": "2018-04-09",
                "original_description": "Uber 072515 SFPOOL",
                "pending": false,
                "transaction_id": "DekykZJWrjf5g7kjRaLvceLZb4avg5CVBDGz5x",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              }
            ],
            "type": "depository"
          },
          {
            "account_id": "V3EkERBQXGF5z6Jb9NDkupNeoy1b81cjpWVDe",
            "balances": {
              "available": 200,
              "current": 210
            },
            "days_available": 730,
            "historical_balances": [
              {
                "current": 210,
                "date": "2018-04-12",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              },
              {
                "current": 210,
                "date": "2018-04-11",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              },
              {
                "current": 210,
                "date": "2018-04-10",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              },
              ...
            ],
            "mask": "1111",
            "name": "Plaid Saving",
            "official_name": "Plaid Silver Standard 0.1% Interest Saving",
            "owners": [
              {
                "addresses": [
                  {
                    "data": {
                      "city": "Malakoff",
                      "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 //",
                "pending": false,
                "transaction_id": "LkexeEJ3Ryf5Vw3evRMMIXlLjkRkawIdzm6Ak",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              },
              {
                "account_id": "V3EkERBQXGF5z6Jb9NDkupNeoy1b81cjpWVDe",
                "amount": -4.22,
                "date": "2018-03-22",
                "original_description": "INTRST PYMNT",
                "pending": false,
                "transaction_id": "y7EJEmwgazsjJDVdMZ3QSQBKpaKnQzSjElP71M",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              },
              {
                "account_id": "V3EkERBQXGF5z6Jb9NDkupNeoy1b81cjpWVDe",
                "amount": 25,
                "date": "2018-03-27",
                "original_description": "CREDIT CARD 3333 PAYMENT //",
                "pending": false,
                "transaction_id": "dLz7z41KlaSWLbmJqpxXiaqPgJPbn5IgMwymJ",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              }
            ],
            "type": "depository"
          },
          {
            "account_id": "4RWyWq143jIEm7BaqJNKCQyG9Ndnv5iJaENyV",
            "balances": {
              "available": null,
              "current": 5000
            },
            "days_available": 730,
            "historical_balances": [
              {
                "current": 5000,
                "date": "2018-04-12",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              },
              {
                "current": 1000,
                "date": "2018-04-11",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              },
              {
                "current": 1000,
                "date": "2018-04-10",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              },
              ...
            ],
            "mask": "2222",
            "name": "Plaid CD",
            "official_name": "Plaid Bronze Standard 0.2% Interest CD",
            "owners": [
              {
                "addresses": [
                  {
                    "data": {
                      "city": "Malakoff",
                      "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 SFPOOL",
                "pending": false,
                "transaction_id": "GM4K4LJqGBu5g8yqjkQJuVnry6rz6zh8Qwkv9",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              },
              {
                "account_id": "jW4r4QvdeXcAZNj8J3Dni68DqxQ3laHZwGyBD",
                "amount": 6.33,
                "date": "2018-04-09",
                "original_description": "Uber 072515 SFPOOL",
                "pending": false,
                "transaction_id": "DekykZJWrjf5g7kjRaLvceLZb4avg5CVBDGz5x",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              }
            ],
            "type": "depository"
          },
          {
            "account_id": "V3EkERBQXGF5z6Jb9NDkupNeoy1b81cjpWVDe",
            "balances": {
              "available": 200,
              "current": 210
            },
            "days_available": 730,
            "historical_balances": [
              {
                "current": 210,
                "date": "2018-04-12",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              },
              {
                "current": 210,
                "date": "2018-04-11",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              },
              {
                "current": 210,
                "date": "2018-04-10",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              },
              ...
            ],
            "mask": "1111",
            "name": "Plaid Saving",
            "official_name": "Plaid Silver Standard 0.1% Interest Saving",
            "owners": [
              {
                "addresses": [
                  {
                    "data": {
                      "city": "Malakoff",
                      "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 //",
                "pending": false,
                "transaction_id": "LkexeEJ3Ryf5Vw3evRMMIXlLjkRkawIdzm6Ak",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              },
              {
                "account_id": "V3EkERBQXGF5z6Jb9NDkupNeoy1b81cjpWVDe",
                "amount": -4.22,
                "date": "2018-03-22",
                "original_description": "INTRST PYMNT",
                "pending": false,
                "transaction_id": "y7EJEmwgazsjJDVdMZ3QSQBKpaKnQzSjElP71M",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              },
              {
                "account_id": "V3EkERBQXGF5z6Jb9NDkupNeoy1b81cjpWVDe",
                "amount": 25,
                "date": "2018-03-27",
                "original_description": "CREDIT CARD 3333 PAYMENT //",
                "pending": false,
                "transaction_id": "dLz7z41KlaSWLbmJqpxXiaqPgJPbn5IgMwymJ",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              }
            ],
            "type": "depository"
          },
          {
            "account_id": "4RWyWq143jIEm7BaqJNKCQyG9Ndnv5iJaENyV",
            "balances": {
              "available": null,
              "current": 5000
            },
            "days_available": 730,
            "historical_balances": [
              {
                "current": 5000,
                "date": "2018-04-12",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              },
              {
                "current": 1000,
                "date": "2018-04-11",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              },
              {
                "current": 1000,
                "date": "2018-04-10",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              },
              ...
            ],
            "mask": "2222",
            "name": "Plaid CD",
            "official_name": "Plaid Bronze Standard 0.2% Interest CD",
            "owners": [
              {
                "addresses": [
                  {
                    "data": {
                      "city": "Malakoff",
                      "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 SFPOOL",
                "pending": false,
                "transaction_id": "GM4K4LJqGBu5g8yqjkQJuVnry6rz6zh8Qwkv9",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              },
              {
                "account_id": "jW4r4QvdeXcAZNj8J3Dni68DqxQ3laHZwGyBD",
                "amount": 6.33,
                "date": "2018-04-09",
                "original_description": "Uber 072515 SFPOOL",
                "pending": false,
                "transaction_id": "DekykZJWrjf5g7kjRaLvceLZb4avg5CVBDGz5x",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              }
            ],
            "type": "depository"
          },
          {
            "account_id": "V3EkERBQXGF5z6Jb9NDkupNeoy1b81cjpWVDe",
            "balances": {
              "available": 200,
              "current": 210
            },
            "days_available": 730,
            "historical_balances": [
              {
                "current": 210,
                "date": "2018-04-12",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              },
              {
                "current": 210,
                "date": "2018-04-11",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              },
              {
                "current": 210,
                "date": "2018-04-10",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              },
              ...
            ],
            "mask": "1111",
            "name": "Plaid Saving",
            "official_name": "Plaid Silver Standard 0.1% Interest Saving",
            "owners": [
              {
                "addresses": [
                  {
                    "data": {
                      "city": "Malakoff",
                      "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 //",
                "pending": false,
                "transaction_id": "LkexeEJ3Ryf5Vw3evRMMIXlLjkRkawIdzm6Ak",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              },
              {
                "account_id": "V3EkERBQXGF5z6Jb9NDkupNeoy1b81cjpWVDe",
                "amount": -4.22,
                "date": "2018-03-22",
                "original_description": "INTRST PYMNT",
                "pending": false,
                "transaction_id": "y7EJEmwgazsjJDVdMZ3QSQBKpaKnQzSjElP71M",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              },
              {
                "account_id": "V3EkERBQXGF5z6Jb9NDkupNeoy1b81cjpWVDe",
                "amount": 25,
                "date": "2018-03-27",
                "original_description": "CREDIT CARD 3333 PAYMENT //",
                "pending": false,
                "transaction_id": "dLz7z41KlaSWLbmJqpxXiaqPgJPbn5IgMwymJ",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              }
            ],
            "type": "depository"
          },
          {
            "account_id": "4RWyWq143jIEm7BaqJNKCQyG9Ndnv5iJaENyV",
            "balances": {
              "available": null,
              "current": 5000
            },
            "days_available": 730,
            "historical_balances": [
              {
                "current": 5000,
                "date": "2018-04-12",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              },
              {
                "current": 1000,
                "date": "2018-04-11",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              },
              {
                "current": 1000,
                "date": "2018-04-10",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              },
              ...
            ],
            "mask": "2222",
            "name": "Plaid CD",
            "official_name": "Plaid Bronze Standard 0.2% Interest CD",
            "owners": [
              {
                "addresses": [
                  {
                    "data": {
                      "city": "Malakoff",
                      "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 SFPOOL",
                "pending": false,
                "transaction_id": "GM4K4LJqGBu5g8yqjkQJuVnry6rz6zh8Qwkv9",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              },
              {
                "account_id": "jW4r4QvdeXcAZNj8J3Dni68DqxQ3laHZwGyBD",
                "amount": 6.33,
                "date": "2018-04-09",
                "original_description": "Uber 072515 SFPOOL",
                "pending": false,
                "transaction_id": "DekykZJWrjf5g7kjRaLvceLZb4avg5CVBDGz5x",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              }
            ],
            "type": "depository"
          },
          {
            "account_id": "V3EkERBQXGF5z6Jb9NDkupNeoy1b81cjpWVDe",
            "balances": {
              "available": 200,
              "current": 210
            },
            "days_available": 730,
            "historical_balances": [
              {
                "current": 210,
                "date": "2018-04-12",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              },
              {
                "current": 210,
                "date": "2018-04-11",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              },
              {
                "current": 210,
                "date": "2018-04-10",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              },
              ...
            ],
            "mask": "1111",
            "name": "Plaid Saving",
            "official_name": "Plaid Silver Standard 0.1% Interest Saving",
            "owners": [
              {
                "addresses": [
                  {
                    "data": {
                      "city": "Malakoff",
                      "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 //",
                "pending": false,
                "transaction_id": "LkexeEJ3Ryf5Vw3evRMMIXlLjkRkawIdzm6Ak",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              },
              {
                "account_id": "V3EkERBQXGF5z6Jb9NDkupNeoy1b81cjpWVDe",
                "amount": -4.22,
                "date": "2018-03-22",
                "original_description": "INTRST PYMNT",
                "pending": false,
                "transaction_id": "y7EJEmwgazsjJDVdMZ3QSQBKpaKnQzSjElP71M",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              },
              {
                "account_id": "V3EkERBQXGF5z6Jb9NDkupNeoy1b81cjpWVDe",
                "amount": 25,
                "date": "2018-03-27",
                "original_description": "CREDIT CARD 3333 PAYMENT //",
                "pending": false,
                "transaction_id": "dLz7z41KlaSWLbmJqpxXiaqPgJPbn5IgMwymJ",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              }
            ],
            "type": "depository"
          },
          {
            "account_id": "4RWyWq143jIEm7BaqJNKCQyG9Ndnv5iJaENyV",
            "balances": {
              "available": null,
              "current": 5000
            },
            "days_available": 730,
            "historical_balances": [
              {
                "current": 5000,
                "date": "2018-04-12",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              },
              {
                "current": 1000,
                "date": "2018-04-11",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              },
              {
                "current": 1000,
                "date": "2018-04-10",
                "iso_currency_code": "USD",
                "unofficial_currency_code": null
              },
              ...
            ],
            "mask": "2222",
            "name": "Plaid CD",
            "official_name": "Plaid Bronze Standard 0.2% Interest CD",
            "owners": [
              {
                "addresses": [
                  {
                    "data": {
                      "city": "Malakoff",
                      "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).

Field	Description
`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

Field	Description
`asset_report_id` String	Plaid’s unique identifier for this Asset Report
`client_report_id` String	An identifier you determine and submit for the Asset Report
`date_generated` Datetime	The date and time when the Asset Report was created
`days_requested` 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

Field	Description
item_id String	Plaid’s unique identifier for the `Item`
institution_name String	The full financial institution name associated with the `Item`
institution_id String	The financial institution associated with the `Item`
date_last_updated Datetime	The date and time when this `Item’s` data was retrieved from the financial institution
accounts [Object]	Data about each of the accounts open on the `Item`; see Account object for fields

Account object

Field	Description
`account_id` String	Plaid’s unique identifier for the account
`mask` String	The last 2-5 digits of the account's number
`name` String	The name of the account, either assigned by the user or by the financial institution itself
`official_name` String, 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.

Field	Description
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

Field	Description
data String	The phone number
primary Boolean	When true, identifies the phone number as the primary number on an account
type String	The type of phone number as described by the financial institution Example: `"mobile"`

Email object

Field	Description
data String	The email address
primary Boolean	When true, identifies the email address as the primary email address on an account
type String	The type of email Example: `"secondary"`

Address object

Field	Description
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

Key	Description
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

Field	Description
available Float	The amount of funds available to be withdrawn from an account, as determined by the financial institution. The available balance typically, but not always, equals the current balance less any pending outflows plus any pending inflows. Not all institutions calculate the available balance; in the event that available balance is unavailable from the institution, Plaid will return an available balance value of `null`.
current Float	The total amount of funds in the account
iso_currency_code String	The ISO currency code of the transaction. Always `null` if `unofficial_currency_code` is non-null.
unofficial_currency_code String	The unofficial currency code associated with the transaction. Always `null` if `iso_currency_code` is non-null.

Historical balance object

Field	Description
date Date	The date of the calculated historical balance
current Float	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 transaction. Always `null` if `unofficial_currency_code` is non-null.
unofficial_currency_code String	The unofficial currency code associated with the transaction. Always `null` if `iso_currency_code` is non-null.

Transaction object

Field	Description
account_id String	Plaid’s unique identifier for the account
transaction_id String	Plaid’s unique identifier for the transaction
date Date	For pending transactions, Plaid returns the date the transaction occurred; for posted transactions, Plaid returns the date the transaction posts; both dates are returned in an ISO 8601 format (YYYY-MM-DD).
original_description String	The string returned by the financial institution to describe the transaction
pending Boolean	When true, identifies the transaction as pending or unsettled; pending transaction details (description, amount) may change before they are settled
amount Float	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. Always `null` if `unofficial_currency_code` is non-null.
unofficial_currency_code String, nullable	The unofficial currency code associated with the transaction. Always `null` if `iso_currency_code` is non-null.
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

Key	Description
`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

Key	Description
`reference_number` String, nullable	The transaction reference number supplied by the financial institution.
`ppd_id` String, nullable	The ACH PPD ID for the payer.
`payee_name` String, nullable	For transfers, the party that is receiving the transaction.

Warning object

Field	Description
warning_type String	The warning type, which will always be `"ASSET_REPORT_WARNING"`.
warning_code String	The warning code identifies a specific kind of warning. Currently, the only possible warning code is `"OWNERS_UNAVAILABLE"`, which indicates that account-owner information is not available.
cause Object	The underlying cause of this warning. See Cause object

Cause object

Field	Description
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.


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)

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:


// 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']

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.


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']

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.


// 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']


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

Investments

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.

Top institutions we cover

Plaid provides investment account coverage for hundreds of institutions. Below you'll find a list of institutions and corresponding institution_ids for the largest US institutions:

Name	Institution ID
Ameriprise Financial	`ins_115604`
Betterment	`ins_115605`
Chase	`ins_3`
Charles Schwab	`ins_11`
E*TRADE	`ins_115589`
Edward Jones	`ins_115607`
Fidelity	`ins_12`
Merrill Edge	`ins_115610`
Merrill Lynch	`ins_115611`
Morgan Stanley	`ins_115699`
Stash Invest	`ins_115614`
TD Ameritrade	`ins_115615`
Vanguard	`ins_115616`
Wealthfront	`ins_115617`
Wells Fargo	`ins_4`

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

Field	Required?	Description
`client_id` String	yes
`secret` String	yes
`access_token` String	yes
`options` Object	no	If provided, must be non-null.

The following options are available:

Field	Description
`account_ids` [String]	A list of `account_id`s to retrieve for the `Item`. Note: An error will be returned if a provided `account_id` is not associated with the `Item`.


// 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']


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": 2104.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": 89529.40,
    "cost_basis": 38939.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

Key	Description
`security_id` String	A unique Plaid identifier for the holding.
`isin` String, nullable	12-character ISIN, a globally unique securities identifier. Will be present when either CUSIP or SEDOL are present.
`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

Key	Description
`account_id` String	The Plaid Account ID associated with the holding.
`security_id` String	The 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.

Type	Name & 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

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

The following options are available:

Field	Default	Description
`account_ids` [String]	`null`	A list of `account_id`s to retrieve for the `Item`. Note: An error will be returned if a provided `account_id` is not associated with the `Item`
`count` Number	`100`	The number of transactions to fetch, where 0 < `count` <= 500.
`offset` Number	`0`	The number of transactions to skip, where `offset` >= 0.


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'])


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

Key	Description
`investment_transaction_id` String	The ID of the Investment ransaction, 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.
`cancel_transaction_id` String	The ID of the investment transaction being cancelled by the current one.
`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.
`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.

Type	Description
`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

Liabilities

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

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

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.


var handler = Plaid.create({
  clientName: 'Plaid Quickstart',
  countryCodes: ['US'],
  env: 'sandbox',
  key: 'PUBLIC_KEY',
  // include liabilities in the list of products
  product: ['liabilities'],
  language: 'en',
  ...
});

The table below shows all currently supported Account types and subtypes in Liabilities.

Supported Liabilities Account Types

Account type	Subtypes
credit	credit card, paypal
loan	student

Filtering Institutions in Link by Account Subtype

You can configure Link to display only the institutions that support a specific Liabilities Account subtype. Using the accountSubtypes parameter, we can filter through institutions, keeping only the student loan servicers or only credit card issuers. (Please note: this filtering capability is only supported for the Liabilities product.)


var handler = Plaid.create({
  ...
  // if we are using account subtype filtering,
  // make sure we set countryCodes to US
  countryCodes: ['US'],
  ...
  // include liabilities in the list of products
  product: ['liabilities'],
  // set accountSubtypes show only institutions with
  // these following account subtypes
  accountSubtypes: {
    loan: ['student'],
  },
  ...
});

Filtering Institutions in Link with Webview

If you're using Link Webview to open Plaid Link, pass in the mapping as a URL-encoded JSON object. Below is how one might initialize the webview.


https://cdn.plaid.com/link/v2/stable/link.html
  ?key=${publicKey}
  &apiVersion=v2
  &env=${env}
  &product=${product}
  &clientName=${clientName}
  &isWebView=true
  &isMobile=true
  &accountSubtypes=${URLEncodedAccountSubtypes}

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.

Retrieve Liabilities Request


POST /liabilities/get

Field	Required?	Description
`client_id` String	yes
`secret` String	yes
`access_token` String	yes
`options` Object	no	If provided, must be non-null.

The following options are available:

Field	Default	Description
`account_ids` [String]	`null`	A list of `account_id`s to retrieve for the `Item`. Note: An error will be returned if a provided `account_id` is not associated with the `Item`


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


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

Key	Description
`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: Great Lakes (`ins_116861`) and Firstmark (`ins_116295`) require a minimum payment across all loans associated with an item. Our API presents that minimum payment amount on each loan. 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.
`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

Key	Description
`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".
`end_date` Date, nullable	The date until which the loan will be in its current status.

Student Repayment Plan schema

Key	Description
`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".
`description` String, nullable	This field will return the description of the repayment plan as provided by the servicer.

PSLF Status schema

Key	Description
`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

Key	Description
`city` String, nullable	The full city name.
`country` String, nullable	The ISO 3166-1 alpha-2 country code
`street` String, nullable	The full street address Example: "564 Main Street, APT 15"
`postal_code` String, nullable	The five or nine digit postal code.
`region` String, nullable	The region or state Example: "NC"

Retrieve Credit Card Response


http code 200
{
  "accounts": [...],
  "item": {...},
  "liabilities": {
    "credit": [
      {
        "account_id": "LgDOJbZz7pFKpaPNgRpZU57zY395q1I0Lxpew",
        "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",
        "late_fee_amount": 25.00,
        "minimum_payment_amount": 123,
        "next_payment_due_date": "2019-04-01",
        "credit_limit": 5500,
        "aprs": [
          {
            "apr_type": "purchase_apr",
            "apr_percentage": 23.99,
            "balance_subject_to_apr": 2345.6,
            "interest_charge_amount": 27.01
          }
        ]
      }
    ],
    "request_id": "9GMVig"
  }
}

Credit card liability schema

Key	Description
`aprs` Object	See the APR object schema.
`credit_limit` Number, nullable	The credit limit of the account.
`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.
`late_fee_amount` Float, nullable	The penalty if the payment is late.
`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

Key	Description
`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.

Item management

Accounts

Retrieve Accounts request


POST /accounts/get

Field	Required?
`client_id` String	yes
`secret` String	yes
`access_token` String	yes


// 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']


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

Key	Description
`account_id` String	The unique ID of the account. Note: In some instances, account IDs may change.
`item` Object	Information about the `Item` associated with the accounts such as the item ID and institution ID. See POST `/item/get` for more information.
`balances` Object	For depository accounts, the current balance is the total amount of funds in the account. The available balance is the amount of funds available to be withdrawn from an account, as determined by the financial institution. The available balance typically, but not always, equals the current balance less any pending outflows plus any pending inflows. Note: Not all institutions calculate the available balance. In the event that available balance is unavailable from the institution, Plaid will return an available balance value of `null`. For accounts with 'student loan' subtypes, balance is defined as the principal remaining.
`name` String	The name of the `Account`, either assigned by the user or the financial institution itself.
`mask` String	The last four digits of the `Account`'s number.
`official_name` String, 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

Key	Description
`current` Number	The total amount of funds in the account.
`available` Number, nullable	The amount of funds available to be withdrawn from an account, as determined by the financial institution. The available balance typically, but not always, equals the current balance less any pending outflows plus any pending inflows.
`limit` Number, nullable	The limit for the account, primarily populated for `credit`-type accounts.
`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 unofficial currency code associated with the transaction. Always `null` if `iso_currency_code` is non-null.

Account types

Account type	Description
investment	Investment account
credit	Credit card
depository	Checking or savings accounts
loan	Loan account
other	Non-specified account type

Account subtypes

Account type	Subtypes
investment	401a, 401k, 403B, 457b, 529, brokerage, cash isa, education savings account, gic, health reimbursement arrangement, hsa, isa, ira, lif, lira, lrif, lrsp, non-taxable brokerage account, other, prif, rdsp, resp, rlif, rrif, pension, profit sharing plan, retirement, roth, roth 401k, rrsp, sep ira, simple ira, sipp, stock plan, thrift savings plan, tfsa, ugma, utma, variable annuity
credit	credit card, paypal
depository	cd, checking, savings, money market, paypal, prepaid
loan	auto, commercial, construction, consumer, home, home equity, loan, mortgage, overdraft, line of credit, student
other	cash management, keogh, mutual fund, prepaid, recurring, rewards, safe deposit, sarsep, other

Account subtypes – `investment`

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

Investment subtype	Description
`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'
`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
`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 401k`	Employer-sponsored investment savings account
`roth`	Roth IRA
`rrif`	Canadian Registered Retirement Income Fund
`rrsp`	Canadian Registered Retirement Savings Plan (equivalent to 401k)
`rdsp`	Canadian Registered Disability Savings Plan
`resp`	Canadian Registered Education Savings 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
`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 status	Description
pending_automatic_verification	An Item is pending automated microdeposit verfication
automatically_verified	An Item was successfully automatically verified
pending_manual_verification	An Item is pending manual microdeposit verfication
manually_verified	An 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

Field	Required?
`client_id` String	yes
`secret` String	yes
`access_token` String	yes


// 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']


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

Key	Description
`item` Object	Metadata about the item. View schema.
`status` Object	An object with information about the status of the Item. View schema.

Item schema

Key	Description
`item_id` String	The Plaid `Item` ID.
`institution_id` String	The Plaid Institution ID associated with the `Item`.
`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.

Item error schema

Field	Description
`error_type` String	A broad categorization of the error. One of: `INVALID_REQUEST`, `INVALID_INPUT`, `INSTITUTION_ERROR`, `RATE_LIMIT_EXCEEDED`, `API_ERROR`, `ITEM_ERROR`, or `ASSET_REPORT_ERROR`. Safe for programmatic use.
`error_code` String	The particular error code. Each `error_type` has a specific set of `error_code`s. 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.

Update webhook request


POST /item/webhook/update

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


// Update 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')


http code 200
{
  "item": {
    "available_products": [
      "balance",
      "auth"
    ],
    "billed_products": [
      "identity",
      "transactions"
    ],
    "error": null,
    "institution_id": "ins_109508",
    "item_id": "Ed6bjNrDLJfGvZWwnkQlfxwoNz54B5C97ejBr",
    "webhook": "https://plaid.com/updated/webhook"
  },
  "request_id": "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

Field	Required?
`client_id` String	yes
`secret` String	yes
`access_token` String	yes


// 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']


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

Field	Required?
`client_id` String	yes
`secret` String	yes
`access_token` String	yes


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)


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.


"status": {
  "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

Field	Description
`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.

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.

Field	Description
`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

Field	Description
`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_type": String,
  "error_code": String,
  "error_message": String,
  "display_message": String
}

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

Field	Description
`error_type` String	A broad categorization of the error. One of: `INVALID_REQUEST`, `INVALID_INPUT`, `INSTITUTION_ERROR`, `RATE_LIMIT_EXCEEDED`, `API_ERROR`, `ITEM_ERROR`, or `ASSET_REPORT_ERROR`. Safe for programmatic use.
`error_code` String	The particular error code. Each `error_type` has a specific set of `error_code`s. Safe for programmatic use.
`error_message` String	A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use.
`display_message` String, nullable	A user-friendly representation of the error code. `null` if the error is not related to user action. This may change over time and is not safe for programmatic use.

Invalid request errors

Returned when the request is malformed and cannot be processed.


{
  "error_type": "INVALID_REQUEST",
  "http_code": Enum (400, 404),
  "error_code": Enum (
    "MISSING_FIELDS",
    "UNKNOWN_FIELDS",
    "INVALID_FIELD",
    "INVALID_BODY",
    "INVALID_HEADERS",
    "NOT_FOUND",
    "SANDBOX_ONLY"
  )
  "error_message": String
  "display_message": Null,
  "request_id": String
  }

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

Invalid input errors

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


{
  "error_type": "INVALID_INPUT",
  "http_code": 400,
  "error_code": Enum (
    "INVALID_API_KEYS",
    "UNAUTHORIZED_ENVIRONMENT",
    "INVALID_ACCESS_TOKEN",
    "INVALID_PUBLIC_TOKEN",
    "INVALID_PRODUCT",
    "INVALID_ACCOUNT_ID",
    "INVALID_INSTITUTION"
  )
  "error_message": String
  "display_message": Null,
  "request_id": String
}

Error code	Notes
`INVALID_API_KEYS` HTTP 400	The client ID and secret included in the request body were invalid. Find your API keys in the Dashboard.
`UNAUTHORIZED_ENVIRONMENT` HTTP 400	Your client ID does not have access to this API environment. See which environments you are enabled for from the Dashboard.
`INVALID_ACCESS_TOKEN` HTTP 400	Access tokens are in the format: `access-<environment>-<identifier>` This error can happen when the `access_token` you provided is invalid, from a different API environment, or has been removed via a `/item/remove` request.
`INVALID_PUBLIC_TOKEN` HTTP 400	Public tokens are in the format: `public-<environment>-<identifier>` This error can happen when the `public_token` you provided is invalid, from a different API environment, or expired.
`INVALID_PRODUCT` HTTP 400	Your client ID does not have access to this product. Contact us to gain access.
`INVALID_ACCOUNT_ID` HTTP 400	One of the `account_id`(s) specified is invalid or does not exist.
`INVALID_INSTITUTION` HTTP 400	The `institution_id` specified is invalid or does not exist.

Rate limit exceeded errors

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


{
  "error_type": "RATE_LIMIT_EXCEEDED",
  "http_code": 429,
  "error_code": Enum (
    "ACCOUNTS_LIMIT",
    "ADDITION_LIMIT",
    "AUTH_LIMIT",
    "IDENTITY_LIMIT",
    "INCOME_LIMIT",
    "ITEM_GET_LIMIT",
    "RATE_LIMIT"
    "TRANSACTIONS_LIMIT",
  )
  "error_message": String
  "display_message": nullable String,
  "request_id": String
}

Error code	Notes
`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.
`INCOME_LIMIT` HTTP 429	Too many requests were made to the `/income/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.


{
  "error_type": "API_ERROR",
  "http_code": 500,
  "error_code": Enum (
    "INTERNAL_SERVER_ERROR",
    "PLANNED_MAINTENANCE"
  )
  "error_message": String
  "display_message": nullable String,
  "request_id": String
}

Error code	Notes
`INTERNAL_SERVER_ERROR` HTTP 500	Plaid was unable to process the request, either due to an internal system issue or an unsupported response from a financial institution.
`PLANNED_MAINTENANCE` HTTP 500	Plaid's systems are in maintenance mode and API operations are disabled. Advanced notice will be provided if a maintenance window is ever planned.

Item errors

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


{
  "error_type": "ITEM_ERROR",
  "http_code": 400,
  "error_code": Enum (
    "INVALID_CREDENTIALS",
    "INVALID_MFA",
    "INVALID_SEND_METHOD",
    "INVALID_UPDATED_USERNAME",
    "ITEM_LOCKED",
    "ITEM_LOGIN_REQUIRED",
    "ITEM_NO_ERROR",
    "ITEM_NOT_SUPPORTED",
    "ITEM_NO_VERIFICATION",
    "INCORRECT_DEPOSIT_AMOUNTS",
    "TOO_MANY_VERIFICATION_ATTEMPTS",
    "USER_SETUP_REQUIRED",
    "MFA_NOT_SUPPORTED",
    "NO_ACCOUNTS",
    "NO_AUTH_ACCOUNTS",
    "NO_INVESTMENT_ACCOUNTS",
    "NO_LIABILITY_ACCOUNTS",
    "PRODUCT_NOT_READY",
    "PRODUCTS_NOT_SUPPORTED"
  )
  "error_message": String
  "display_message": nullable String,
  "request_id": String
}

Error code	Notes
`INVALID_CREDENTIALS` HTTP 400	The financial institution indicated that the credentials provided were invalid.
`INVALID_MFA` HTTP 400	The financial institution indicated that the MFA response(s) provided were invalid.
`INVALID_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_NO_VERIFICATION` HTTP 400	Plaid is unable to support this user's accounts due to restrictions in place at the financial institution.
`INCORRECT_DEPOSIT_AMOUNTS` HTTP 400	The user submitted incorrect Manual Same-Day micro-deposit amounts during Item verification in Link.
`TOO_MANY_VERIFICATION_ATTEMPTS` HTTP 400	The user attempted to verify their Manual Same-Day micro-deposit amounts more than 3 times for an Item. The Item is now permanently locked and the user must retry with a new institution.
`USER_SETUP_REQUIRED` HTTP 400	The user must log in directly to the financial institution and take some action (agree to updated terms and conditions, change their password, etc.) before Plaid can access their accounts.
`MFA_NOT_SUPPORTED` HTTP 400	Returned when the user requires a form of MFA that Plaid does not support for a given financial institution.
`NO_ACCOUNTS` HTTP 400	Returned when there are no open accounts associated with the `Item`.
`NO_AUTH_ACCOUNTS` HTTP 400	Returned from `POST /auth/get` when there are no valid checking or savings account(s) for which account and routing numbers could be retrieved.
`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.

Auth errors

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


{
  "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 code	Notes
`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.


{
  "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 code	Notes
`PRODUCT_NOT_ENABLED` HTTP 400	In your request to the `/asset_report/create` endpoint, you included the `access_token` of an `Item` for which the `assets` product was not enabled. To fix this error, create the `Item` again with `assets` in the Link `product` array. See the Link parameter reference for more.
`DATA_UNAVAILABLE` HTTP 400	Plaid was not able to pull sufficient data to generate the Asset Report. The `causes` field will contain detailed information about the underlying causes (e.g., institution maintenance).
`PRODUCT_NOT_READY` HTTP 400	The Asset Report is still being generated. Try retrieving the Report again later.
`ASSET_REPORT_GENERATION_FAILED` HTTP 500	The Asset Report could not be generated for an unknown reason. Try creating the Report again later.
`INVALID_PARENT` HTTP 400 or 404	The filtered or refreshed Asset Report could not be created because the parent Asset Report is not in a good state (for example, it has been deleted).
`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.


{
  "warning_type": "ASSET_REPORT_WARNING",
  "warning_code": Enum (
    "OWNERS_UNAVAILABLE"
  ),
  "cause": Cause
}

Warning code	Notes
`OWNERS_UNAVAILABLE`	Plaid was not able to pull account information due to the included `Cause`.

Institution errors

Returned when there are errors for the requested financial institution.


{
  "error_type": "INSTITUTION_ERROR",
  "http_code": 400,
  "error_code": Enum (
    "INSTITUTION_DOWN",
    "INSTITUTION_NOT_RESPONDING",
    "INSTITUTION_NOT_AVAILABLE",
    "INSTITUTION_NO_LONGER_SUPPORTED"
  )
  "error_message": String
  "display_message": nullable String,
  "request_id": String
}

Error code	Notes
`INSTITUTION_DOWN` HTTP 400	The financial institution is down, either for maintenance or due to an infrastructure issue with their systems.
`INSTITUTION_NOT_RESPONDING` HTTP 400	The financial institution is failing to respond to some of our requests. Your user may be successful if they retry another time.
`INSTITUTION_NOT_AVAILABLE` HTTP 400	The financial institution is not available this time.
`INSTITUTION_NO_LONGER_SUPPORTED` HTTP 400	Plaid no longer supports this financial institution.

Webhooks

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.

Code	Details
AUTOMATICALLY_VERIFIED	Fired 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_EXPIRED	Fired when an Item cannot be verified automatically after 7 days.


{
  "webhook_type": "AUTH",
  "webhook_code": "AUTOMATICALLY_VERIFIED",
  "item_id": String,
  "account_id": String
}


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

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

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

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


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


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


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


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

Item webhooks

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

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


{
  "webhook_type": "ITEM",
  "webhook_code": "WEBHOOK_UPDATE_ACKNOWLEDGED",
  "item_id": "wz666MBjYWTp2PDzzggYhM6oWWmBb",
  "error": null,
  "new_webhook_url": "https://plaid.com/example/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
  }
}

Income webhooks

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


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

Assets webhooks

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

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

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


{
  "asset_report_id": String,
  "webhook_code": "PRODUCT_READY",
  "webhook_type": "ASSETS"
}


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

Institutions

Institution overview

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

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


POST /institutions/get
POST /institutions/get_by_id
POST /institutions/search

Institutions by product

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

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

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

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

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

Institution Search

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

Institution search request


POST /institutions/search

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

The following options are available:

Field	Default	Description
`include_optional_metadata` Boolean	`false`	When `true`, return the institution's homepage URL, logo and primary brand color. Learn more.
`country_codes` [String]	`null`	Specify an array of Plaid-supported country codes using the ISO-3166-1 alpha-2 country code standard.


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


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


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


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


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


http code 200
{
  "institutions": [
    {
      "country_codes": ["US"],
      "credentials": [{
        "label": "User ID",
        "name": "username",
        "type": "text"
      }, {
        "label": "Password",
        "name": "password",
        "type": "password"
      }],
      "has_mfa": true,
      "institution_id": "ins_109509",
      "mfa": [
        "code",
        "list",
        "questions",
        "selections"
      ],
      "name": "First Gingham Credit Union",
      // included when options.include_optional_metadata is true
      "url": "https://plaid.com",
      "primary_color": "#1f1f1f",
      "logo": null
    },
    ...
  ],
  "request_id": "m8MDnv9okwxFNBV"
}

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

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

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

The following options are available:

Field	Default	Description
`products` [String]	`null`	Filter the `Institution`s based on whether they support all products listed in `products`.
`include_optional_metadata` Boolean	`false`	When `true`, return the institution's homepage URL, logo and primary brand color. Learn more.
`country_codes` [String]	`null`	Specify an array of Plaid-supported country codes using the ISO-3166-1 alpha-2 country code standard.


// 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']


http code 200
{
  "institutions": [
    {
      "country_codes": ["US"],
      "credentials": [{
        "label": "User ID",
        "name": "username",
        "type": "text"
       }, {
        "label": "Password",
        "name": "password",
        "type": "password"
      }],
      "has_mfa": true,
      "institution_id": "ins_109508",
      "mfa": [
        "code",
        "list",
        "questions",
        "selections"
      ],
      "name": "First Platypus Bank",
      // the following are included when
      // options.include_optional_metadata is true
      "primary_color": "#1f1f1f",
      "url": "https://plaid.com",
      "logo": null,
      ]
    }
  ],
  "request_id": "m8MDnv9okwxFNBV",
  "total": 1
}

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

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

The following options are available:

Field	Default	Description
`include_optional_metadata` Boolean	`false`	When `true`, return the institution's homepage URL, logo and primary brand color. Learn more.
`include_status` Boolean	`false`	If `true`, the response will include status information about the institution.


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


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


response = client.institutions.get_by_id(INSTITUTION_ID)


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


response = client.Institutions.get_by_id(INSTITUTION_ID)


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"
    ],
    // 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": "HEALTHLY",
        "last_status_change": "2019-02-12T08:22:00Z",
        "breakdown": {
          "success": 0.95,
          "error_plaid": 0.02,
          "error_institution": 0.03,
          "refresh_interval": "NORMAL"
      }
    },
    // included when options.include_optional_metadata is true
    "primary_color": "#1f1f1f",
    "url": "https://plaid.com",
    "logo": null
  },
  "request_id": "m8MDnv9okwxFNBV"
}

Institution schema

Field	Description
`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.

Institution status schema

Field	Description
`item_logins` Object	Status information about the institution's performance for Item adds via Link. View schema.
`transactions_status` Object	Status information about the institution's performance for transactions updates. View schema.

Institution status

The status of an institution is determined by the health of its Item login and Transactions update attempts. 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.


"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": "HEALTHLY",
    "last_status_change": "2019-02-12T08:22:00Z",
    "breakdown": {
      "success": 0.95,
      "error_plaid": 0.02,
      "error_institution": 0.03,
      "refresh_interval": "NORMAL"
  }
}

Item logins status schema

Field	Description
`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.

Field	Description
`success` Number	Proportion of Item logins that were successful.
`error_plaid` Number	Proportion of Item logins that failed due to an internal Plaid issue.
`error_institution` Number	Proportion of Item logins that failed due to an issue in the institution's system.

Institution status in Link

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 an institution is DEGRADED, Link will warn users that they may experience issues and allow them to continue. Once an institution becomes DOWN, Link will block users from attempting to login and suggest they find another bank.

Institution status in Link

Transactions updates status schema

Field	Description
`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.

Field	Description
`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.

Sandbox

Creating Items in the Sandbox

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


https://sandbox.plaid.com

Via Link

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.

Programatically

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

Field	Required?	Description
`institution_id` String	Yes
`public_key` String	Yes
`initial_products` [String]	Yes	The products to initially pull for the `Item`. May be any products that the specified `institution_id` supports.
`options` Object, optional	No	If provided, must be non-null.

The following options are available:

Field	Default	Description
`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.


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


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


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


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


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


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

Test credentials

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. You can also customize the accounts for each Item you create in the Sandbox.

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:

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

Testing Auth

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

Step	Instant Match	Automated Micro-deposits	Same Day Micro-deposits
Institution	Houndstooth Bank	Houndstooth Bank	N/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 #1	N/A	N/A	`$0.01`
Micro-deposit #2	N/A	N/A	`$0.02`
Sandbox timeline	Instant	Approximately 6 hours	Verify within minutes

Testing errors

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


username: user_good
password: error_ERROR_CODE // ex: error_INVALID_CREDENTIALS

Testing with random account and transaction data

Use the username user_custom and the password {} to create an Item with randomly generated accounts and transactions.


username: user_custom
password: {}

Testing with customized accounts

You can use the username user_custom and a stringified JSON password with any Sandbox institution to customize the accounts created with the Item. You can control account types and subtypes, balances, inflows, and names. There is also more varied transaction data when using the username user_custom.

If the password is not valid stringified JSON, a INVALID_CREDENTIALS error will be returned.


username: user_custom
// the password must be stringified JSON
password: { override_accounts: [{ ... }] }

override_accounts schema

Key	Description
`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.
`type` String	This will be used as the account type.
`subtype` String	This will be used as the account subtype.
`meta` Object, optional	If provided, the metadata for this account will be overriden. View `meta` schema.
`inflow_model` Object, optional	If provided, the inflow model used by this account will be overridden. View `inflow_model` schema.

meta schema

Key	Description
`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.
`number` String, optional	This will be used as the account’s number.
`limit` Number, optional	This will be used as the account’s limit.

inflow_model schema

Key	Description
`type` String	Inflow model, either `none` or `monthly-income`.
`income_amount` Number	Amount of income per month.
`payment_day_of_month` String	`1`, `15`, or `last`. The day of the month on which the income transaction should appear. ‘last’ means the last day of the month.
`transaction_name` String	The name that the income transaction should have.


// 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 '{
  "public_key": "PUBLIC_KEY",
  "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 '{
  "public_key": "PUBLIC_KEY",
  "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"}}]}'
        }
    )


// Generate a public_token for an Item with customized income
client.sandboxPublicTokenCreate('ins_109508', ['transactions'], {
  override_username: 'user_custom',
  override_password: JSON.stringify({
    override_accounts: [{
      type: "depository",
      subtype: "checking",
      inflow_model: {
        type: "monthly-income",
        income_amount: 10000,
        payment_day_of_month: "last",
        transaction_name: "PAYCHECK"
      }
    }]
  })
}, function(err, createResponse) {
  // Handle error, if present
  var publicToken = createResponse.public_token;
  // The generated public_token can now be exchanged
  // for an access_token
});


curl -X POST https://sandbox.plaid.com/sandbox/public_token/create \
-H 'Content-Type: application/json' \
-d '{
  "public_key": "PUBLIC_KEY",
  "institution_id": "ins_109508",
  "initial_products": ["transactions"],
  "options": {
    "override_username": "user_custom",
    "override_password": "{\"override_accounts\":[{\"type\":\"depository\",\"subtype\":\"checking\",\"inflow_model\":{\"type\":\"monthly-income\",\"income_amount\":10000,\"payment_day_of_month\":\"last\",\"transaction_name\":\"PAYCHECK\"}}]}"
  }
}'


# Generate a public_token for an Item with customized income
create_response = client.sandbox.sandbox_public_token.create(
  institution_id: 'ins_109508',
  initial_products: ['transactions']
  override_username: 'user_custom',
  override_password: '{"override_accounts":[{"type":"depository","subtype":"checking","inflow_model":{"type":"monthly-income","income_amount":10000,"payment_day_of_month":"last","transaction_name":"PAYCHECK"}}]}'
)


curl -X POST https://sandbox.plaid.com/sandbox/public_token/create \
-H 'Content-Type: application/json' \
-d '{
  "public_key": "PUBLIC_KEY",
  "institution_id": "ins_109508",
  "initial_products": ["transactions"],
  "options": {
    "override_username": "user_custom",
    "override_password": "{\"override_accounts\":[{\"type\":\"depository\",\"subtype\":\"checking\",\"inflow_model\":{\"type\":\"monthly-income\",\"income_amount\":10000,\"payment_day_of_month\":\"last\",\"transaction_name\":\"PAYCHECK\"}}]}"
  }
}'


# Generate a public_token for an Item with customized income
create_response = \
    client.Sandbox.public_token.create(
        'ins_109508',
        ['transactions'],
        {
            override_username='user_custom',
            override_password='{"override_accounts":[{"type":"depository","subtype":"checking","inflow_model":{"type":"monthly-income","income_amount":10000,"payment_day_of_month":"last","transaction_name":"PAYCHECK"}}]}')
        }
    )

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:

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

Use the username user_good for integration tests as the data will be deterministic.

Managing Item states

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

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

Simulating `ITEM_LOGIN_REQUIRED` errors

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

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

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

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

Simulate Item error


POST /sandbox/item/reset_login


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)


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

Field	Required?
`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 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')


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

Overview

Introduction

Glossary

API keys and access

API protocols

API host

Endpoints

Versioning

Breaking changes

We consider the following changes to be backwards compatible:

Storing Plaid API identifiers

Store access_tokens and item_ids in your application database

access_token

item_id

asset_report_token

asset_report_id

Log API request identifiers

request_id

link_session_id

Retrieve transaction or account ids

account_id

transaction_id

Status

System status

Institution and Item status

In the Dashboard

Via the API

Creating Items with Plaid Link

Integrating with Link

Parameter reference

onSuccess callback

onExit callback

Metadata status

onEvent callback

Event names

Metadata Reference

Metadata view_name

open() function

exit() function

Exchange Token flow

Exchange Token

Creating Public Tokens

Create Public Token

Updating Items via Link

iOS bindings

Looking to get started right away?

WebView integration

Looking to get started right away?

Communication between Link and your app

connected event

exit event

event event

WebView examples

Browser & Platform support

Desktop

iOS

Android

Item product access

Auth

Enabling all Auth features

Verifying Same Day Microdeposits

Retrieve Auth request

ACH numbers schema

EFT numbers schema

International numbers schema

BACS numbers schema

Transactions

Retrieve Transactions request

Transaction schema

Transaction location schema

Transaction payment_meta schema

Item transaction updates

Full transaction history

Balance

Retrieve Balance request

Balances schema

Identity

Retrieve Identity request

Identity schema

Phone numbers schema

Metadata `status`

Metadata `view_name`

`connected` event

`exit` event

`event` event