Assets

API reference for Assets endpoints and webhooks

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

All the endpoints on this page are also compatible with Financial Insights Reports (UK/EU only) and will automatically operate on Financial Insights Reports instead of Asset Reports if the Financial Insights Report add-on has been enabled.

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
/credit/relay/createCreate a relay token of an Asset Report for sharing (beta)
/credit/relay/getRetrieve the report associated with a relay token (beta)
/credit/relay/refreshRefresh a report of a relay token (beta)
/credit/relay/removeDelete a relay token (beta)
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. The exact amount of time to create the report will vary depending on how many days of history are requested and will typically range from a few seconds to about one minute. 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
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
[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.
add_ons
[string]
This field can be used to add additional options for the Asset Report. To fetch investments data (transactions, holdings, etc.) in the Asset Report, investments must be specified in add_ons. For Fast Assets, fast_assets must be specified in add_ons.

Possible values: investments, fast_assets
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.
require_all_items
boolean
If set to false, only 1 item must be healthy at the time of report creation. The default value is true, which would require all items to be healthy at the time of report creation.

Default: true
Select group for content switcher
1const daysRequested = 90;
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 /asset_report/get endpoint with include_insights set to true.
For latency-sensitive applications, you can optionally call /asset_report/create with options.add_ons set to ["fast_assets"]. This will cause Plaid to create two versions of the Asset Report: one with only current and available balance and identity information, and then later on the complete Asset Report. You will receive separate webhooks for each version of the Asset Report.

asset_report/get
Request fields
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
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.
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
fast_report
boolean
true to fetch "fast" version of asset report. Defaults to false if omitted. Can only be used if /asset_report/create was called with options.add_ons set to ["fast_assets"].

Default: false
options
object
An optional object to filter or add data to /asset_report/get results. If provided, must be non-null.
days_to_include
integer
The maximum number of days of history to include in the Asset Report.

Maximum: 731
Minimum: 0
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
nullablestring
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
nullablestring
An identifier you determine and submit for the user.
first_name
nullablestring
The user's first name. Required for the Fannie Mae Day 1 Certainty™ program.
middle_name
nullablestring
The user's middle name
last_name
nullablestring
The user's last name. Required for the Fannie Mae Day 1 Certainty™ program.
ssn
nullablestring
The user's Social Security Number. Required for the Fannie Mae Day 1 Certainty™ program.
Format: "ddd-dd-dddd"
phone_number
nullablestring
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
nullablestring
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
nullablenumber
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
nullablenumber
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
nullablenumber
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
margin_loan_amount
nullablenumber
The total amount of borrowed funds in the account, as determined by the financial institution. For investment-type accounts, the margin balance is the total value of borrowed assets in the account, as presented by the institution. This is commonly referred to as margin or a loan.

Format: double
iso_currency_code
nullablestring
The ISO-4217 currency code of the balance. Always null if unofficial_currency_code is non-null.
unofficial_currency_code
nullablestring
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
nullablestring
Timestamp in ISO 8601 format (YYYY-MM-DDTHH:mm:ssZ) indicating the oldest acceptable balance when making a request to /accounts/balance/get.
This field is only used and expected when the institution is ins_128026 (Capital One) and the Item contains one or more accounts with a non-depository account type, in which case a value must be provided or an INVALID_REQUEST error with the code of INVALID_FIELD will be returned. For Capital One depository accounts as well as all other account types on all other institutions, this field is ignored. See account type schema for a full list of account types.
If the balance that is pulled is older than the given timestamp for Items with this field required, an INVALID_REQUEST error with the code of LAST_UPDATED_DATETIME_OUT_OF_RANGE will be returned with the most recent timestamp for the requested account contained in the response.

Format: date-time
mask
nullablestring
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
nullablestring
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
nullablestring
See the Account type schema for a full listing of account types and corresponding subtypes.

Possible values: 401a, 401k, 403B, 457b, 529, auto, brokerage, business, cash isa, cash management, cd, checking, commercial, construction, consumer, credit card, crypto exchange, ebt, education savings account, fixed annuity, gic, health reimbursement arrangement, home equity, hsa, isa, ira, keogh, lif, life insurance, line of credit, lira, loan, lrif, lrsp, money market, mortgage, mutual fund, non-custodial wallet, non-taxable brokerage account, other, other insurance, other annuity, overdraft, paypal, payroll, pension, prepaid, prif, profit sharing plan, rdsp, resp, retirement, rlif, roth, roth 401k, rrif, rrsp, sarsep, savings, sep ira, simple ira, sipp, stock plan, student, thrift savings plan, tfsa, trust, ugma, utma, variable annuity
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 micro-deposit.
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.
database_matched: The Item has successfully been verified using Plaid's data sources. Note: Database Match is currently a beta feature, please contact your account manager for more information.

Possible values: automatically_verified, pending_automatic_verification, pending_manual_verification, manually_verified, verification_expired, verification_failed, database_matched
persistent_account_id
string
A unique and persistent identifier for accounts that can be used to trace multiple instances of the same account across different Items for depository accounts. This is currently an opt-in field and only supported for Chase Items.
holder_category
nullablestring
Indicates the account's categorization as either a personal or a business account. This field is currently in beta; to request access, contact your account manager.

Possible values: business, personal, unrecognized
days_available
number
The duration of transaction history available within this report for this Item, typically defined as the time since the date of the earliest transaction in that account.
transactions
[object]
Transaction history associated with the account.
account_id
string
The ID of the account in which this transaction occurred.
amount
number
The settled value of the transaction, denominated in the transaction'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
nullablestring
The ISO-4217 currency code of the transaction. Always null if unofficial_currency_code is non-null.
unofficial_currency_code
nullablestring
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 unofficial_currency_codes.
original_description
nullablestring
The string returned by the financial institution to describe the transaction.
category
nullable[string]
A hierarchical array of the categories to which this transaction belongs. For a full list of categories, see /categories/get.
This field will only appear in an Asset Report with Insights.
category_id
nullablestring
The ID of the category to which this transaction belongs. For a full list of categories, see /categories/get.
This field will only appear in an Asset Report with Insights.
credit_category
nullableobject
Information describing the intent of the transaction. Most relevant for credit use cases, but not limited to such use cases.
See the taxonomy csv file for a full list of credit categories.
primary
string
A high level category that communicates the broad category of the transaction.
detailed
string
A granular category conveying the transaction's intent. This field can also be used as a unique identifier for the category.
check_number
nullablestring
The check number of the transaction. This field is only populated for check transactions.
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
date_transacted
nullablestring
The date on which the transaction took place, in IS0 8601 format.
location
object
A representation of where a transaction took place
address
nullablestring
The street address where the transaction occurred.
city
nullablestring
The city where the transaction occurred.
region
nullablestring
The region or state where the transaction occurred. In API versions 2018-05-22 and earlier, this field is called state.
postal_code
nullablestring
The postal code where the transaction occurred. In API versions 2018-05-22 and earlier, this field is called zip.
country
nullablestring
The ISO 3166-1 alpha-2 country code where the transaction occurred.
lat
nullablenumber
The latitude where the transaction occurred.

Format: double
lon
nullablenumber
The longitude where the transaction occurred.

Format: double
store_number
nullablestring
The merchant defined store number where the transaction occurred.
name
string
The merchant name or transaction description.
This field will only appear in an Asset Report with Insights.
merchant_name
nullablestring
The merchant name, as enriched by Plaid from the name field. This is typically a more human-readable version of the merchant counterparty in the transaction. For some bank transactions (such as checks or account transfers) where there is no meaningful merchant name, this value will be null.
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/sync or /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
nullablestring
The transaction reference number supplied by the financial institution.
ppd_id
nullablestring
The ACH PPD ID for the payer.
payee
nullablestring
For transfers, the party that is receiving the transaction.
by_order_of
nullablestring
The party initiating a wire transfer. Will be null if the transaction is not a wire transfer.
payer
nullablestring
For transfers, the party that is paying the transaction.
payment_method
nullablestring
The type of transfer, e.g. 'ACH'
payment_processor
nullablestring
The name of the payment processor
reason
nullablestring
The payer-supplied description of the transfer.
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
nullablestring
The ID of a posted transaction's associated pending transaction, where applicable.
account_owner
nullablestring
The name of the account owner. This field is not typically populated and only relevant when dealing with sub-accounts.
transaction_id
string
The unique ID of the transaction. Like all Plaid identifiers, the transaction_id is case sensitive.
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.

Possible values: digital, place, special, unresolved
investments
object
A transaction within an investment account.
investment_transaction_id
string
The ID of the Investment transaction, unique across all Plaid transactions. Like all Plaid identifiers, the investment_transaction_id is case sensitive.
account_id
string
The account_id of the account against which this transaction posted.
security_id
nullablestring
The security_id to which this transaction is related.
date
string
The ISO 8601 posting date for the transaction.

Format: date
name
string
The institution’s description of the transaction.
quantity
number
The number of units of the security involved in this transaction. Positive for buy transactions; negative for sell transactions.

Format: double
vested_quantity
number
The total quantity of vested assets held, as reported by the financial institution. Vested assets are only associated with equities.

Format: double
vested_value
number
The value of the vested holdings as reported by the institution.

Format: double
amount
number
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.

Format: double
price
number
The price of the security at which this transaction occurred.

Format: double
fees
nullablenumber
The combined value of all fees applied to this transaction

Format: double
type
string
Value is one of the following: buy: Buying an investment sell: Selling an investment cancel: A cancellation of a pending transaction cash: Activity that modifies a cash position fee: A fee on the account transfer: Activity which modifies a position, but not through buy/sell activity e.g. options exercise, portfolio transfer
For descriptions of possible transaction types and subtypes, see the Investment transaction types schema.

Possible values: buy, sell, cancel, cash, fee, transfer
subtype
string
For descriptions of possible transaction types and subtypes, see the Investment transaction types schema.

Possible values: account fee, adjustment, assignment, buy, buy to cover, contribution, deposit, distribution, dividend, dividend reinvestment, exercise, expire, fund fee, interest, interest receivable, interest reinvestment, legal fee, loan payment, long-term capital gain, long-term capital gain reinvestment, management fee, margin expense, merger, miscellaneous fee, non-qualified dividend, non-resident tax, pending credit, pending debit, qualified dividend, rebalance, return of principal, request, sell, sell short, send, short-term capital gain, short-term capital gain reinvestment, spin off, split, stock distribution, tax, tax withheld, trade, transfer, transfer fee, trust fee, unqualified gain, withdrawal
iso_currency_code
nullablestring
The ISO-4217 currency code of the transaction. Always null if unofficial_currency_code is non-null.
unofficial_currency_code
nullablestring
The unofficial currency code associated with the holding. 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.
owners
[object]
Data returned by the financial institution about the account owner or owners.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. 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
nullablestring
The full city name
region
nullablestring
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
nullablestring
The postal code. In API versions 2018-05-22 and earlier, this field is called zip.
country
nullablestring
The ISO 3166-1 alpha-2 country code
primary
boolean
When true, identifies the address as the primary address on an account.
ownership_type
nullablestring
How an asset is owned.
association: Ownership by a corporation, partnership, or unincorporated association, including for-profit and not-for-profit organizations. individual: Ownership by an individual. joint: Joint ownership by multiple parties. trust: Ownership by a revocable or irrevocable trust.

Possible values: null, individual, joint, association, trust
historical_balances
[object]
Calculated data about the historical balances on the account.
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
nullablestring
The ISO-4217 currency code of the balance. Always null if unofficial_currency_code is non-null.
unofficial_currency_code
nullablestring
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 unofficial_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. OWNERS_UNAVAILABLE indicates that account-owner information is not available.INVESTMENTS_UNAVAILABLE indicates that Investments specific information is not available. TRANSACTIONS_UNAVAILABLE indicates that transactions information associated with Credit and Depository accounts are unavailable.

Possible values: OWNERS_UNAVAILABLE, INVESTMENTS_UNAVAILABLE, TRANSACTIONS_UNAVAILABLE
cause
nullableobject
An error object and associated item_id used to identify a specific Item and error when a batch operation operating on multiple Items has encountered an error in one of the Items.
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, MICRODEPOSITS_ERROR, SANDBOX_ERROR, PARTNER_ERROR, TRANSACTIONS_ERROR, TRANSACTION_ERROR, TRANSFER_ERROR
error_code
string
The particular error code. Safe for programmatic use.
error_code_reason
nullablestring
The specific reason for the error code. Currently, reasons are only supported OAuth-based item errors; null will be returned otherwise. Safe for programmatic use.
Possible values: OAUTH_INVALID_TOKEN: The user’s OAuth connection to this institution has been invalidated.
OAUTH_CONSENT_EXPIRED: The user's access consent for this OAuth connection to this institution has expired.
OAUTH_USER_REVOKED: The user’s OAuth connection to this institution is invalid because the user revoked their connection.
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
nullablestring
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 this 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
nullableinteger
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
nullablestring
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": "028e8404-a013-4a45-ac9e-002482f9cafc",
4    "client_report_id": "client_report_id_1221",
5    "date_generated": "2023-03-30T18:27:37Z",
6    "days_requested": 90,
7    "items": [
8      {
9        "accounts": [
10          {
11            "account_id": "1qKRXQjk8xUWDJojNwPXTj8gEmR48piqRNye8",
12            "balances": {
13              "available": 43200,
14              "current": 43200,
15              "limit": null,
16              "margin_loan_amount": null,
17              "iso_currency_code": "USD",
18              "unofficial_currency_code": null
19            },
20            "days_available": 90,
21            "historical_balances": [
22              {
23                "current": 49050,
24                "date": "2023-03-29",
25                "iso_currency_code": "USD",
26                "unofficial_currency_code": null
27              },
28              {
29                "current": 49050,
30                "date": "2023-03-28",
31                "iso_currency_code": "USD",
32                "unofficial_currency_code": null
33              },
34              {
35                "current": 49050,
36                "date": "2023-03-27",
37                "iso_currency_code": "USD",
38                "unofficial_currency_code": null
39              },
40              {
41                "current": 49050,
42                "date": "2023-03-26",
43                "iso_currency_code": "USD",
44                "unofficial_currency_code": null
45              },
46              {
47                "current": 49050,
48                "date": "2023-03-25",
49                "iso_currency_code": "USD",
50                "unofficial_currency_code": null
51              }
52            ],
53            "mask": "4444",
54            "name": "Plaid Money Market",
55            "official_name": "Plaid Platinum Standard 1.85% Interest Money Market",
56            "owners": [
57              {
58                "addresses": [
59                  {
60                    "data": {
61                      "city": "Malakoff",
62                      "country": "US",
63                      "region": "NY",
64                      "street": "2992 Cameron Road",
65                      "postal_code": "14236"
66                    },
67                    "primary": true
68                  },
69                  {
70                    "data": {
71                      "city": "San Matias",
72                      "country": "US",
73                      "region": "CA",
74                      "street": "2493 Leisure Lane",
75                      "postal_code": "93405-2255"
76                    },
77                    "primary": false
78                  }
79                ],
80                "emails": [
81                  {
82                    "data": "accountholder0@example.com",
83                    "primary": true,
84                    "type": "primary"
85                  },
86                  {
87                    "data": "accountholder1@example.com",
88                    "primary": false,
89                    "type": "secondary"
90                  },
91                  {
92                    "data": "extraordinarily.long.email.username.123456@reallylonghostname.com",
93                    "primary": false,
94                    "type": "other"
95                  }
96                ],
97                "names": [
98                  "Alberta Bobbeth Charleson"
99                ],
100                "phone_numbers": [
101                  {
102                    "data": "+1 111-555-3333",
103                    "primary": false,
104                    "type": "home"
105                  },
106                  {
107                    "data": "+1 111-555-4444",
108                    "primary": false,
109                    "type": "work"
110                  },
111                  {
112                    "data": "+1 111-555-5555",
113                    "primary": false,
114                    "type": "mobile"
115                  }
116                ]
117              }
118            ],
119            "ownership_type": null,
120            "subtype": "money market",
121            "transactions": [
122              {
123                "account_id": "1qKRXQjk8xUWDJojNwPXTj8gEmR48piqRNye8",
124                "amount": 5850,
125                "date": "2023-03-30",
126                "iso_currency_code": "USD",
127                "original_description": "ACH Electronic CreditGUSTO PAY 123456",
128                "pending": false,
129                "transaction_id": "gGQgjoeyqBF89PND6K14Sow1wddZBmtLomJ78",
130                "unofficial_currency_code": null
131              }
132            ],
133            "type": "depository"
134          },
135          {
136            "account_id": "eG7pNLjknrFpWvP7Dkbdf3Pq6GVBPKTaQJK5v",
137            "balances": {
138              "available": 100,
139              "current": 110,
140              "limit": null,
141              "margin_loan_amount": null,
142              "iso_currency_code": "USD",
143              "unofficial_currency_code": null
144            },
145            "days_available": 90,
146            "historical_balances": [
147              {
148                "current": 110,
149                "date": "2023-03-29",
150                "iso_currency_code": "USD",
151                "unofficial_currency_code": null
152              },
153              {
154                "current": -390,
155                "date": "2023-03-28",
156                "iso_currency_code": "USD",
157                "unofficial_currency_code": null
158              },
159              {
160                "current": -373.67,
161                "date": "2023-03-27",
162                "iso_currency_code": "USD",
163                "unofficial_currency_code": null
164              },
165              {
166                "current": -284.27,
167                "date": "2023-03-26",
168                "iso_currency_code": "USD",
169                "unofficial_currency_code": null
170              },
171              {
172                "current": -284.27,
173                "date": "2023-03-25",
174                "iso_currency_code": "USD",
175                "unofficial_currency_code": null
176              }
177            ],
178            "mask": "0000",
179            "name": "Plaid Checking",
180            "official_name": "Plaid Gold Standard 0% Interest Checking",
181            "owners": [
182              {
183                "addresses": [
184                  {
185                    "data": {
186                      "city": "Malakoff",
187                      "country": "US",
188                      "region": "NY",
189                      "street": "2992 Cameron Road",
190                      "postal_code": "14236"
191                    },
192                    "primary": true
193                  },
194                  {
195                    "data": {
196                      "city": "San Matias",
197                      "country": "US",
198                      "region": "CA",
199                      "street": "2493 Leisure Lane",
200                      "postal_code": "93405-2255"
201                    },
202                    "primary": false
203                  }
204                ],
205                "emails": [
206                  {
207                    "data": "accountholder0@example.com",
208                    "primary": true,
209                    "type": "primary"
210                  },
211                  {
212                    "data": "accountholder1@example.com",
213                    "primary": false,
214                    "type": "secondary"
215                  },
216                  {
217                    "data": "extraordinarily.long.email.username.123456@reallylonghostname.com",
218                    "primary": false,
219                    "type": "other"
220                  }
221                ],
222                "names": [
223                  "Alberta Bobbeth Charleson"
224                ],
225                "phone_numbers": [
226                  {
227                    "data": "+1 111-555-3333",
228                    "primary": false,
229                    "type": "home"
230                  },
231                  {
232                    "data": "+1 111-555-4444",
233                    "primary": false,
234                    "type": "work"
235                  },
236                  {
237                    "data": "+1 111-555-5555",
238                    "primary": false,
239                    "type": "mobile"
240                  }
241                ]
242              }
243            ],
244            "ownership_type": null,
245            "subtype": "checking",
246            "transactions": [
247              {
248                "account_id": "eG7pNLjknrFpWvP7Dkbdf3Pq6GVBPKTaQJK5v",
249                "amount": 89.4,
250                "date": "2023-03-27",
251                "iso_currency_code": "USD",
252                "original_description": "SparkFun",
253                "pending": false,
254                "transaction_id": "4zBRq1Qem4uAPnoyKjJNTRQpQddM4ztlo1PLD",
255                "unofficial_currency_code": null
256              },
257              {
258                "account_id": "eG7pNLjknrFpWvP7Dkbdf3Pq6GVBPKTaQJK5v",
259                "amount": 12,
260                "date": "2023-03-28",
261                "iso_currency_code": "USD",
262                "original_description": "McDonalds #3322",
263                "pending": false,
264                "transaction_id": "dkjL41PnbKsPral79jpxhMWdW55gkPfBkWpRL",
265                "unofficial_currency_code": null
266              },
267              {
268                "account_id": "eG7pNLjknrFpWvP7Dkbdf3Pq6GVBPKTaQJK5v",
269                "amount": 4.33,
270                "date": "2023-03-28",
271                "iso_currency_code": "USD",
272                "original_description": "Starbucks",
273                "pending": false,
274                "transaction_id": "a84ZxQaWDAtDL3dRgmazT57K7jjN3WFkNWMDy",
275                "unofficial_currency_code": null
276              },
277              {
278                "account_id": "eG7pNLjknrFpWvP7Dkbdf3Pq6GVBPKTaQJK5v",
279                "amount": -500,
280                "date": "2023-03-29",
281                "iso_currency_code": "USD",
282                "original_description": "United Airlines **** REFUND ****",
283                "pending": false,
284                "transaction_id": "xG9jbv3eMoFWepzB7wQLT3LoLggX5Duy1Gbe5",
285                "unofficial_currency_code": null
286              }
287            ],
288            "type": "depository"
289          }
290        ],
291        "date_last_updated": "2023-03-30T18:25:26Z",
292        "institution_id": "ins_109508",
293        "institution_name": "First Platypus Bank",
294        "item_id": "AZMP7JrGXgtPd3AQMeg7hwMKgk5E8qU1V5ME7"
295      }
296    ],
297    "user": {
298      "client_user_id": "uid_40332",
299      "email": "abcharleston@example.com",
300      "first_name": "Anna",
301      "last_name": "Charleston",
302      "middle_name": "B",
303      "phone_number": "1-415-867-5309",
304      "ssn": "111-22-1234"
305    }
306  },
307  "request_id": "GVzMdiDd8DDAQK4",
308  "warnings": []
309}

