Overview

Introduction

COPY

COPIED!

Welcome to Plaid! Here you’ll find information for integrating with our Asset Verification API. We’ve tried to make this documentation user-friendly and example-filled, but if you have any questions, please reach out directly to integrations@plaid.com or head to our Help Center.

Core concepts

COPY

COPIED!

An Item represents a set of user credentials for a given financial institution, for example a consumer’s relationship with Wells Fargo. An Item can have multiple Accounts, for example "Everyday Checking" and “Platinum Savings”. An Account can have multiple Transactions, for example “9/27 Charity: Water Charity: W 160926 Global”.

A single end-user of yours might have accounts at different financial institutions, which means they would have multiple Items, one for each institution.

An Asset Report is a collection of data from one or more Items, plus data you submit.

Access and keys

COPY

COPIED!

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 you with a live client_id, secret, and public_key via the Dashboard.

Your public_key is a non-sensitive, public identifier that is used to initialize Plaid Link (more on Link below).

Your client_id and secret are private identifiers that are required for accessing any financial data. These should never be shared in client-side code.

Protocols

COPY

COPIED!

The Plaid API uses POST requests to communicate and HTTP response codes to indicate status and errors. 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.

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

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 our Sandbox and Development environments. All requests to Production will be billed. When you’re getting ready to launch into Production, please request Production API access via the Dashboard.

Endpoints

COPY

COPIED!

Link

/item/public_token/exchange
/item/public_token/create

Item management

/accounts/get
/item/get
/item/webhook/update
/item/access_token/invalidate
/item/access_token/update_version
/item/remove

Asset Report management

/asset_report/create
/asset_report/remove
/asset_report/audit_copy/create
/asset_report/audit_copy/remove

Asset Report access

/asset_report/get
/asset_report/pdf/get

Storing API response data

COPY

COPIED!

It is important to securely store the access_token and item_id associated with each Item you create (we'll walk through how to create Items in the Quickstart below). The access_token is used to include data for that Item in an Asset Report and to generate public_tokens for the Item for use with Link’s update mode. The item_id is included as the identifying property in all webhooks. You should securely store both of these values.

All API responses and Link client-side callbacks include a unique request_id, even when an error occurs. We recommend persisting this value for internal logging purposes, as well as for support-related escalations. More information about how to access a request_id can be found in the Help Center.

// EXAMPLE ITEM
{
 "access_token": "access-sandbox-e9317406-8413-43c6",
 "item": {
   "available_products": [
     "balance",
     "auth",
     "identity",
     "transactions"
   ],
   "billed_products": [
     “assets”
   ],
   "error": null,
   "institution_id": "ins_109508",
   "item_id": "Ed6bjNrDLJfGvZWwnkQlfxwoNz54B5C97ejBr",
   "webhook": "https://plaid.com/example/hook"
 },
 "request_id": "qpCtl"
}

Quickstart

Quickstart Overview

COPY

COPIED!

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

1. Create Items for each of the user’s institutions, using Plaid Link

2. Create the Asset Report using the access_tokens for each of those Items

3. Retrieve the Asset Report in your desired format

4. Share the Asset Report (optional) by obtaining an audit_copy_token and then passing it to a participating third party, for example Fannie Mae as part of its Day 1 Certainty™ program

In this integration guide, we’ll walk you through how to implement each of these steps. After this guide, you’ll find an Appendix which describes the data fields available as part of the Asset Report.

Obtaining API keys

COPY

COPIED!

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

Creating Items with Link

COPY

COPIED!

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 financial accounts to Plaid.

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

Client-side

Link’s integration is a pure JavaScript approach that you trigger via your own client-side code. Once you have your public_key from the Dashboard, the Link JavaScript integration is fairly straightforward.

To launch Link within your application experience, the following is all you need:

Copy

// CLIENT-SIDE LINK INTEGRATION

<button id="link-button">Link Your Account</button>

<script src="https://cdn.plaid.com/link/v2/stable/link-initialize.js"></script>
<script type="text/javascript">

var handler = Plaid.create({
  clientName: 'Plaid Asset Verification Demo',
  env: 'sandbox',
  key: '<PUBLIC_KEY>', // Replace with your public_key to test with live credentials
  product: ['assets'],
  webhook: '<WEBHOOK_URL>', // Optional – use webhooks to get transaction and error updates
  selectAccount: false, // Optional – trigger the Select Account
  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, if `selectAccount` 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.
  }
});

$('#link-button').on('click', function(e) {
  handler.open();
});

</script>

When your user clicks the “Link Your Account” button in the above example, Link will open to the 'Institution Select' view so the user can choose which financial institution to authenticate. From that point, Link takes care of credential validation, multi-factor authentication, and error handling.

