Assets

API reference for Assets endpoints and webhooks

Create, delete, retrieve and share Asset Reports with information about a user's assets and transactions.

Endpoints
/asset_report/createCreate an Asset Report
/asset_report/getGet an Asset Report
/asset_report/pdf/getGet a PDF Asset Report
/asset_report/refreshCreate an updated Asset Report
/asset_report/filterFilter unneeded accounts from an Asset Report
/asset_report/removeDelete an asset report
/asset_report/audit_copy/createCreate an Audit Copy of an Asset Report for sharing
/asset_report/audit_copy/removeDelete an Audit Copy of an Asset Report
Webhooks
PRODUCT_READYAsset Report generation has completed
ERRORAsset Report generation has failed

Endpoints

/asset_report/create

Create an Asset Report

The /asset_report/create endpoint initiates the process of creating an Asset Report, which can then be retrieved by passing the asset_report_token return value to the /asset_report/get or /asset_report/pdf/get endpoints.
The Asset Report takes some time to be created and is not available immediately after calling /asset_report/create. When the Asset Report is ready to be retrieved using /asset_report/get or /asset_report/pdf/get, Plaid will fire a PRODUCT_READY webhook. For full details of the webhook schema, see Asset Report webhooks.
The /asset_report/create endpoint creates an Asset Report at a moment in time. Asset Reports are immutable. To get an updated Asset Report, use the /asset_report/refresh endpoint.

asset_report/create

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
access_tokens
required[string]
An array of access tokens corresponding to the Items that will be included in the report. The assets product must have been initialized for the Items during link; the Assets product cannot be added after initialization.

Min items: 1
Max items: 99
days_requested
requiredinteger
The maximum integer number of days of history to include in the Asset Report. If using Fannie Mae Day 1 Certainty, days_requested must be at least 61 for new originations or at least 31 for refinancings.
An Asset Report requested with "Additional History" (that is, with more than 61 days of transaction history) will incur an Additional History fee.

Maximum: 731
Minimum: 0
options
object
An optional object to filter /asset_report/create results. If provided, must be non-null. The optional user object is required for the report to be eligible for Fannie Mae's Day 1 Certainty program.
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
The user object allows you to provide additional information about the user to be appended to the Asset Report. All fields are optional. The first_name, last_name, and ssn fields are required if you would like the Report to be eligible for Fannie Mae’s Day 1 Certainty™ program.
client_user_id
string
An identifier you determine and submit for the user.
first_name
string
The user's first name. Required for the Fannie Mae Day 1 Certainty™ program.
middle_name
string
The user's middle name
last_name
string
The user's last name. Required for the Fannie Mae Day 1 Certainty™ program.
ssn
string
The user's Social Security Number. Required for the Fannie Mae Day 1 Certainty™ program.
Format: "ddd-dd-dddd"
phone_number
string
The user's phone number, in E.164 format: +{countrycode}{number}. For example: "+14151234567". Phone numbers provided in other formats will be parsed on a best-effort basis.
email
string
The user's email address.
Select group for content switcher
1const daysRequested = 60;
2const options = {
3  client_report_id: '123',
4  webhook: 'https://www.example.com',
5  user: {
6    client_user_id: '7f57eb3d2a9j6480121fx361',
7    first_name: 'Jane',
8    middle_name: 'Leah',
9    last_name: 'Doe',
10    ssn: '123-45-6789',
11    phone_number: '(555) 123-4567',
12    email: 'jane.doe@example.com',
13  },
14};
15const request: AssetReportCreateRequest = {
16  access_tokens: [accessToken],
17  days_requested,
18  options,
19};
20// accessTokens is an array of Item access tokens.
21// Note that the assets product must be enabled for all Items.
22// All fields on the options object are optional.
23try {
24  const response = await plaidClient.assetReportCreate(request);
25  const assetReportId = response.data.asset_report_id;
26  const assetReportToken = response.data.asset_report_token;
27} catch (error) {
28  // handle error
29}
asset_report/create

Response fields and example

asset_report_token
string
A token that can be provided to endpoints such as /asset_report/get or /asset_report/pdf/get to fetch or update an Asset Report.
asset_report_id
string
A unique ID identifying an Asset Report. Like all Plaid identifiers, this ID is case sensitive.
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "asset_report_token": "assets-sandbox-6f12f5bb-22dd-4855-b918-f47ec439198a",
3  "asset_report_id": "1f414183-220c-44f5-b0c8-bc0e6d4053bb",
4  "request_id": "Iam3b"
5}

/asset_report/get

Retrieve an Asset Report

The /asset_report/get endpoint retrieves the Asset Report in JSON format. Before calling /asset_report/get, you must first create the Asset Report using /asset_report/create (or filter an Asset Report using /asset_report/filter) and then wait for the PRODUCT_READY webhook to fire, indicating that the Report is ready to be retrieved.
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.
To retrieve an Asset Report with Insights, call the /asset_report/get endpoint with include_insights set to true.

asset_report/get

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
asset_report_token
requiredstring
A token that can be provided to endpoints such as /asset_report/get or /asset_report/pdf/get to fetch or update an Asset Report.
include_insights
boolean
true if you would like to retrieve the Asset Report with Insights, false otherwise. This field defaults to false if omitted.