/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
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.
options
object
An optional object to filter or add data to /asset_report/get results. If provided, must be non-null.
days_to_include
integer
The maximum integer number of days of history to include in the Asset Report.

Maximum: 731
Minimum: 0
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.. View a sample Financial Insights Report (UK/EU only) 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
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: 90,
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
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 response = 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 access to 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
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
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
string
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
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}

/credit/relay/create

Create a relay token to share an Asset Report with a partner client

Plaid can share an Asset Report directly with a participating third party on your behalf. The shared Asset Report is the exact same Asset Report originally created in /asset_report/create.
To grant a third party access to an Asset Report, use the /credit/relay/create endpoint to create a relay_token and then pass that token to your third party. Each third party has its own secondary_client_id; for example, ce5bd328dcd34123456. You'll need to create a separate relay_token for each third party that needs access to the report on your behalf.

credit/relay/create
Request fields
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.
report_tokens
required[string]
List of report token strings, with at most one token of each report type. Currently only Asset Report token is supported.
secondary_client_id
requiredstring
The secondary_client_id is the client id of the third party with whom you would like to share the relay token.
webhook
string
URL to which Plaid will send webhooks when the Secondary Client successfully retrieves an Asset Report by calling /credit/relay/get.
1const request: CreditRelayCreateRequest = {
2  report_tokens: [createResponse.data.asset_report_token],
3  secondary_client_id: clientIdFromPartner
4};
5try {
6  const response = await plaidClient.creditRelayCreate(request);
7  const relayToken = response.data.relay_token;
8} catch (error) {
9  // handle error
10}
credit/relay/create