You can customize the .create() method on the global Plaid object to suit your needs. The Link parameter reference has a full rundown of your options.

Note: In order for an access_token to be used to generate an Asset Report, it must have been generated via Link with assets included in the product array, as shown in the example above.

Once the user has successfully authenticated within Link, the onSuccess callback gets triggered. The onSuccess callback takes two arguments, the public_token and a metadata object.

The metadata object provides an institution object with two properties: name and institution_id. name is the full name of the institution the user authenticated, such as ‘Bank of America’, and institution_id is the Plaid identifier for that institution, such as ‘ins_100000’. You might use this data, for example, to populate a list of successfully authenticated institutions for the user in your user interface.

The metadata object also provides a link_session_id string, which is a unique identifier associated with a user’s actions and events through the Link flow, and can be included when opening a support ticket for faster turnaround.

// METADATA SCHEMA

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

The public_token is a one-time use token which you’ll send back to your server, where you’ll exchange it via the Plaid API for the Item’s private access_token.

Server-side

To exchange the public_token for the Item’s private access_token, simply call the /item/public_token/exchange endpoint from your server-side handler.

Copy

// EXCHANGE TOKEN REQUEST

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-fb7cca4a-82e6-4707"
 }'

EXCHANGE TOKEN RESPONSE

http code 200
{
   "access_token": "asset-sandbox-7c69d345-fd46-461f",
   "item_id": "M5eVJqLnv3tbzdngLDp9FL5OlDNxlNhlE55op",
   "request_id": "Aim3b"
}

Save the access_token and item_id in a secure datastore, as they’re used to access Item data and identify webhooks, respectively. The public_token is a one-time use token, so there is no need to store it.

Next steps

At this point, you’ve successfully had the user create an Item, received the public_token from Link, and exchanged it for an access_token. You’ll use the access_token to include this Item in the Asset Report we’ll create in the next section.

If users need to link accounts at multiple institutions, simply repeat the Link flow above, each time instructing them to authenticate their next institution until they have linked all of their intended Items. You can include multiple Items in a single Asset Report, you just need an access_token for each Item you want to included.

Creating an Asset Report

COPY

COPIED!

Asset Reports are point-in-time snapshots of an Item or set of Items, including account balances, historical transactions, and account holder identity information. 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 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 would simply create a new Asset Report by submitting the same access_tokens and other information you provided when creating the original report.

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

Note: In order for an access_token to be used to generate an Asset Report, it must have been generated via Link with assets included in the Link .create() method's product array, as shown above.

Copy

// CREATE ASSET REPORT REQUEST

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

CREATE ASSET REPORT RESPONSE

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

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.

Retrieving an Asset Report

COPY

COPIED!

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.

// REPORT GENERATION SUCCESSFUL WEBHOOK
{
  "asset_report_id": String,
  "webhook_code": "PRODUCT_READY",
  "webhook_type": "ASSETS"
}

If Asset Report generation fails, Plaid will send a webhook indicating why generation failed.

// REPORT GENERATION FAILED WEBHOOK
{
  "asset_report_id": String,
  "error": {
    "display_message": String,
    "error_code": String,
    "error_message": String,
    "error_type": "ASSET_REPORT_ERROR"
  },
  "webhook_code": "ERROR",
  "webhook_type": "ASSETS"
}

Formats

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

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

Copy

// RETRIEVE JSON FORMAT REPORT REQUEST

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

For a detailed layout of the retrieve JSON format report response, please see the Assets parameter reference.

PDF -- To retrieve the Asset Report as a pre-formatted PDF, call the /asset_report/pdf/get endpoint.

Copy

// RETRIEVE PDF FORMAT REPORT REQUEST

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'

On success, the request id for /asset_report/pdf/get is returned in the Plaid-Request-ID header.

Sharing an Audit Copy

COPY

COPIED!

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:

Copy

CREATE AUDIT COPY REQUEST

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

CREATE AUDIT COPY RESPONSE

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

Removing Asset Reports and Audit Copies

COPY

COPIED!

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.

Copy

// REMOVE ASSET REPORT REQUEST

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

REMOVE ASSET REPORT RESPONSE

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

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.

Copy

// REMOVE AUDIT COPY REQUEST

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

REMOVE AUDIT COPY RESPONSE

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

Parameter reference

Asset Report Creation

COPY

COPIED!

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.

/asset_report/create request parameters