Default: false
Select group for content switcher
1const request: request = {
2  asset_report_token: assetReportToken,
3  include_insights: true,
4};
5try {
6  const response = await plaidClient.assetReportGet(request);
7  const assetReportId = response.data.asset_report_id;
8} catch (error) {
9  if (error.data.error_code == 'PRODUCT_NOT_READY') {
10    // Asset report is not ready yet. Try again later
11  } else {
12    // handle error
13  }
14}
asset_report/get

Response fields and example

report
object
An object representing an Asset Report
asset_report_id
string
A unique ID identifying an Asset Report. Like all Plaid identifiers, this ID is case sensitive.
client_report_id
nullable string
An identifier you determine and submit for the Asset Report.
date_generated
string
The date and time when the Asset Report was created, in ISO 8601 format (e.g. "2018-04-12T03:32:11Z").

Format: date-time
days_requested
number
The duration of transaction history you requested
user
object
The user object allows you to provide additional information about the user to be appended to the Asset Report. All fields are optional. The first_name, last_name, and ssn fields are required if you would like the Report to be eligible for Fannie Mae’s Day 1 Certainty™ program.
client_user_id
nullable string
An identifier you determine and submit for the user.
first_name
nullable string
The user's first name. Required for the Fannie Mae Day 1 Certainty™ program.
middle_name
nullable string
The user's middle name
last_name
nullable string
The user's last name. Required for the Fannie Mae Day 1 Certainty™ program.
ssn
nullable string
The user's Social Security Number. Required for the Fannie Mae Day 1 Certainty™ program.
Format: "ddd-dd-dddd"
phone_number
nullable string
The user's phone number, in E.164 format: +{countrycode}{number}. For example: "+14151234567". Phone numbers provided in other formats will be parsed on a best-effort basis.
email
nullable string
The user's email address.
items
[object]
Data returned by Plaid about each of the Items included in the Asset Report.
item_id
string
The item_id of the Item associated with this webhook, warning, or error
institution_name
string
The full financial institution name associated with the Item.
institution_id
string
The id of the financial institution associated with the Item.
date_last_updated
string
The date and time when this Item’s data was last retrieved from the financial institution, in ISO 8601 format.

Format: date-time
accounts
[object]
Data about each of the accounts open on the Item.
account_id
string
Plaid’s unique identifier for the account. This value will not change unless Plaid can't reconcile the account with the data returned by the financial institution. This may occur, for example, when the name of the account changes. If this happens a new account_id will be assigned to the account.
The account_id can also change if the access_token is deleted and the same credentials that were used to generate that access_token are used to generate a new access_token on a later date. In that case, the new account_id will be different from the old account_id.
If an account with a specific account_id disappears instead of changing, the account is likely closed. Closed accounts are not returned by the Plaid API.
Like all Plaid identifiers, the account_id is case sensitive.
balances
object
A set of fields describing the balance for an account. Balance information may be cached unless the balance object was returned by /accounts/balance/get.
available
nullable number
The amount of funds available to be withdrawn from the account, as determined by the financial institution.
For credit-type accounts, the available balance typically equals the limit less the current balance, less any pending outflows plus any pending inflows.
For depository-type accounts, the available balance typically equals the current balance less any pending outflows plus any pending inflows. For depository-type accounts, the available balance does not include the overdraft limit.
For investment-type accounts (or brokerage-type accounts for API versions 2018-05-22 and earlier), the available balance is the total cash available to withdraw as presented by the institution.
Note that not all institutions calculate the available balance. In the event that available balance is unavailable, Plaid will return an available balance value of null.
Available balance may be cached and is not guaranteed to be up-to-date in realtime unless the value was returned by /accounts/balance/get.
If current is null this field is guaranteed not to be null.

Format: double
current
nullable number
The total amount of funds in or owed by the account.
For credit-type accounts, a positive balance indicates the amount owed; a negative amount indicates the lender owing the account holder.
For loan-type accounts, the current balance is the principal remaining on the loan, except in the case of student loan accounts at Sallie Mae (ins_116944). For Sallie Mae student loans, the account's balance includes both principal and any outstanding interest.
For investment-type accounts (or brokerage-type accounts for API versions 2018-05-22 and earlier), the current balance is the total value of assets as presented by the institution.
Note that balance information may be cached unless the value was returned by /accounts/balance/get; if the Item is enabled for Transactions, the balance will be at least as recent as the most recent Transaction update. If you require realtime balance information, use the available balance as provided by /accounts/balance/get.
When returned by /accounts/balance/get, this field may be null. When this happens, available is guaranteed not to be null.

Format: double
limit
nullable number
For credit-type accounts, this represents the credit limit.
For depository-type accounts, this represents the pre-arranged overdraft limit, which is common for current (checking) accounts in Europe.
In North America, this field is typically only available for credit-type accounts.