Response fields and example

relay_token
string
A token that can be shared with a third party to allow them to access 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  "relay_token": "credit-relay-production-3TAU2CWVYBDVRHUCAAAI27ULU4",
3  "request_id": "Iam3b"
4}

/credit/relay/get

Retrieve the reports associated with a relay token that was shared with you

/credit/relay/get allows third parties to receive a report that was shared with them, using a relay_token that was created by the report owner.

credit/relay/get
Request fields
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.
relay_token
requiredstring
The relay_token granting access to the report you would like to get.
report_type
requiredstring
The report type. It can be asset. Income report types are not yet supported.

Possible values: asset
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 
1const request: CreditRelayGetRequest = {
2  relay_token: createResponse.data.relay_token,
3  report_type: 'assets',
4};
5try {
6  const response = await plaidClient.creditRelayGet(request);
7} catch (error) {
8  // handle error
9}
credit/relay/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
nullablestring
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
nullablestring
An identifier you determine and submit for the user.
first_name
nullablestring
The user's first name. Required for the Fannie Mae Day 1 Certainty™ program.
middle_name
nullablestring
The user's middle name
last_name
nullablestring
The user's last name. Required for the Fannie Mae Day 1 Certainty™ program.
ssn
nullablestring
The user's Social Security Number. Required for the Fannie Mae Day 1 Certainty™ program.
Format: "ddd-dd-dddd"
phone_number
nullablestring
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
nullablestring
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
nullablenumber
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
nullablenumber
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
nullablenumber
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
margin_loan_amount
nullablenumber
The total amount of borrowed funds in the account, as determined by the financial institution. For investment-type accounts, the margin balance is the total value of borrowed assets in the account, as presented by the institution. This is commonly referred to as margin or a loan.