Field	Type	Description
client_id	string	Your client_id
secret	string	Your secret
access_tokens	list of strings	An array of access tokens, one token for each Item to be included in the Asset Report.
days_requested	integer	Days of transaction history requested to be included in the Asset Report. Plaid will return as much data as possible within the implied date range, up to a maximum of 730 days (2 years) of history.
client_report_id	string	Client-generated identifier, for example used by lenders to track track loan applications.
webhook	string	URL to which Plaid will send a webhook when the requested Asset Report is ready.
user	User object	Data submitted by you about the user whose Asset Report is being compiled. See User object for fields.

User object

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

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

Asset Report Retrieval

COPY

COPIED!

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

/asset_report/get response parameters

Field	Type	Description
report	Report object	The data comprising the asset report. See Report object for fields.
request_id	string	A unique identifier included in Plaid success and error responses. This can be shared with Plaid Support to expedite investigation.
warnings	Warning objects (list)

Report object

Field	Type	Description
asset_report_id	string	Plaid’s unique identifier for this asset report
client_report_id	string	An identifier you determine and submit for the Asset Report
date_generated	datetime	The date and time when the Asset Report was created
days_requested	integer	The duration of transaction history you requested
user	User object	Data submitted by you about the user whose Asset Report is being compiled; See User object for fields
items	Item objects (list)	Data returned by Plaid about each of the Items included in the Asset Report; See Item object for fields

Item object

Field	Type	Description
item_id	string	Plaid’s unique identifier for the Item
institution_name	string	The full financial institution name associated with the Item
institution_id	string	The financial institution associated with the Item
date_last_updated	datetime	The date and time when this Item’s data was retrieved from the financial institution
accounts	Account objects (list)	Data about each of the accounts open on the Item. See Account object for fields

Account object

Field	Type	Description
account_id	string	Plaid’s unique identifier for the account
mask	string	The last 2-5 digits of the account's number
name	string	The name of the account, either assigned by the user or by the financial institution itself
official_name	string	The official name of the account as given by the financial institution
type	string	See below
subtype	string	See below
owners	Owner objects (list)	Data returned by the financial institution about the account owner or owners; See Owner object for fields
balances	Balance object	Data about the various balances on the account; See Balance object for fields
historical_balances	Historical balance objects (list)	Calculated data about the historical balances on the account; see Historical balance object for fields
transactions	Transaction objects (list)	Data about the transactions
days_available	integer	The duration of transaction history available for this Item, typically defined as the time since the date of the earliest transaction in that account.

Account type and subtype are indicated as follows:

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

Owner object

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

Field	Type	Description
names	strings (list)	A list of names associated with the account by the financial institution
phone_numbers	Phone number objects (list)	A list of phone numbers associated with the account by the financial institution; See Phone number object for fields
emails	Email number objects (list)	A list of emails associated with the account by the financial institution; See Email object for fields
addresses	Address objects (list)	Data about the various addresses associated with the account by the financial institution; See Address object for fields

Phone number object

Field	Type	Description
data	string	The phone number
primary	boolean	When true, identifies the phone number as the primary number on an account
type	string	The type of phone number as described by the financial institution. Example: "mobile"

Email object

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

Address object

Field	Type	Description
data	Address data object	Data about the components comprising an address. See Address data object for fields.
primary	boolean	When true, identifies the address as the primary address on an account

Address data object

Field	Type	Description
city	string	The full city name
state	string	The two-letter state abbreviation. Example: "NC"
street	string	The full street address. Example: “564 Main Street, APT 15”
zip	string	The five or nine digit postal code

Balance object

Field	Type	Description
available	decimal	The current balance less any outstanding holds or debits that have not yet posted to the account Not all institutions calculate the available balance; In the event that available balance is unavailable from the institution, Plaid will return an available balance value of null
current	decimal	The total amount of funds in the account

Historical balance object

Field	Type	Description
date	date	The date of the calculated historical balance
current	decimal	The total amount of funds in the account, calculated from the current balance in the balance object by subtracting inflows and adding back outflows according to the posted date of each

Transaction object

Field	Type	Description
account_id	string	Plaid’s unique identifier for the account
transaction_id	string	Plaid’s unique identifier for the transaction
date	date	For pending transactions, Plaid returns the date the transaction occurred; for posted transactions, Plaid returns the date the transaction posts. Both dates are returned in an ISO 8601 format (YYYY-MM-DD).
original_description	string	The string returned by the financial institution to describe the transaction
pending	boolean	When true, identifies the transaction as pending or unsettled. Pending transaction details (description, amount) may change before they are settled.
amount	decimal	The settled dollar value. Positive values when money moves out of the account; negative values when money moves in. For example, purchases are positive; credit card payments, direct deposits, refunds are negative.