Format: double
iso_currency_code
nullable string
The ISO-4217 currency code of the balance. Always null if unofficial_currency_code is non-null.
unofficial_currency_code
nullable string
The unofficial currency code associated with the balance. Always null if iso_currency_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.
See the currency code schema for a full listing of supported unofficial_currency_codes.
last_updated_datetime
nullable string
Timestamp in ISO 8601 format (YYYY-MM-DDTHH:mm:ssZ) indicating the last time that the balance for the given account has been updated
This is currently only provided when the min_last_updated_datetime is passed when calling /accounts/balance/get for ins_128026 (Capital One).

Format: date-time
mask
nullable string
The last 2-4 alphanumeric characters of an account's official account number. Note that the mask may be non-unique between an Item's accounts, and it may also not match the mask that the bank displays to the user.
name
string
The name of the account, either assigned by the user or by the financial institution itself
official_name
nullable string
The official name of the account as given by the financial institution
type
string
investment: Investment account. In API versions 2018-05-22 and earlier, this type is called brokerage instead.
credit: Credit card
depository: Depository account
loan: Loan account
other: Non-specified account type
See the Account type schema for a full listing of account types and corresponding subtypes.

Possible values: investment, credit, depository, loan, brokerage, other
subtype
nullable string
See the Account type schema for a full listing of account types and corresponding subtypes.

Possible values: 401a, 401k, 403B, 457b, 529, brokerage, cash isa, education savings account, ebt, fixed annuity, gic, health reimbursement arrangement, hsa, isa, ira, lif, life insurance, lira, lrif, lrsp, non-taxable brokerage account, other, other insurance, other annuity, 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, trust, ugma, utma, variable annuity, credit card, paypal, cd, checking, savings, money market, prepaid, auto, business, commercial, construction, consumer, home equity, loan, mortgage, overdraft, line of credit, student, cash management, keogh, mutual fund, recurring, rewards, safe deposit, sarsep, payroll, null
verification_status
string
The current verification status of an Auth Item initiated through Automated or Manual micro-deposits. Returned for Auth Items only.
pending_automatic_verification: The Item is pending automatic verification
pending_manual_verification: The Item is pending manual micro-deposit verification. Items remain in this state until the user successfully verifies the two amounts.
automatically_verified: The Item has successfully been automatically verified
manually_verified: The Item has successfully been manually verified
verification_expired: Plaid was unable to automatically verify the deposit within 7 calendar days and will no longer attempt to validate the Item. Users may retry by submitting their information again through Link.
verification_failed: The Item failed manual micro-deposit verification because the user exhausted all 3 verification attempts. Users may retry by submitting their information again through Link.

Possible values: automatically_verified, pending_automatic_verification, pending_manual_verification, manually_verified, verification_expired, verification_failed
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. Only returned by Assets endpoints.
transactions
[object]
Transaction history associated with the account. Only returned by Assets endpoints. Transaction history returned by endpoints such as /transactions/get or /investments/transactions/get will be returned in the top-level transactions field instead.
transaction_type
deprecatedstring
Please use the payment_channel field, transaction_type will be deprecated in the future.
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.

Possible values: digital, place, special, unresolved
pending_transaction_id
nullable string
The ID of a posted transaction's associated pending transaction, where applicable.
category_id
nullable string
The ID of the category to which this transaction belongs. For a full list of categories, see /categories/get.
If the transactions object was returned by an Assets endpoint such as /asset_report/get/ or /asset_report/pdf/get, this field will only appear in an Asset Report with Insights.
category
nullable [string]
A hierarchical array of the categories to which this transaction belongs. For a full list of categories, see /categories/get.
If the transactions object was returned by an Assets endpoint such as /asset_report/get/ or /asset_report/pdf/get, this field will only appear in an Asset Report with Insights.
location
object
A representation of where a transaction took place
address
nullable string
The street address where the transaction occurred.
city
nullable string
The city where the transaction occurred.
region
nullable string
The region or state where the transaction occurred. In API versions 2018-05-22 and earlier, this field is called state.
postal_code
nullable string
The postal code where the transaction occurred. In API versions 2018-05-22 and earlier, this field is called zip.
country
nullable string
The ISO 3166-1 alpha-2 country code where the transaction occurred.
lat
nullable number
The latitude where the transaction occurred.

Format: double
lon
nullable number
The longitude where the transaction occurred.

Format: double
store_number
nullable string
The merchant defined store number where the transaction occurred.
payment_meta
object
Transaction information specific to inter-bank transfers. If the transaction was not an inter-bank transfer, all fields will be null.
If the transactions object was returned by a Transactions endpoint such as /transactions/get, the payment_meta key will always appear, but no data elements are guaranteed. If the transactions object was returned by an Assets endpoint such as /asset_report/get/ or /asset_report/pdf/get, this field will only appear in an Asset Report with Insights.
reference_number
nullable string
The transaction reference number supplied by the financial institution.
ppd_id
nullable string
The ACH PPD ID for the payer.
payee
nullable string
For transfers, the party that is receiving the transaction.
by_order_of
nullable string
The party initiating a wire transfer. Will be null if the transaction is not a wire transfer.
payer
nullable string
For transfers, the party that is paying the transaction.
payment_method
nullable string
The type of transfer, e.g. 'ACH'
payment_processor
nullable string
The name of the payment processor
reason
nullable string
The payer-supplied description of the transfer.
account_owner
nullable string
The name of the account owner. This field is not typically populated and only relevant when dealing with sub-accounts.
name
string
The merchant name or transaction description.
If the transactions object was returned by a Transactions endpoint such as /transactions/get, this field will always appear. If the transactions object was returned by an Assets endpoint such as /asset_report/get/ or /asset_report/pdf/get, this field will only appear in an Asset Report with Insights.
original_description
nullable string
The string returned by the financial institution to describe the transaction. For transactions returned by /transactions/get, this field is in beta and will be omitted unless the client is both enrolled in the closed beta program and has set options.include_original_description to true.
account_id
string
The ID of the account in which this transaction occurred.
amount
number
The settled value of the transaction, denominated in the account's currency, as stated in iso_currency_code or unofficial_currency_code. Positive values when money moves out of the account; negative values when money moves in. For example, debit card purchases are positive; credit card payments, direct deposits, and refunds are negative.