Format: double
iso_currency_code
nullablestring
The ISO-4217 currency code of the balance. Always null if unofficial_currency_code is non-null.
unofficial_currency_code
nullablestring
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
nullablestring
Timestamp in ISO 8601 format (YYYY-MM-DDTHH:mm:ssZ) indicating the oldest acceptable balance when making a request to /accounts/balance/get.
This field is only used and expected when the institution is ins_128026 (Capital One) and the Item contains one or more accounts with a non-depository account type, in which case a value must be provided or an INVALID_REQUEST error with the code of INVALID_FIELD will be returned. For Capital One depository accounts as well as all other account types on all other institutions, this field is ignored. See account type schema for a full list of account types.
If the balance that is pulled is older than the given timestamp for Items with this field required, an INVALID_REQUEST error with the code of LAST_UPDATED_DATETIME_OUT_OF_RANGE will be returned with the most recent timestamp for the requested account contained in the response.

Format: date-time
mask
nullablestring
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
nullablestring
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
nullablestring
See the Account type schema for a full listing of account types and corresponding subtypes.

Possible values: 401a, 401k, 403B, 457b, 529, auto, brokerage, business, cash isa, cash management, cd, checking, commercial, construction, consumer, credit card, crypto exchange, ebt, education savings account, fixed annuity, gic, health reimbursement arrangement, home equity, hsa, isa, ira, keogh, lif, life insurance, line of credit, lira, loan, lrif, lrsp, money market, mortgage, mutual fund, non-custodial wallet, non-taxable brokerage account, other, other insurance, other annuity, overdraft, paypal, payroll, pension, prepaid, prif, profit sharing plan, rdsp, resp, retirement, rlif, roth, roth 401k, rrif, rrsp, sarsep, savings, sep ira, simple ira, sipp, stock plan, student, thrift savings plan, tfsa, trust, ugma, utma, variable annuity
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 micro-deposit.
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.
database_matched: The Item has successfully been verified using Plaid's data sources. Note: Database Match is currently a beta feature, please contact your account manager for more information.

