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/create | Create an Asset Report |
/asset_report/get | Get an Asset Report |
/asset_report/pdf/get | Get a PDF Asset Report |
/asset_report/refresh | Create an updated Asset Report |
/asset_report/filter | Filter unneeded accounts from an Asset Report |
/asset_report/remove | Delete an asset report |
/asset_report/audit_copy/create | Create an Audit Copy of an Asset Report for sharing |
/asset_report/audit_copy/remove | Delete an Audit Copy of an Asset Report |
/credit/relay/create | Create a relay token of an Asset Report for sharing (beta) |
/credit/relay/get | Retrieve the report associated with a relay token (beta) |
/credit/relay/refresh | Refresh a report of a relay token (beta) |
/credit/relay/remove | Delete a relay token (beta) |
Webhooks | |
---|---|
PRODUCT_READY | Asset Report generation has completed |
ERROR | Asset 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.
client_id
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
secret
. The secret
is required and may be provided either in the PLAID-SECRET
header or as part of a request body.access_tokens
assets
product must have been initialized for the Items during link; the Assets product cannot be added after initialization.1
99
days_requested
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.
731
0
options
/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
webhook
add_ons
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
.investments
, fast_assets
user
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
first_name
middle_name
last_name
ssn
Format: "ddd-dd-dddd"
phone_number
email
require_all_items
true
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 error29}
Response fields and example
asset_report_token
/asset_report/get
or /asset_report/pdf/get
to fetch or update an Asset Report.asset_report_id
request_id
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}
Was this helpful?
/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.
client_id
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
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
/asset_report/get
or /asset_report/pdf/get
to fetch or update an Asset Report.include_insights
true
if you would like to retrieve the Asset Report with Insights, false
otherwise. This field defaults to false
if omitted.false
fast_report
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"]
.false
options
/asset_report/get
results. If provided, must be non-null
.days_to_include
731
0
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 later11 } else {12 // handle error13 }14}
Response fields and example
report
asset_report_id
client_report_id
date_generated
date-time
days_requested
user
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
first_name
middle_name
last_name
ssn
Format: "ddd-dd-dddd"
phone_number
email
items
item_id
item_id
of the Item associated with this webhook, warning, or errorinstitution_name
institution_id
date_last_updated
date-time
accounts
account_id
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
/accounts/balance/get
.available
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
.double
current
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
.double
limit
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.double
margin_loan_amount
double
iso_currency_code
unofficial_currency_code
is non-null.unofficial_currency _code
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_code
s.last_updated_datetime
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.date-time
mask
name
official_name
type
investment:
Investment account. In API versions 2018-05-22 and earlier, this type is called brokerage
instead.credit:
Credit carddepository:
Depository accountloan:
Loan accountother:
Non-specified account typeSee the Account type schema for a full listing of account types and corresponding subtypes.
investment
, credit
, depository
, loan
, brokerage
, other
subtype
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
pending_automatic_verification
: The Item is pending automatic verificationpending_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 verifiedverification_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.automatically_verified
, pending_automatic_verification
, pending_manual_verification
, manually_verified
, verification_expired
, verification_failed
, database_matched
persistent_account_id
holder_category
business
, personal
, unrecognized
days_available
transactions
account_id
amount
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.double
iso_currency_code
null
if unofficial_currency_code
is non-null.unofficial_currency _code
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_code
s.original_description
category
/categories/get
.This field will only appear in an Asset Report with Insights.
category_id
/categories/get
.This field will only appear in an Asset Report with Insights.
credit_category
See the
taxonomy csv file
for a full list of credit categories.check_number
date_transacted
location
address
city
region
state
.postal_code
zip
.country
lat
double
lon
double
store_number
name
This field will only appear in an Asset Report with Insights.
merchant_name
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
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
ppd_id
payee
by_order_of
null
if the transaction is not a wire transfer.payer
payment_method
payment_processor
reason
pending
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
account_owner
transaction_id
transaction_id
is case sensitive.transaction_type
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.digital
, place
, special
, unresolved
investments
investment _transaction_id
investment_transaction_id
is case sensitive.account_id
account_id
of the account against which this transaction posted.security_id
security_id
to which this transaction is related.name
quantity
double
vested_quantity
double
vested_value
double
amount
double
price
double
fees
double
type
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 transferFor descriptions of possible transaction types and subtypes, see the Investment transaction types schema.
buy
, sell
, cancel
, cash
, fee
, transfer
subtype
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
null
if unofficial_currency_code
is non-null
.unofficial_currency _code
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_code
s.owners
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 versioningnames
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
emails
addresses
data
city
region
state
.
Example: "NC"
street
"564 Main Street, APT 15"
postal_code
zip
.country
primary
true
, identifies the address as the primary address on an account.ownership_type
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.null
, individual
, joint
, association
, trust
historical_balances
current
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.
double
iso_currency_code
null
if unofficial_currency_code
is non-null
.unofficial_currency _code
null
if iso_currency_code
is non-null
.See the currency code schema for a full listing of supported
unofficial_currency_code
s.warnings
warning_type
ASSET_REPORT_WARNING
warning_code
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.OWNERS_UNAVAILABLE
, INVESTMENTS_UNAVAILABLE
, TRANSACTIONS_UNAVAILABLE
cause
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
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
error_code_reason
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_REVOKED_TOKEN
: The user’s OAuth connection to this institution is invalid because the user revoked their connection.error_message
display_message
null
if the error is not related to user action.This may change over time and is not safe for programmatic use.
request_id
causes
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
documentation_url
suggested_action
item_id
item_id
of the Item associated with this webhook, warning, or errorrequest_id
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": null19 },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": null27 },28 {29 "current": 49050,30 "date": "2023-03-28",31 "iso_currency_code": "USD",32 "unofficial_currency_code": null33 },34 {35 "current": 49050,36 "date": "2023-03-27",37 "iso_currency_code": "USD",38 "unofficial_currency_code": null39 },40 {41 "current": 49050,42 "date": "2023-03-26",43 "iso_currency_code": "USD",44 "unofficial_currency_code": null45 },46 {47 "current": 49050,48 "date": "2023-03-25",49 "iso_currency_code": "USD",50 "unofficial_currency_code": null51 }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": true68 },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": false78 }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": null131 }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": null144 },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": null152 },153 {154 "current": -390,155 "date": "2023-03-28",156 "iso_currency_code": "USD",157 "unofficial_currency_code": null158 },159 {160 "current": -373.67,161 "date": "2023-03-27",162 "iso_currency_code": "USD",163 "unofficial_currency_code": null164 },165 {166 "current": -284.27,167 "date": "2023-03-26",168 "iso_currency_code": "USD",169 "unofficial_currency_code": null170 },171 {172 "current": -284.27,173 "date": "2023-03-25",174 "iso_currency_code": "USD",175 "unofficial_currency_code": null176 }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": true193 },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": false203 }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": null256 },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": null266 },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": null276 },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": null286 }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}
Was this helpful?
/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.
client_id
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
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
/asset_report/get
or /asset_report/pdf/get
to fetch or update an Asset Report.options
/asset_report/get
results. If provided, must be non-null
.days_to_include
731
0
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 error11}
Response
This endpoint returns binary PDF data. View a sample Asset Report PDF.. View a sample Financial Insights Report (UK/EU only) PDF.
Was this helpful?
/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.
client_id
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
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
asset_report_token
returned by the original call to /asset_report/create
days_requested
/asset_report/create
will be used.0
731
options
/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
webhook
user
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
first_name
middle_name
last_name
ssn
Format: "ddd-dd-dddd"
phone_number
email
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 error23}
Response fields and example
asset_report_id
asset_report_token
/asset_report/get
or /asset_report/pdf/get
to fetch or update an Asset Report.request_id
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}
Was this helpful?
/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.
client_id
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
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
/asset_report/get
or /asset_report/pdf/get
to fetch or update an Asset Report.account_ids_to_exclude
account_id
.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 error10}
Response fields and example
asset_report_token
/asset_report/get
or /asset_report/pdf/get
to fetch or update an Asset Report.asset_report_id
request_id
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}
Was this helpful?
/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.
client_id
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
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
/asset_report/get
or /asset_report/pdf/get
to fetch or update an Asset Report.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 error9}
Response fields and example
removed
true
if the Asset Report was successfully removed.request_id
1{2 "removed": true,3 "request_id": "I6zHN"4}
Was this helpful?
/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.
client_id
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
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
/asset_report/get
or /asset_report/pdf/get
to fetch or update an Asset Report.auditor_id
auditor_id
of the third party with whom you would like to share the Asset Report.1// The auditor ID corresponds to the third party with which you want to share2// 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 error12}
Response fields and example
audit_copy_token
request_id
1{2 "audit_copy_token": "a-sandbox-3TAU2CWVYBDVRHUCAAAI27ULU4",3 "request_id": "Iam3b"4}
Was this helpful?
/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.
client_id
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
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
audit_copy_token
granting access to the Audit Copy you would like to revoke.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 error10}
Response fields and example
removed
true
if the Audit Copy was successfully removed.request_id
1{2 "removed": true,3 "request_id": "m8MDnv9okwxFNBV"4}
Was this helpful?
/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.
client_id
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
secret
. The secret
is required and may be provided either in the PLAID-SECRET
header or as part of a request body.report_tokens
secondary_client_id
secondary_client_id
is the client id of the third party with whom you would like to share the relay token.webhook
/credit/relay/get
.1const request: CreditRelayCreateRequest = {2 report_tokens: [createResponse.data.asset_report_token],3 secondary_client_id: clientIdFromPartner4};5try {6 const response = await plaidClient.creditRelayCreate(request);7 const relayToken = response.data.relay_token;8} catch (error) {9 // handle error10}
Response fields and example
relay_token
request_id
1{2 "relay_token": "credit-relay-production-3TAU2CWVYBDVRHUCAAAI27ULU4",3 "request_id": "Iam3b"4}
Was this helpful?
/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.
client_id
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
secret
. The secret
is required and may be provided either in the PLAID-SECRET
header or as part of a request body.relay_token
relay_token
granting access to the report you would like to get.report_type
asset
. Income report types are not yet supported.asset
include_insights
true
if you would like to retrieve the Asset Report with Insights, false
otherwise. This field defaults to false
if omitted.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 error9}
Response fields and example
report
asset_report_id
client_report_id
date_generated
date-time
days_requested
user
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
first_name
middle_name
last_name
ssn
Format: "ddd-dd-dddd"
phone_number
email
items
item_id
item_id
of the Item associated with this webhook, warning, or errorinstitution_name
institution_id
date_last_updated
date-time
accounts
account_id
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
/accounts/balance/get
.available
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
.double
current
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
.double
limit
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.double
margin_loan_amount
double
iso_currency_code
unofficial_currency_code
is non-null.unofficial_currency _code
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_code
s.last_updated_datetime
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.date-time
mask
name
official_name
type
investment:
Investment account. In API versions 2018-05-22 and earlier, this type is called brokerage
instead.credit:
Credit carddepository:
Depository accountloan:
Loan accountother:
Non-specified account typeSee the Account type schema for a full listing of account types and corresponding subtypes.
investment
, credit
, depository
, loan
, brokerage
, other
subtype
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
pending_automatic_verification
: The Item is pending automatic verificationpending_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 verifiedverification_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.automatically_verified
, pending_automatic_verification
, pending_manual_verification
, manually_verified
, verification_expired
, verification_failed
, database_matched
persistent_account_id
holder_category
business
, personal
, unrecognized
days_available
transactions
account_id
amount
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.double
iso_currency_code
null
if unofficial_currency_code
is non-null.unofficial_currency _code
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_code
s.original_description
category
/categories/get
.This field will only appear in an Asset Report with Insights.
category_id
/categories/get
.This field will only appear in an Asset Report with Insights.
credit_category
See the
taxonomy csv file
for a full list of credit categories.check_number
date_transacted
location
address
city
region
state
.postal_code
zip
.country
lat
double
lon
double
store_number
name
This field will only appear in an Asset Report with Insights.
merchant_name
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
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
ppd_id
payee
by_order_of
null
if the transaction is not a wire transfer.payer
payment_method
payment_processor
reason
pending
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
account_owner
transaction_id
transaction_id
is case sensitive.transaction_type
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.digital
, place
, special
, unresolved
investments
investment _transaction_id
investment_transaction_id
is case sensitive.account_id
account_id
of the account against which this transaction posted.security_id
security_id
to which this transaction is related.name
quantity
double
vested_quantity
double
vested_value
double
amount
double
price
double
fees
double
type
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 transferFor descriptions of possible transaction types and subtypes, see the Investment transaction types schema.
buy
, sell
, cancel
, cash
, fee
, transfer
subtype
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
null
if unofficial_currency_code
is non-null
.unofficial_currency _code
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_code
s.owners
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 versioningnames
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
emails
addresses
data
city
region
state
.
Example: "NC"
street
"564 Main Street, APT 15"
postal_code
zip
.country
primary
true
, identifies the address as the primary address on an account.ownership_type
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.null
, individual
, joint
, association
, trust
historical_balances
current
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.
double
iso_currency_code
null
if unofficial_currency_code
is non-null
.unofficial_currency _code
null
if iso_currency_code
is non-null
.See the currency code schema for a full listing of supported
unofficial_currency_code
s.warnings
warning_type
ASSET_REPORT_WARNING
warning_code
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.OWNERS_UNAVAILABLE
, INVESTMENTS_UNAVAILABLE
, TRANSACTIONS_UNAVAILABLE
cause
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
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
error_code_reason
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_REVOKED_TOKEN
: The user’s OAuth connection to this institution is invalid because the user revoked their connection.error_message
display_message
null
if the error is not related to user action.This may change over time and is not safe for programmatic use.
request_id
causes
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
documentation_url
suggested_action
item_id
item_id
of the Item associated with this webhook, warning, or errorrequest_id
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": null19 },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": null27 },28 {29 "current": 49050,30 "date": "2023-03-28",31 "iso_currency_code": "USD",32 "unofficial_currency_code": null33 },34 {35 "current": 49050,36 "date": "2023-03-27",37 "iso_currency_code": "USD",38 "unofficial_currency_code": null39 },40 {41 "current": 49050,42 "date": "2023-03-26",43 "iso_currency_code": "USD",44 "unofficial_currency_code": null45 },46 {47 "current": 49050,48 "date": "2023-03-25",49 "iso_currency_code": "USD",50 "unofficial_currency_code": null51 }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": true68 },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": false78 }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": null131 }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": null144 },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": null152 },153 {154 "current": -390,155 "date": "2023-03-28",156 "iso_currency_code": "USD",157 "unofficial_currency_code": null158 },159 {160 "current": -373.67,161 "date": "2023-03-27",162 "iso_currency_code": "USD",163 "unofficial_currency_code": null164 },165 {166 "current": -284.27,167 "date": "2023-03-26",168 "iso_currency_code": "USD",169 "unofficial_currency_code": null170 },171 {172 "current": -284.27,173 "date": "2023-03-25",174 "iso_currency_code": "USD",175 "unofficial_currency_code": null176 }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": true193 },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": false203 }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": null256 },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": null266 },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": null276 },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": null286 }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}
Was this helpful?
/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.
client_id
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
secret
. The secret
is required and may be provided either in the PLAID-SECRET
header or as part of a request body.relay_token
relay_token
granting access to the report you would like to refresh.report_type
asset
. Income report types are not yet supported.asset
webhook