Format: double
iso_currency_code
nullable string
The ISO-4217 currency code of the transaction. Always null if unofficial_currency_code is non-null.
unofficial_currency_code
nullable string
The unofficial currency code associated with the transaction. Always null if iso_currency_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.
See the currency code schema for a full listing of supported iso_currency_codes.
date
string
For pending transactions, the date that the transaction occurred; for posted transactions, the date that the transaction posted. Both dates are returned in an ISO 8601 format ( YYYY-MM-DD ).

Format: date
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.
transaction_id
string
The unique ID of the transaction. Like all Plaid identifiers, the transaction_id is case sensitive.
merchant_name
nullable string
The merchant name, as extracted by Plaid from the name field.
check_number
nullable string
The check number of the transaction. This field is only populated for check transactions.
date_transacted
nullable string
The date on which the transaction took place, in IS0 8601 format.
owners
[object]
Data returned by the financial institution about the account owner or owners. Only returned by Identity or Assets endpoints. For business accounts, the name reported may be either the name of the individual or the name of the business, depending on the institution. Multiple owners on a single account will be represented in the same owner object, not in multiple owner objects within the array. In API versions 2018-05-22 and earlier, the owners object is not returned, and instead identity information is returned in the top level identity object. For more details, see Plaid API versioning
names
[string]
A list of names associated with the account by the financial institution. These should always be the names of individuals, even for business accounts. If the name of a business is reported, please contact Plaid Support. In the case of a joint account, Plaid will make a best effort to report the names of all account holders.
If an Item contains multiple accounts with different owner names, some institutions will report all names associated with the Item in each account's names array.
phone_numbers
[object]
A list of phone numbers associated with the account by the financial institution. May be an empty array if no relevant information is returned from the financial institution.
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.

Possible values: home, work, office, mobile, mobile1, other
emails
[object]
A list of email addresses associated with the account by the financial institution. May be an empty array if no relevant information is returned from the financial institution.
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.

Possible values: primary, secondary, other
addresses
[object]
Data about the various addresses associated with the account by the financial institution. May be an empty array if no relevant information is returned from the financial institution.
data
object
Data about the components comprising an address.
city
string
The full city name
region
nullable string
The region or state. In API versions 2018-05-22 and earlier, this field is called state. Example: "NC"
street
string
The full street address Example: "564 Main Street, APT 15"
postal_code
nullable string
The postal code. In API versions 2018-05-22 and earlier, this field is called zip.
country
nullable string
The ISO 3166-1 alpha-2 country code
primary
boolean
When true, identifies the address as the primary address on an account.
historical_balances
[object]
Calculated data about the historical balances on the account. Only returned by Assets endpoints and currently not supported by brokerage or investment accounts.
date
string
The date of the calculated historical balance, in an ISO 8601 format (YYYY-MM-DD)

Format: date
current
number
The total amount of funds in the account, calculated from the current balance in the balance object by subtracting inflows and adding back outflows according to the posted date of each transaction.
If the account has any pending transactions, historical balance amounts on or after the date of the earliest pending transaction may differ if retrieved in subsequent Asset Reports as a result of those pending transactions posting.

Format: double
iso_currency_code
nullable string
The ISO-4217 currency code of the balance. Always null if unofficial_currency_code is non-null.
unofficial_currency_code
nullable string
The unofficial currency code associated with the balance. Always null if iso_currency_code is non-null.
See the currency code schema for a full listing of supported iso_currency_codes.
warnings
[object]
If the Asset Report generation was successful but identity information cannot be returned, this array will contain information about the errors causing identity information to be missing
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.

Possible values: OWNERS_UNAVAILABLE
cause
nullable object
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. Error fields will be null if no error has occurred.
error_type
string
A broad categorization of the error. Safe for programmatic use.