Possible values: automatically_verified, pending_automatic_verification, pending_manual_verification, manually_verified, verification_expired, verification_failed, database_matched
persistent_account_id
string
A unique and persistent identifier for accounts that can be used to trace multiple instances of the same account across different Items for depository accounts. This is currently an opt-in field and only supported for Chase Items.
holder_category
nullablestring
Indicates the account's categorization as either a personal or a business account. This field is currently in beta; to request access, contact your account manager.

Possible values: business, personal, unrecognized
days_available
number
The duration of transaction history available within this report for this Item, typically defined as the time since the date of the earliest transaction in that account.
transactions
[object]
Transaction history associated with the account.
account_id
string
The ID of the account in which this transaction occurred.
amount
number
The settled value of the transaction, denominated in the transaction'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
nullablestring
The ISO-4217 currency code of the transaction. Always null if unofficial_currency_code is non-null.
unofficial_currency_code
nullablestring
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 unofficial_currency_codes.
original_description
nullablestring
The string returned by the financial institution to describe the transaction.
category
nullable[string]
A hierarchical array of the categories to which this transaction belongs. For a full list of categories, see /categories/get.
This field will only appear in an Asset Report with Insights.
category_id
nullablestring
The ID of the category to which this transaction belongs. For a full list of categories, see /categories/get.
This field will only appear in an Asset Report with Insights.
credit_category
nullableobject
Information describing the intent of the transaction. Most relevant for credit use cases, but not limited to such use cases.
See the taxonomy csv file for a full list of credit categories.
primary
string
A high level category that communicates the broad category of the transaction.
detailed
string
A granular category conveying the transaction's intent. This field can also be used as a unique identifier for the category.
check_number
nullablestring
The check number of the transaction. This field is only populated for check transactions.
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
date_transacted
nullablestring
The date on which the transaction took place, in IS0 8601 format.
location
object
A representation of where a transaction took place
address
nullablestring
The street address where the transaction occurred.
city
nullablestring
The city where the transaction occurred.
region
nullablestring
The region or state where the transaction occurred. In API versions 2018-05-22 and earlier, this field is called state.
postal_code
nullablestring
The postal code where the transaction occurred. In API versions 2018-05-22 and earlier, this field is called zip.
country
nullablestring
The ISO 3166-1 alpha-2 country code where the transaction occurred.
lat
nullablenumber
The latitude where the transaction occurred.

Format: double
lon
nullablenumber
The longitude where the transaction occurred.

Format: double
store_number
nullablestring
The merchant defined store number where the transaction occurred.
name
string
The merchant name or transaction description.
This field will only appear in an Asset Report with Insights.
merchant_name
nullablestring
The merchant name, as enriched by Plaid from the name field. This is typically a more human-readable version of the merchant counterparty in the transaction. For some bank transactions (such as checks or account transfers) where there is no meaningful merchant name, this value will be null.
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/sync or /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
nullablestring
The transaction reference number supplied by the financial institution.
ppd_id
nullablestring
The ACH PPD ID for the payer.
payee
nullablestring
For transfers, the party that is receiving the transaction.
by_order_of
nullablestring
The party initiating a wire transfer. Will be null if the transaction is not a wire transfer.
payer
nullablestring
For transfers, the party that is paying the transaction.
payment_method
nullablestring
The type of transfer, e.g. 'ACH'
payment_processor
nullablestring
The name of the payment processor
reason
nullablestring
The payer-supplied description of the transfer.
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
nullablestring
The ID of a posted transaction's associated pending transaction, where applicable.
account_owner
nullablestring
The name of the account owner. This field is not typically populated and only relevant when dealing with sub-accounts.
transaction_id
string
The unique ID of the transaction. Like all Plaid identifiers, the transaction_id is case sensitive.
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.

Possible values: digital, place, special, unresolved
investments
object
A transaction within an investment account.
investment_transaction_id
string
The ID of the Investment transaction, unique across all Plaid transactions. Like all Plaid identifiers, the investment_transaction_id is case sensitive.
account_id
string
The account_id of the account against which this transaction posted.
security_id
nullablestring
The security_id to which this transaction is related.
date
string
The ISO 8601 posting date for the transaction.

Format: date
name
string
The institution’s description of the transaction.
quantity
number
The number of units of the security involved in this transaction. Positive for buy transactions; negative for sell transactions.

Format: double
vested_quantity
number
The total quantity of vested assets held, as reported by the financial institution. Vested assets are only associated with equities.

Format: double
vested_value
number
The value of the vested holdings as reported by the institution.

Format: double
amount
number
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.

Format: double
price
number
The price of the security at which this transaction occurred.

Format: double
fees
nullablenumber
The combined value of all fees applied to this transaction

Format: double
type
string
Value is one of the following: buy: Buying an investment sell: Selling an investment cancel: A cancellation of a pending transaction cash: Activity that modifies a cash position fee: A fee on the account transfer: Activity which modifies a position, but not through buy/sell activity e.g. options exercise, portfolio transfer
For descriptions of possible transaction types and subtypes, see the Investment transaction types schema.

Possible values: buy, sell, cancel, cash, fee, transfer
subtype
string
For descriptions of possible transaction types and subtypes, see the Investment transaction types schema.

Possible values: account fee, adjustment, assignment, buy, buy to cover, contribution, deposit, distribution, dividend, dividend reinvestment, exercise, expire, fund fee, interest, interest receivable, interest reinvestment, legal fee, loan payment, long-term capital gain, long-term capital gain reinvestment, management fee, margin expense, merger, miscellaneous fee, non-qualified dividend, non-resident tax, pending credit, pending debit, qualified dividend, rebalance, return of principal, request, sell, sell short, send, short-term capital gain, short-term capital gain reinvestment, spin off, split, stock distribution, tax, tax withheld, trade, transfer, transfer fee, trust fee, unqualified gain, withdrawal
iso_currency_code
nullablestring
The ISO-4217 currency code of the transaction. Always null if unofficial_currency_code is non-null.
unofficial_currency_code
nullablestring
The unofficial currency code associated with the holding. 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.
owners
[object]
Data returned by the financial institution about the account owner or owners.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. 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
nullablestring
The full city name
region
nullablestring
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
nullablestring
The postal code. In API versions 2018-05-22 and earlier, this field is called zip.
country
nullablestring
The ISO 3166-1 alpha-2 country code
primary
boolean
When true, identifies the address as the primary address on an account.
ownership_type
nullablestring
How an asset is owned.
association: Ownership by a corporation, partnership, or unincorporated association, including for-profit and not-for-profit organizations. individual: Ownership by an individual. joint: Joint ownership by multiple parties. trust: Ownership by a revocable or irrevocable trust.

Possible values: null, individual, joint, association, trust
historical_balances
[object]
Calculated data about the historical balances on the account.
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
nullablestring
The ISO-4217 currency code of the balance. Always null if unofficial_currency_code is non-null.
unofficial_currency_code
nullablestring
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 unofficial_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. OWNERS_UNAVAILABLE indicates that account-owner information is not available.INVESTMENTS_UNAVAILABLE indicates that Investments specific information is not available. TRANSACTIONS_UNAVAILABLE indicates that transactions information associated with Credit and Depository accounts are unavailable.