Possible values: INVALID_REQUEST, INVALID_RESULT, INVALID_INPUT, INSTITUTION_ERROR, RATE_LIMIT_EXCEEDED, API_ERROR, ITEM_ERROR, ASSET_REPORT_ERROR, RECAPTCHA_ERROR, OAUTH_ERROR, PAYMENT_ERROR, BANK_TRANSFER_ERROR, INCOME_VERIFICATION_ERROR
error_code
string
The particular error code. 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
nullable string
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.
request_id
string
A unique ID identifying the request, to be used for troubleshooting purposes. This field will be omitted in errors provided by webhooks.
causes
array
In the Assets product, a request can pertain to more than one Item. If an error is returned for such a request, causes will return an array of errors containing a breakdown of these errors on the individual Item level, if any can be identified.
causes will only be provided for the error_type ASSET_REPORT_ERROR. causes will also not be populated inside an error nested within a warning object.
status
nullable number
The HTTP status code associated with the error. This will only be returned in the response body when the error information is provided via a webhook.
documentation_url
string
The URL of a Plaid documentation page with more information about the error
suggested_action
nullable string
Suggested steps for resolving the error
item_id
string
The item_id of the Item associated with this webhook, warning, or error
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "report": {
3    "asset_report_id": "bf3a0490-344c-4620-a219-2693162e4b1d",
4    "client_report_id": "123abc",
5    "date_generated": "2020-06-05T22:47:53Z",
6    "days_requested": 3,
7    "items": [
8      {
9        "accounts": [
10          {
11            "account_id": "3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr",
12            "balances": {
13              "available": 200,
14              "current": 210,
15              "iso_currency_code": "USD",
16              "limit": null,
17              "unofficial_currency_code": null
18            },
19            "days_available": 3,
20            "historical_balances": [
21              {
22                "current": 210,
23                "date": "2020-06-04",
24                "iso_currency_code": "USD",
25                "unofficial_currency_code": null
26              },
27              {
28                "current": 210,
29                "date": "2020-06-03",
30                "iso_currency_code": "USD",
31                "unofficial_currency_code": null
32              },
33              {
34                "current": 210,
35                "date": "2020-06-02",
36                "iso_currency_code": "USD",
37                "unofficial_currency_code": null
38              }
39            ],
40            "mask": "1111",
41            "name": "Plaid Saving",
42            "official_name": "Plaid Silver Standard 0.1% Interest Saving",
43            "owners": [
44              {
45                "addresses": [
46                  {
47                    "data": {
48                      "city": "Malakoff",
49                      "country": "US",
50                      "postal_code": "14236",
51                      "region": "NY",
52                      "street": "2992 Cameron Road"
53                    },
54                    "primary": true
55                  },
56                  {
57                    "data": {
58                      "city": "San Matias",
59                      "country": "US",
60                      "postal_code": "93405-2255",
61                      "region": "CA",
62                      "street": "2493 Leisure Lane"
63                    },
64                    "primary": false
65                  }
66                ],
67                "emails": [
68                  {
69                    "data": "accountholder0@example.com",
70                    "primary": true,
71                    "type": "primary"
72                  },
73                  {
74                    "data": "accountholder1@example.com",
75                    "primary": false,
76                    "type": "secondary"
77                  },
78                  {
79                    "data": "extraordinarily.long.email.username.123456@reallylonghostname.com",
80                    "primary": false,
81                    "type": "other"
82                  }
83                ],
84                "names": [
85                  "Alberta Bobbeth Charleson"
86                ],
87                "phone_numbers": [
88                  {
89                    "data": "1112223333",
90                    "primary": false,
91                    "type": "home"
92                  },
93                  {
94                    "data": "1112224444",
95                    "primary": false,
96                    "type": "work"
97                  },
98                  {
99                    "data": "1112225555",
100                    "primary": false,
101                    "type": "mobile"
102                  }
103                ]
104              }
105            ],
106            "ownership_type": null,
107            "subtype": "savings",
108            "transactions": [],
109            "type": "depository"
110          },
111          {
112            "account_id": "BxBXxLj1m4HMXBm9WZJyUg9XLd4rKEhw8Pb1J",
113            "balances": {
114              "available": null,
115              "current": 56302.06,
116              "iso_currency_code": "USD",
117              "limit": null,
118              "unofficial_currency_code": null
119            },
120            "days_available": 3,
121            "historical_balances": [],
122            "mask": "8888",
123            "name": "Plaid Mortgage",
124            "official_name": null,
125            "owners": [
126              {
127                "addresses": [
128                  {
129                    "data": {
130                      "city": "Malakoff",
131                      "country": "US",
132                      "postal_code": "14236",
133                      "region": "NY",
134                      "street": "2992 Cameron Road"
135                    },
136                    "primary": true
137                  },
138                  {
139                    "data": {
140                      "city": "San Matias",
141                      "country": "US",
142                      "postal_code": "93405-2255",
143                      "region": "CA",
144                      "street": "2493 Leisure Lane"
145                    },
146                    "primary": false
147                  }
148                ],
149                "emails": [
150                  {
151                    "data": "accountholder0@example.com",
152                    "primary": true,
153                    "type": "primary"
154                  },
155                  {
156                    "data": "accountholder1@example.com",
157                    "primary": false,
158                    "type": "secondary"
159                  },
160                  {
161                    "data": "extraordinarily.long.email.username.123456@reallylonghostname.com",
162                    "primary": false,
163                    "type": "other"
164                  }
165                ],
166                "names": [
167                  "Alberta Bobbeth Charleson"
168                ],
169                "phone_numbers": [
170                  {
171                    "data": "1112223333",
172                    "primary": false,
173                    "type": "home"
174                  },
175                  {
176                    "data": "1112224444",
177                    "primary": false,
178                    "type": "work"
179                  },
180                  {
181                    "data": "1112225555",
182                    "primary": false,
183                    "type": "mobile"
184                  }
185                ]
186              }
187            ],
188            "ownership_type": null,
189            "subtype": "mortgage",
190            "transactions": [],
191            "type": "loan"
192          },
193          {
194            "account_id": "dVzbVMLjrxTnLjX4G66XUp5GLklm4oiZy88yK",
195            "balances": {
196              "available": null,
197              "current": 410,
198              "iso_currency_code": "USD",
199              "limit": null,
200              "unofficial_currency_code": null
201            },
202            "days_available": 3,
203            "historical_balances": [
204              {
205                "current": 410,
206                "date": "2020-06-04",
207                "iso_currency_code": "USD",
208                "unofficial_currency_code": null
209              },
210              {
211                "current": 410,
212                "date": "2020-06-03",
213                "iso_currency_code": "USD",
214                "unofficial_currency_code": null
215              },
216              {
217                "current": 410,
218                "date": "2020-06-02",
219                "iso_currency_code": "USD",
220                "unofficial_currency_code": null
221              }
222            ],
223            "mask": "3333",
224            "name": "Plaid Credit Card",
225            "official_name": "Plaid Diamond 12.5% APR Interest Credit Card",
226            "owners": [
227              {
228                "addresses": [
229                  {
230                    "data": {
231                      "city": "Malakoff",
232                      "country": "US",
233                      "postal_code": "14236",
234                      "region": "NY",
235                      "street": "2992 Cameron Road"
236                    },
237                    "primary": true
238                  },
239                  {
240                    "data": {
241                      "city": "San Matias",
242                      "country": "US",
243                      "postal_code": "93405-2255",
244                      "region": "CA",
245                      "street": "2493 Leisure Lane"
246                    },
247                    "primary": false
248                  }
249                ],
250                "emails": [
251                  {
252                    "data": "accountholder0@example.com",
253                    "primary": true,
254                    "type": "primary"
255                  },
256                  {
257                    "data": "accountholder1@example.com",
258                    "primary": false,
259                    "type": "secondary"
260                  },
261                  {
262                    "data": "extraordinarily.long.email.username.123456@reallylonghostname.com",
263                    "primary": false,
264                    "type": "other"
265                  }
266                ],
267                "names": [
268                  "Alberta Bobbeth Charleson"
269                ],
270                "phone_numbers": [
271                  {
272                    "data": "1112223333",
273                    "primary": false,
274                    "type": "home"
275                  },
276                  {
277                    "data": "1112224444",
278                    "primary": false,
279                    "type": "work"
280                  },
281                  {
282                    "data": "1112225555",
283                    "primary": false,
284                    "type": "mobile"
285                  }
286                ]
287              }
288            ],
289            "ownership_type": null,
290            "subtype": "credit card",
291            "transactions": [],
292            "type": "credit"
293          }
294        ],
295        "date_last_updated": "2020-06-05T22:47:52Z",
296        "institution_id": "ins_3",
297        "institution_name": "Chase",
298        "item_id": "eVBnVMp7zdTJLkRNr33Rs6zr7KNJqBFL9DrE6"
299      }
300    ],
301    "user": {
302      "client_user_id": "123456789",
303      "email": "accountholder0@example.com",
304      "first_name": "Alberta",
305      "last_name": "Charleson",
306      "middle_name": "Bobbeth",
307      "phone_number": "111-222-3333",
308      "ssn": "123-45-6789"
309    }
310  },
311  "request_id": "eYupqX1mZkEuQRx",
312  "warnings": []
313}