Possible values: OWNERS_UNAVAILABLE, INVESTMENTS_UNAVAILABLE, TRANSACTIONS_UNAVAILABLE
cause
nullableobject
An error object and associated item_id used to identify a specific Item and error when a batch operation operating on multiple Items has encountered an error in one of the Items.
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, MICRODEPOSITS_ERROR, SANDBOX_ERROR, PARTNER_ERROR, TRANSACTIONS_ERROR, TRANSACTION_ERROR, TRANSFER_ERROR
error_code
string
The particular error code. Safe for programmatic use.
error_code_reason
nullablestring
The specific reason for the error code. Currently, reasons are only supported OAuth-based item errors; null will be returned otherwise. Safe for programmatic use.
Possible values: OAUTH_INVALID_TOKEN: The user’s OAuth connection to this institution has been invalidated.
OAUTH_CONSENT_EXPIRED: The user's access consent for this OAuth connection to this institution has expired.
OAUTH_USER_REVOKED: The user’s OAuth connection to this institution is invalid because the user revoked their connection.
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
nullablestring
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 this 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
nullableinteger
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
nullablestring
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": "028e8404-a013-4a45-ac9e-002482f9cafc",
4    "client_report_id": "client_report_id_1221",
5    "date_generated": "2023-03-30T18:27:37Z",
6    "days_requested": 90,
7    "items": [
8      {
9        "accounts": [
10          {
11            "account_id": "1qKRXQjk8xUWDJojNwPXTj8gEmR48piqRNye8",
12            "balances": {
13              "available": 43200,
14              "current": 43200,
15              "limit": null,
16              "margin_loan_amount": null,
17              "iso_currency_code": "USD",
18              "unofficial_currency_code": null
19            },
20            "days_available": 90,
21            "historical_balances": [
22              {
23                "current": 49050,
24                "date": "2023-03-29",
25                "iso_currency_code": "USD",
26                "unofficial_currency_code": null
27              },
28              {
29                "current": 49050,
30                "date": "2023-03-28",
31                "iso_currency_code": "USD",
32                "unofficial_currency_code": null
33              },
34              {
35                "current": 49050,
36                "date": "2023-03-27",
37                "iso_currency_code": "USD",
38                "unofficial_currency_code": null
39              },
40              {
41                "current": 49050,
42                "date": "2023-03-26",
43                "iso_currency_code": "USD",
44                "unofficial_currency_code": null
45              },
46              {
47                "current": 49050,
48                "date": "2023-03-25",
49                "iso_currency_code": "USD",
50                "unofficial_currency_code": null
51              }
52            ],
53            "mask": "4444",
54            "name": "Plaid Money Market",
55            "official_name": "Plaid Platinum Standard 1.85% Interest Money Market",
56            "owners": [
57              {
58                "addresses": [
59                  {
60                    "data": {
61                      "city": "Malakoff",
62                      "country": "US",
63                      "region": "NY",
64                      "street": "2992 Cameron Road",
65                      "postal_code": "14236"
66                    },
67                    "primary": true
68                  },
69                  {
70                    "data": {
71                      "city": "San Matias",
72                      "country": "US",
73                      "region": "CA",
74                      "street": "2493 Leisure Lane",
75                      "postal_code": "93405-2255"
76                    },
77                    "primary": false
78                  }
79                ],
80                "emails": [
81                  {
82                    "data": "accountholder0@example.com",
83                    "primary": true,
84                    "type": "primary"
85                  },
86                  {
87                    "data": "accountholder1@example.com",
88                    "primary": false,
89                    "type": "secondary"
90                  },
91                  {
92                    "data": "extraordinarily.long.email.username.123456@reallylonghostname.com",
93                    "primary": false,
94                    "type": "other"
95                  }
96                ],
97                "names": [
98                  "Alberta Bobbeth Charleson"
99                ],
100                "phone_numbers": [
101                  {
102                    "data": "+1 111-555-3333",
103                    "primary": false,
104                    "type": "home"
105                  },
106                  {
107                    "data": "+1 111-555-4444",
108                    "primary": false,
109                    "type": "work"
110                  },
111                  {
112                    "data": "+1 111-555-5555",
113                    "primary": false,
114                    "type": "mobile"
115                  }
116                ]
117              }
118            ],
119            "ownership_type": null,
120            "subtype": "money market",
121            "transactions": [
122              {
123                "account_id": "1qKRXQjk8xUWDJojNwPXTj8gEmR48piqRNye8",
124                "amount": 5850,
125                "date": "2023-03-30",
126                "iso_currency_code": "USD",
127                "original_description": "ACH Electronic CreditGUSTO PAY 123456",
128                "pending": false,
129                "transaction_id": "gGQgjoeyqBF89PND6K14Sow1wddZBmtLomJ78",
130                "unofficial_currency_code": null
131              }
132            ],
133            "type": "depository"
134          },
135          {
136            "account_id": "eG7pNLjknrFpWvP7Dkbdf3Pq6GVBPKTaQJK5v",
137            "balances": {
138              "available": 100,
139              "current": 110,
140              "limit": null,
141              "margin_loan_amount": null,
142              "iso_currency_code": "USD",
143              "unofficial_currency_code": null
144            },
145            "days_available": 90,
146            "historical_balances": [
147              {
148                "current": 110,
149                "date": "2023-03-29",
150                "iso_currency_code": "USD",
151                "unofficial_currency_code": null
152              },
153              {
154                "current": -390,
155                "date": "2023-03-28",
156                "iso_currency_code": "USD",
157                "unofficial_currency_code": null
158              },
159              {
160                "current": -373.67,
161                "date": "2023-03-27",
162                "iso_currency_code": "USD",
163                "unofficial_currency_code": null
164              },
165              {
166                "current": -284.27,
167                "date": "2023-03-26",
168                "iso_currency_code": "USD",
169                "unofficial_currency_code": null
170              },
171              {
172                "current": -284.27,
173                "date": "2023-03-25",
174                "iso_currency_code": "USD",
175                "unofficial_currency_code": null
176              }
177            ],
178            "mask": "0000",
179            "name": "Plaid Checking",
180            "official_name": "Plaid Gold Standard 0% Interest Checking",
181            "owners": [
182              {
183                "addresses": [
184                  {
185                    "data": {
186                      "city": "Malakoff",
187                      "country": "US",
188                      "region": "NY",
189                      "street": "2992 Cameron Road",
190                      "postal_code": "14236"
191                    },
192                    "primary": true
193                  },
194                  {
195                    "data": {
196                      "city": "San Matias",
197                      "country": "US",
198                      "region": "CA",
199                      "street": "2493 Leisure Lane",
200                      "postal_code": "93405-2255"
201                    },
202                    "primary": false
203                  }
204                ],
205                "emails": [
206                  {
207                    "data": "accountholder0@example.com",
208                    "primary": true,
209                    "type": "primary"
210                  },
211                  {
212                    "data": "accountholder1@example.com",
213                    "primary": false,
214                    "type": "secondary"
215                  },
216                  {
217                    "data": "extraordinarily.long.email.username.123456@reallylonghostname.com",
218                    "primary": false,
219                    "type": "other"
220                  }
221                ],
222                "names": [
223                  "Alberta Bobbeth Charleson"
224                ],
225                "phone_numbers": [
226                  {
227                    "data": "+1 111-555-3333",
228                    "primary": false,
229                    "type": "home"
230                  },
231                  {
232                    "data": "+1 111-555-4444",
233                    "primary": false,
234                    "type": "work"
235                  },
236                  {
237                    "data": "+1 111-555-5555",
238                    "primary": false,
239                    "type": "mobile"
240                  }
241                ]
242              }
243            ],
244            "ownership_type": null,
245            "subtype": "checking",
246            "transactions": [
247              {
248                "account_id": "eG7pNLjknrFpWvP7Dkbdf3Pq6GVBPKTaQJK5v",
249                "amount": 89.4,
250                "date": "2023-03-27",
251                "iso_currency_code": "USD",
252                "original_description": "SparkFun",
253                "pending": false,
254                "transaction_id": "4zBRq1Qem4uAPnoyKjJNTRQpQddM4ztlo1PLD",
255                "unofficial_currency_code": null
256              },
257              {
258                "account_id": "eG7pNLjknrFpWvP7Dkbdf3Pq6GVBPKTaQJK5v",
259                "amount": 12,
260                "date": "2023-03-28",
261                "iso_currency_code": "USD",
262                "original_description": "McDonalds #3322",
263                "pending": false,
264                "transaction_id": "dkjL41PnbKsPral79jpxhMWdW55gkPfBkWpRL",
265                "unofficial_currency_code": null
266              },
267              {
268                "account_id": "eG7pNLjknrFpWvP7Dkbdf3Pq6GVBPKTaQJK5v",
269                "amount": 4.33,
270                "date": "2023-03-28",
271                "iso_currency_code": "USD",
272                "original_description": "Starbucks",
273                "pending": false,
274                "transaction_id": "a84ZxQaWDAtDL3dRgmazT57K7jjN3WFkNWMDy",
275                "unofficial_currency_code": null
276              },
277              {
278                "account_id": "eG7pNLjknrFpWvP7Dkbdf3Pq6GVBPKTaQJK5v",
279                "amount": -500,
280                "date": "2023-03-29",
281                "iso_currency_code": "USD",
282                "original_description": "United Airlines **** REFUND ****",
283                "pending": false,
284                "transaction_id": "xG9jbv3eMoFWepzB7wQLT3LoLggX5Duy1Gbe5",
285                "unofficial_currency_code": null
286              }
287            ],
288            "type": "depository"
289          }
290        ],
291        "date_last_updated": "2023-03-30T18:25:26Z",
292        "institution_id": "ins_109508",
293        "institution_name": "First Platypus Bank",
294        "item_id": "AZMP7JrGXgtPd3AQMeg7hwMKgk5E8qU1V5ME7"
295      }
296    ],
297    "user": {
298      "client_user_id": "uid_40332",
299      "email": "abcharleston@example.com",
300      "first_name": "Anna",
301      "last_name": "Charleston",
302      "middle_name": "B",
303      "phone_number": "1-415-867-5309",
304      "ssn": "111-22-1234"
305    }
306  },
307  "request_id": "GVzMdiDd8DDAQK4",
308  "warnings": []
309}

/credit/relay/refresh

Refresh a report of a relay token

The /credit/relay/refresh endpoint allows third parties to refresh a report that was relayed to them, using a relay_token that was created by the report owner. A new report will be created with the original report parameters, but with the most recent data available based on the days_requested value of the original report.

credit/relay/refresh
Request fields
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.
relay_token
requiredstring
The relay_token granting access to the report you would like to refresh.
report_type
requiredstring
The report type. It can be asset. Income report types are not yet supported.

Possible values: asset
webhook
string
The URL registered to receive webhooks when the report of a relay token has been refreshed.
1const request: CreditRelayRefreshRequest = {
2  relay_token: createResponse.data.relay_token,
3  report_type: 'assets',
4};
5try {
6  const response = await plaidClient.CreditRelayRefresh(request);
7} catch (error) {
8  // handle error
9}
credit/relay/refresh

Response fields and example

relay_token
string
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  "relay_token": "credit-relay-sandbox-8218d5f8-6d6d-403d-92f5-13a9afaa4398",
3  "request_id": "NBZaq",
4  "asset_report_id": "bf3a0490-344c-4620-a219-2693162e4b1d"
5}

/credit/relay/remove

Remove relay token

The /credit/relay/remove endpoint allows you to invalidate a relay_token. The third party holding the token will no longer be able to access or refresh the reports which the relay_token gives access to. The original report, associated Items, and other relay tokens that provide access to the same report are not affected and will remain accessible after removing the given relay_token.

credit/relay/remove
Request fields
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.
relay_token
requiredstring
The relay_token you would like to revoke.
1const request: CreditRelayRemoveRequest = {
2  relay_token: createResponse.data.relay_token,
3};
4try {
5  const response = await plaidClient.creditRelayRemove(request);
6} catch (error) {
7  // handle error
8}
credit/relay/remove

Response fields and example

removed
boolean
true if the relay token 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 corresponding to the Asset Report the webhook has fired for.
user_id
string
The user_id corresponding to the User ID the webhook has fired for.
report_type
string
Indicates either a Fast Asset Report, which will contain only current identity and balance information, or a Full Asset Report, which will also contain historical balance information and transaction data.

Possible values: FULL, FAST
environment
string
The Plaid environment the webhook was sent from

Possible values: sandbox, production
1{
2  "webhook_type": "ASSETS",
3  "webhook_code": "PRODUCT_READY",
4  "asset_report_id": "47dfc92b-bba3-4583-809e-ce871b321f05",
5  "report_type": "FULL"
6}

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
Errors are identified by error_code and categorized by error_type. Use these in preference to HTTP status codes to identify and handle specific errors. HTTP status codes are set and provide the broadest categorization of errors: 4xx codes are for developer- or user-related errors, and 5xx codes are for Plaid-related errors, and the status will be 2xx in non-error cases. An Item with a non-null error object will only be part of an API response when calling /item/get to view Item status. Otherwise, error fields will be null if no error has occurred; if an error has occurred, an error code will be returned instead.
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, MICRODEPOSITS_ERROR, SANDBOX_ERROR, PARTNER_ERROR, TRANSACTIONS_ERROR, TRANSACTION_ERROR, TRANSFER_ERROR
error_code
string
The particular error code. Safe for programmatic use.
error_code_reason
string
The specific reason for the error code. Currently, reasons are only supported OAuth-based item errors; null will be returned otherwise. Safe for programmatic use.
Possible values: OAUTH_INVALID_TOKEN: The user’s OAuth connection to this institution has been invalidated.
OAUTH_CONSENT_EXPIRED: The user's access consent for this OAuth connection to this institution has expired.
OAUTH_USER_REVOKED: The user’s OAuth connection to this institution is invalid because the user revoked their connection.
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 this 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
integer
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.
user_id
string
The user_id corresponding to the User ID the webhook has fired for.
environment
string
The Plaid environment the webhook was sent from

Possible values: sandbox, production
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}