/asset_report/pdf/get

Retrieve a PDF Asset Report

The /asset_report/pdf/get endpoint retrieves the Asset Report in PDF format. Before calling /asset_report/pdf/get, you must first create the Asset Report using /asset_report/create (or filter an Asset Report using /asset_report/filter) and then wait for the PRODUCT_READY webhook to fire, indicating that the Report is ready to be retrieved.
The response to /asset_report/pdf/get is the PDF binary data. The request_id is returned in the Plaid-Request-ID header.
View a sample PDF Asset Report.

asset_report/pdf/get

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
asset_report_token
requiredstring
A token that can be provided to endpoints such as /asset_report/get or /asset_report/pdf/get to fetch or update an Asset Report.
Select group for content switcher
1try {
2  const request: AssetReportPDFGetRequest = {
3    asset_report_token: assetReportToken,
4  };
5  const response = await plaidClient.assetReportPdfGet(request, {
6    responseType: 'arraybuffer',
7  });
8  const pdf = response.buffer.toString('base64');
9} catch (error) {
10  // handle error
11}
Response

This endpoint returns binary PDF data. View a sample Asset Report PDF.

/asset_report/refresh

Refresh 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.
The new Asset Report will contain the same Items as the original Report, as well as the same filters applied by any call to /asset_report/filter. By default, the new Asset Report will also use the same parameters you submitted with your original /asset_report/create request, but the original days_requested value and the values of any parameters in the options object can be overridden with new values. To change these arguments, simply supply new values for them in your request to /asset_report/refresh. Submit an empty string ("") for any previously-populated fields you would like set as empty.

asset_report/refresh

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
asset_report_token
requiredstring
The asset_report_token returned by the original call to /asset_report/create
days_requested
integer
The maximum number of days of history to include in the Asset Report. Must be an integer. If not specified, the value from the original call to /asset_report/create will be used.

Minimum: 0
Maximum: 731
options
object
An optional object to filter /asset_report/refresh results. If provided, cannot be null. If not specified, the options from the original call to /asset_report/create will be used.
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
The user object allows you to provide additional information about the user to be appended to the Asset Report. All fields are optional. The first_name, last_name, and ssn fields are required if you would like the Report to be eligible for Fannie Mae’s Day 1 Certainty™ program.
client_user_id
string
An identifier you determine and submit for the user.
first_name
string
The user's first name. Required for the Fannie Mae Day 1 Certainty™ program.
middle_name
string
The user's middle name
last_name
string
The user's last name. Required for the Fannie Mae Day 1 Certainty™ program.
ssn
string
The user's Social Security Number. Required for the Fannie Mae Day 1 Certainty™ program.
Format: "ddd-dd-dddd"
phone_number
string
The user's phone number, in E.164 format: +{countrycode}{number}. For example: "+14151234567". Phone numbers provided in other formats will be parsed on a best-effort basis.
email
string
The user's email address.
Select group for content switcher
1const request: AssetReportRefreshRequest = {
2  asset_report_token: assetReportToken,
3  daysRequested: 60,
4  options: {
5    client_report_id: '123',
6    webhook: 'https://www.example.com',
7    user: {
8      client_user_id: '7f57eb3d2a9j6480121fx361',
9      first_name: 'Jane',
10      middle_name: 'Leah',
11      last_name: 'Doe',
12      ssn: '123-45-6789',
13      phone_number: '(555) 123-4567',
14      email: 'jane.doe@example.com',
15    },
16  },
17};
18try {
19  const response = await plaidClient.assetReportRefresh(request);
20  const assetReportId = response.data.asset_report_id;
21} catch (error) {
22  // handle error
23}
asset_report/refresh

Response fields and example

asset_report_id
string
A unique ID identifying an Asset Report. Like all Plaid identifiers, this ID is case sensitive.
asset_report_token
string
A token that can be provided to endpoints such as /asset_report/get or /asset_report/pdf/get to fetch or update an Asset Report.
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "asset_report_id": "c33ebe8b-6a63-4d74-a83d-d39791231ac0",
3  "asset_report_token": "assets-sandbox-8218d5f8-6d6d-403d-92f5-13a9afaa4398",
4  "request_id": "NBZaq"
5}

/asset_report/filter

Filter Asset Report

By default, an Asset Report will contain all of the accounts on a given Item. In some cases, you may not want the Asset Report to contain all accounts. For example, you might have the end user choose which accounts are relevant in Link using the Account Select view, which you can enable in the dashboard. Or, you might always exclude certain account types or subtypes, which you can identify by using the /accounts/get endpoint. To narrow an Asset Report to only a subset of accounts, use the /asset_report/filter endpoint.
To exclude certain Accounts from an Asset Report, first use the /asset_report/create endpoint to create the report, then send the 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 token and id. Asset Reports created via /asset_report/filter do not contain new Asset data, and are not billed.
Plaid will fire a PRODUCT_READY webhook once generation of the filtered Asset Report has completed.

asset_report/filter

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
asset_report_token
requiredstring
A token that can be provided to endpoints such as /asset_report/get or /asset_report/pdf/get to fetch or update an Asset Report.
account_ids_to_exclude
required[string]
The accounts to exclude from the Asset Report, identified by account_id.
Select group for content switcher
1const request: AssetReportFilterRequest = {
2  asset_report_token: assetReportToken,
3  account_ids_to_exclude: ['JJGWd5wKDgHbw6yyzL3MsqBAvPyDlqtdyk419'],
4};
5try {
6  const reponse = await plaidClient.assetReportFilter(request);
7  const assetReportId = response.data.asset_report_id;
8} catch (error) {
9  // handle error
10}
asset_report/filter

Response fields and example

asset_report_token
string
A token that can be provided to endpoints such as /asset_report/get or /asset_report/pdf/get to fetch or update an Asset Report.
asset_report_id
string
A unique ID identifying an Asset Report. Like all Plaid identifiers, this ID is case sensitive.
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "asset_report_token": "assets-sandbox-bc410c6a-4653-4c75-985c-e757c3497c5c",
3  "asset_report_id": "fdc09207-0cef-4d88-b5eb-0d970758ebd9",
4  "request_id": "qEg07"
5}

/asset_report/remove

Delete an Asset Report

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.
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 invalidate any audit_copy_tokens associated with the Asset Report.

asset_report/remove

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
asset_report_token
requiredstring
A token that can be provided to endpoints such as /asset_report/get or /asset_report/pdf/get to fetch or update an Asset Report.
Select group for content switcher
1const request: AssetReportRemoveRequest = {
2  asset_report_token: assetReportToken,
3};
4try {
5  const response = await plaidClient.assetReportRemove(request);
6  const removed = response.data.removed;
7} catch (error) {
8  // handle error
9}
asset_report/remove

Response fields and example

removed
boolean
true if the Asset Report was successfully removed.
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "removed": true,
3  "request_id": "I6zHN"
4}

/asset_report/audit_copy/create

Create Asset Report Audit Copy

Plaid can provide an Audit Copy of any Asset Report directly to a participating third party on your behalf. For example, Plaid can 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, use the /asset_report/audit_copy/create endpoint to create an audit_copy_token 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.

asset_report/audit_copy/create

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
asset_report_token
requiredstring
A token that can be provided to endpoints such as /asset_report/get or /asset_report/pdf/get to fetch or update an Asset Report.
auditor_id
requiredstring
The auditor_id of the third party with whom you would like to share the Asset Report.
Select group for content switcher
1// The auditor ID corresponds to the third party with which you want to share
2// the asset report. For example, Fannie Mae's auditor ID is 'fannie_mae'.
3const request: AssetReportAuditCopyCreateRequest = {
4  asset_report_token: createResponse.data.asset_report_token,
5  auditor_id: 'fannie_mae',
6};
7try {
8  const response = await plaidClient.assetReportAuditCopyCreate(request);
9  const auditCopyToken = response.data.audit_copy_token;
10} catch (error) {
11  // handle error
12}
asset_report/audit_copy/create

Response fields and example

audit_copy_token
string
A token that can be shared with a third party auditor to allow them to obtain access to the Asset Report. This token should be stored securely.
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "audit_copy_token": "a-sandbox-3TAU2CWVYBDVRHUCAAAI27ULU4",
3  "request_id": "Iam3b"
4}

/asset_report/audit_copy/remove

Remove Asset Report Audit Copy

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.

asset_report/audit_copy/remove

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
audit_copy_token
requiredstring
The audit_copy_token granting access to the Audit Copy you would like to revoke.
Select group for content switcher
1// auditCopyToken is the token from the createAuditCopy response.
2const request: AssetReportAuditCopyRemoveRequest = {
3  audit_copy_token: auditCopyToken,
4};
5try {
6  const response = await plaidClient.assetReportAuditCopyRemove(request);
7  const removed = response.data.removed;
8} catch (error) {
9  // handle error
10}
asset_report/audit_copy/remove

Response fields and example

removed
boolean
true if the Audit Copy was successfully removed.
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "removed": true,
3  "request_id": "m8MDnv9okwxFNBV"
4}

Webhooks

PRODUCT_READY

Fired when the Asset Report has been generated and /asset_report/get is ready to be called. If you attempt to retrieve an Asset Report before this webhook has fired, you’ll receive a response with the HTTP status code 400 and a Plaid error code of PRODUCT_NOT_READY.

webhook_type
string
ASSETS
webhook_code
string
PRODUCT_READY
asset_report_id
string
The asset_report_id that can be provided to /asset_report/get to retrieve the Asset Report.
1{
2  "webhook_type": "ASSETS",
3  "webhook_code": "PRODUCT_READY",
4  "asset_report_id": "47dfc92b-bba3-4583-809e-ce871b321f05"
5}

ERROR

Fired when Asset Report generation has failed. The resulting error will have an error_type of ASSET_REPORT_ERROR.

webhook_type
string
ASSETS
webhook_code
string
ERROR
error
object
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. Error fields will be null if no error has occurred.
error_type
string
A broad categorization of the error. Safe for programmatic use.

Possible values: INVALID_REQUEST, INVALID_RESULT, INVALID_INPUT, INSTITUTION_ERROR, RATE_LIMIT_EXCEEDED, API_ERROR, ITEM_ERROR, ASSET_REPORT_ERROR, RECAPTCHA_ERROR, OAUTH_ERROR, PAYMENT_ERROR, BANK_TRANSFER_ERROR, INCOME_VERIFICATION_ERROR
error_code
string
The particular error code. 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
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.
request_id
string
A unique ID identifying the request, to be used for troubleshooting purposes. This field will be omitted in errors provided by webhooks.
causes
array
In the Assets product, a request can pertain to more than one Item. If an error is returned for such a request, causes will return an array of errors containing a breakdown of these errors on the individual Item level, if any can be identified.
causes will only be provided for the error_type ASSET_REPORT_ERROR. causes will also not be populated inside an error nested within a warning object.
status
number
The HTTP status code associated with the error. This will only be returned in the response body when the error information is provided via a webhook.
documentation_url
string
The URL of a Plaid documentation page with more information about the error
suggested_action
string
Suggested steps for resolving the error
asset_report_id
string
The ID associated with the Asset Report.
1{
2  "webhook_type": "ASSETS",
3  "webhook_code": "ERROR",
4  "asset_report_id": "47dfc92b-bba3-4583-809e-ce871b321f05",
5  "error": {
6    "display_message": null,
7    "error_code": "PRODUCT_NOT_ENABLED",
8    "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.",
9    "error_type": "ASSET_REPORT_ERROR",
10    "request_id": "m8MDnv9okwxFNBV"
11  }
12}