Aggregation API Reference
Plaid Exchange Data Aggregation Reference
This API enables Plaid to make recurrent, user-absent requests in order to maintain a current and consistent view of a user’s permissioned accounts.
Get Account and Identity Endpoint
GET /users/{user_id}
Provide user and account information for a given user ID. This endpoint contains the information necessary for the partner to support the Identity and Auth products.
Responses
200 OK
The request is authorized.
UserAccountInfoResponse
Basic account and identity enumeration.
Properties
List of Identity instances necessary to fully resolve all records in accounts.
1 Permanent identity identifier.
The display name of this entity (insufficient for KYC purposes)
The email address where this entity can be contacted.
Option 1.objectcontainingorganization,person,mailing_address.
Describes an organization, e.g., a business or non-profit.
Name of the organization represented.
Type of business structure.
sole, partnership, llc, corpThe ISO-18245 merchant category code for this business.
^\d{4}$ The identities of the organization owner(s).
The tax authority ID.
Name of the tax authority.
The tax payer ID, e.g. EIN, TIN, SSN.
The national jurisdiction of the tax authority in ISO 3166-1 format.
If the tax authority is subnational, the ISO 3166-2 subdivision of the authority's jurisdiction. This is usually a state, province, or department.
Describes an individual, named person.
Legal given name of the personal entity.
Middle name, use blank if none.
Last name or family name.
The date of birth in ISO-8601 format.
date The tax authority ID.
Name of the tax authority.
The tax payer ID, e.g. EIN, TIN, SSN.
The national jurisdiction of the tax authority in ISO 3166-1 format.
If the tax authority is subnational, the ISO 3166-2 subdivision of the authority's jurisdiction. This is usually a state, province, or department.
Description of a street address.
The lines of the street address.
1 The city of the mailing address.
The first-level administrative subdivision, e.g., a state, province or district. Use ISO 3166-2 subdivisions (note: _not_ ISO-3166-alpha-2).
The ISO 3166-alpha-2 country code.
The postal code.
The phone number, formatted using ITU standard E. 123.
Indicate the Identity corresponding to the currently logged-in user.
List of Securities necessary to fully resolve all records in accounts.
0 The permanent identifier for this security, across all accounts and holdings. Do not use a full or masked account number for this value as this increases the risk of revealing Personally Identifiable Information (PII).
The ISO 6166-compliant ISIN for this security, if available.
A descriptive name for the security, suitable for display.
The security's trading symbol, if applicable. Otherwise, a short, commonly used identifier.
Indicates the security is highly-liquid, e.g. a money market account, and should be regarded as cash.
The instantaneous trading price of the security.
string, stringThe time at which current_price was current, in ISO 8601 format.
date-time The price of the security at the most recent close of trading. For securities that are traded continuously throughout the day, use the price at 11:59PM of the previous day, in the institution's time zone.
string, stringThe security type. For detailed descriptions of available types, see Plaid API security types.
cash, derivative, equity, etf, fixed income, loan, mutual fund, otherThe ISO 4217 currency in which this account’s transactions and balances are denominated.
string, stringIf the account is denominated in a non-ISO currency, provide the currency's symbol.
Option 1.objectcontainingexpiry,contract_type,option_style,exercise_price,underlying_security_id.
The contract expiration date.
date The type of option.
put, callThe style of option (US or European)
euro, usThe price at which the contract owner may transact.
^-?(\d*)(?:\.\d{1,2})?$ Reference to the security underlying this contract.
List of all accounts for which this user is an owner or interested non-owner.
Permanent account identifier. Do not use a full or masked account number for this value as this increases the risk of revealing Personally Identifiable Information (PII).
Date of most recent change to, or activity on this account, e.g. new transactions, or changes to account metadata. Used to provide hints for optimal scheduling of updates.
date-time Indicates the ownership type of the account, _not_ the relationship the current user has over the account.
individual, joint, association, trustReferences to the identities for the owner(s) of this account.
References to the identities for the non-owner(s) related to this account, e.g. trustees, beneficiaries.
Status of this account.
active, inactive, frozen, locked, flagged, restricted, closed, active, inactive, frozen, locked, flagged, restricted, closedMajor classification of this account.
depository, loan, investment, depository, loan, investmentMinor classification of this account.
cash management, cd, checking, savings, money market, health, prepaid, gic, auto, commercial, construction, consumer, credit card, home equity, mortgage, overdraft, line of credit, student, 401a, 401k, 403B, 457b, 529, brokerage, esa, ira, isa, lira, other, rif, rsp, pension, profit-sharing, roth ira, roth 401k, sep ira, simple ira, sipp, stock plan, tsp, tfsa, custodial, variable annuity, cash management, cd, checking, savings, money market, health, prepaid, gic, auto, commercial, construction, consumer, credit card, home equity, mortgage, overdraft, line of credit, student, 401a, 401k, 403B, 457b, 529, brokerage, esa, ira, isa, lira, other, rif, rsp, pension, profit-sharing, roth ira, roth 401k, sep ira, simple ira, sipp, stock plan, tsp, tfsa, custodial, variable annuityThe account's user-given name, if the institution supports naming of accounts.
The account's marketing or brand name.
A short alpha-numeric string to assist users in identifying the account, e.g. last four digits of the account number.
The date on which the account was opened.
date The total balance in the account, typically including pending transactions. See individual account types for specific definitions of this value.
string, stringThe immediately available balance in the account, typically the amount available to withdraw at the moment.
string, stringIndicates whether some activity on the account - deposits, gains, etc - benefits from tax deferral or exemption, e.g. HSA, IRA, 401(k) accounts.
The ISO-4217 currency in which this account’s transactions and balances are denominated.
string, stringIf the account is denominated in a non-ISO currency, provide the currency's symbol.
Option 1.objectcontaininginterest_rate,transfer_codes,maturity_date,statements.objectcontainingtransfer_codes,margin_balance,margin_limit,margin_equity,maintenance_margin,buying_power,current_as_of,holdings.objectcontainingaccount_number,reference_number,servicer_identity_id,interest_rate,interest_rate_type,interest_rate_schedule,term_months,term_days,repayment_status,principal_balance,payoff_quote,payoff_expiry,origination_date,origination_principal,maturity_date,statements.objectcontainingescrow_balance.objectcontainingdisbursement_schedule,guarantor_identity,pslf_eligibility,sequence_number.objectcontainingreward_balance,credit_limit,spender_identity_ids,interest_rates,statements,reward_currency,reward_non_iso,_currency art_asset_url.
ACH (US) account identifiers.
The account number.
The ABA routing transit number.
The institution's routing number for wire transfer.
Indicates account may be debited using transfer code.
Indicates account may be credited using transfer code.
EFT (Canada) account identifiers.
The account number.
The institution's number assigned by Payments Canada.
The branch number corresponding to the account.
Indicates account may be debited using transfer code.
Indicates account may be credited using transfer code.
IBAN account identifiers.
The full IBAN.
Bank identifier.
The country code.
Location code for the bank's office.
Optionally indicate a specific branch.
Indicates account may be debited using transfer code.
Indicates account may be credited using transfer code.
Payment card account identifiers.
The payment card number.
Month of card expiration, as a 2-digit value.
Year of card expiration.
CVV, CSC, or other card-not-present verification value.
Indicates account may be debited using transfer code.
Indicates account may be credited using transfer code.
ACATS account identifiers.
The account number.
Identity of the receiving brokerage (including organization).
Describes an organization, e.g., a business or non-profit.
Name of the organization represented.
Type of business structure.
sole, partnership, llc, corpThe ISO-18245 merchant category code for this business.
^\d{4}$ The identities of the organization owner(s).
The tax authority ID.
Name of the tax authority.
The tax payer ID, e.g. EIN, TIN, SSN.
The national jurisdiction of the tax authority in ISO 3166-1 format.
If the tax authority is subnational, the ISO 3166-2 subdivision of the authority's jurisdiction. This is usually a state, province, or department.
Describes an individual, named person.
Legal given name of the personal entity.
Middle name, use blank if none.
Last name or family name.
The date of birth in ISO-8601 format.
date The tax authority ID.
Name of the tax authority.
The tax payer ID, e.g. EIN, TIN, SSN.
The national jurisdiction of the tax authority in ISO 3166-1 format.
If the tax authority is subnational, the ISO 3166-2 subdivision of the authority's jurisdiction. This is usually a state, province, or department.
The email address where this entity can be contacted.
Description of a street address.
The lines of the street address.
1 The city of the mailing address.
The first-level administrative subdivision, e.g., a state, province or district. Use ISO 3166-2 subdivisions (note: _not_ ISO-3166-alpha-2).
The ISO 3166-alpha-2 country code.
The postal code.
The phone number, formatted using ITU standard E. 123.
Permanent identity identifier.
The display name of this entity (insufficient for KYC purposes)
The DTCC institution identifiers for the institution holding the account.
1 Indicates account may be debited using transfer code.
Indicates account may be credited using transfer code.
[object], [object], [object]The amount that is on loan. Provide as a negative amount.
^-?(\d*)(?:\.\d{1,2})?$ The total limit of the margin extended to the account.
^-?(\d*)(?:\.\d{1,2})?$ The amount of marginable assets owned in the account.
^-?(\d*)(?:\.\d{1,2})?$ The minimum equity needed to hold the positions in the account.
^-?(\d*)(?:\.\d{1,2})?$ Total amount of funds available for making transactions, includes margin.
^-?(\d*)(?:\.\d{1,2})?$ The time at which current_balance was current.
date-time Descriptions of held assets in the account.
The identifier of the security referenced by this holding.
The total cost of acquiring this holding, inclusive of fees.
^-?(\d*)(?:\.\d{1,2})?$ The amount of the security (typically, number of shares) comprising this holding.
^-?(\d*)(?:\.\d{1,2})?$ The tax lots constituting this holding.
The unique and permanent identifier for this lot.
The date at which the lot was acquired.
date The total price at which this lot was acquired.
^-?(\d*)(?:\.\d{1,2})?$ The quantity held in this lot.
^-?(\d*)(?:\.\d{1,2})?$ The ISO-4217 currency in which this account’s transactions and balances are denominated.
If the account is denominated in a non-ISO currency, provide the currency's symbol.
The account number for this loan.
The loan's reference number.
Reference to the identity of the loan servicer.
The interest rate adjustment scheme for this loan.
fixed, adjustable, variable, otherA history of effective rates on this loan. For adjustable rate loans, include dates of future adjustments. Do not use to describe fixed-rate loans.
The date this rate became, or becomes, effective.
date The date this rate became, or becomes, ineffective. Use null if the end date is not known or not fixed.
date The effective rate during the period described.
^\d*(\.\d{1,4})?$ The full length of the loan's term, in months.
0 The full length of the loan's term, in days.
0 The loan's repayment status.
fully repaid, current, grace, deferment, forbearance, past due, delinquent, default, charged off, cancelledThe loan's remaining principal.
^-?(\d*)(?:\.\d{1,2})?$ The instantaneous payoff quote.
^-?(\d*)(?:\.\d{1,2})?$ The date until which payoff_quote is considered current.
date The loan's date of origination.
date The original principal balance.
^-?(\d*)(?:\.\d{1,2})?$ The total amount held in escrow for this loan, if applicable.
Fixed-point decimal number, carried up to six decimal places.
^-?(\d*)(?:\.\d{1,2})?$ The schedule for disbursement of funds.
The date of disbursement.
date The amount disbursed.
^-?(\d*)(?:\.\d{1,2})?$ The company or agency guaranteeing the loan.
Describes an organization, e.g., a business or non-profit.
Name of the organization represented.
Type of business structure.
sole, partnership, llc, corpThe ISO-18245 merchant category code for this business.
^\d{4}$ The identities of the organization owner(s).
The tax authority ID.
Name of the tax authority.
The tax payer ID, e.g. EIN, TIN, SSN.
The national jurisdiction of the tax authority in ISO 3166-1 format.
If the tax authority is subnational, the ISO 3166-2 subdivision of the authority's jurisdiction. This is usually a state, province, or department.
Describes an individual, named person.
Legal given name of the personal entity.
Middle name, use blank if none.
Last name or family name.
The date of birth in ISO-8601 format.
date The tax authority ID.
Name of the tax authority.
The tax payer ID, e.g. EIN, TIN, SSN.
The national jurisdiction of the tax authority in ISO 3166-1 format.
If the tax authority is subnational, the ISO 3166-2 subdivision of the authority's jurisdiction. This is usually a state, province, or department.
The email address where this entity can be contacted.
Description of a street address.
The lines of the street address.
1 The city of the mailing address.
The first-level administrative subdivision, e.g., a state, province or district. Use ISO 3166-2 subdivisions (note: _not_ ISO-3166-alpha-2).
The ISO 3166-alpha-2 country code.
The postal code.
The phone number, formatted using ITU standard E. 123.
Permanent identity identifier.
The display name of this entity (insufficient for KYC purposes)
Description of the loan's eligibility for public service forgiveness.
Indicates the loan's eligibility for PSLF.
The number of payments made which qualify under PSLF.
0 Total payments required for forgiveness.
0 The loan's sequence number.
The balance of any rewards associated with this account.
Fixed-point decimal number, carried up to six decimal places.
^-?(\d*)(?:\.\d{1,2})?$ The total credit limit for this account. If card has no limit, use null.
Fixed-point decimal number, carried up to six decimal places.
^-?(\d*)(?:\.\d{1,2})?$ References to the Identities for non-owner authorized spenders.
Effective interest rates for different balances associated with this card.
The date this rate came into effect, typical of special offer rates, e.g. 0% purchase rate for 12 months. Use start_date and end_date to represent changes in the purchase APR as well.
date The date this rate ends being effective for this rate type. Use null when the rate does not have a set end date.
date The type of balance subject to this rate.
purchase, cash advance, balance transferThe APR covering this balance.
^\d*(\.\d{1,4})?$ The current balance subject to this rate, following the definition of current_balance.
^-?(\d*)(?:\.\d{1,2})?$ The amount within the subject_balance that was generated by this interest rate.
^-?(\d*)(?:\.\d{1,2})?$ The ISO-4217 currency in which this account's reward balances are denominated
If the account's reward balance is denominated in a non-ISO currency, provide the currency's symbol
URL reference to an image of the payment card face.
{
"user_identity_id": "d7f1b8b9-0006-4135-91c0-b5532045a314",
"identities": [
{
"id": "d7f1b8b9-0006-4135-91c0-b5532045a314",
"name": "Jane Doe",
"email": "jane@plaid.com"
}
],
"accounts": [
{
"id": "account_5921",
"isin": "US17275R1023",
"name": "CISCO SYSTEMS INC",
"symbol": "CSCO",
"is_cash_equivalent": true,
"current_price": "100.95",
"current_as_of": "2018-08-28",
"close_price": "100.95",
"type": "cash",
"currency": "USD",
"non_iso_currency": null
}
],
"securities": [
{
"id": "R13oiR6lC5jNC5jK",
"last_activity_at": "2018-08-28",
"ownership_type": "individual",
"owner_identity_ids": [
"6gXfjEcgqcjTVnUgbTwDF3DTeiQ"
],
"non_owner_identity_ids": null,
"status": "active",
"type": "depository",
"subtype": "cash management",
"name": "Vacation Money",
"official_name": "Pro Checking",
"display_mask": "9833",
"opening_date": "2018-08-28",
"current_balance": "100.95",
"available_balance": "100.95",
"tax_advantaged": true,
"currency": "USD",
"non_iso_currency": null
}
]
}Plaid’s privacy guarantee to end users is that it will never share per-account data, including knowledge of the existence of individual accounts, with applications unless the user has affirmatively indicated those accounts and applications should be linked. Plaid also will also minimize the storage details of accounts retrieved through this API which are not linked to any applications.
At times, it is necessary to communicate information about accounts not connected to any Plaid-powered applications, primarily for the purpose of enabling sensible UX, e.g. when drawing account selection screens. To ease implementation, this API operates at a per-user granularity and not a per-account granularity, because Plaid assumes the responsibility of providing a privacy-conscious view of the user’s accounts to each application.
However, Plaid provides the NotionalAccount and BasicIdentity models to enable implementers, if desired, to mask the existence of identities and accounts it knows are not linked to any Plaid applications. The partner is expected to use the Authorization API to ensure its access policy is synchronized with that of Plaid’s, i.e. both Plaid and the partner see the same items. Failure to do so will result in an inconsistent state and degraded end-user experiences.
304 Not Changed
If present, Plaid will consume the ETag header, and then present the most-recently seen ETag using the If-None-Match header on subsequent requests. If there has been no activity on, and no change to, the customer’s account, the partner may return 304 Not Changed with an empty HTTP body. Plaid will end the session and send no more requests until the next scheduled update.
It is recommended to generate ETags by concatenating and hashing the account_ids and last_activity_at timestamps for all accounts present in the response. If any identity data has changed, the ETag should always be new.
Get Transactions Endpoint
GET /users/{user_id}/transactions
Provides a query interface for a user’s transactions across all accounts, optionally filtered by posting date.
Parameters
Retrieve user transactions.
Provides a query interface for a user’s transactions across all accounts, optionally filtered by posting date.
Request fields
Opaque user identifier.
pathThe offset from the beginning of the result set. For example, if start is set to 500, the results set will start with the 501st transaction. (If this parameter is not provided, the results set will start with the 1st transaction by default.)
0 queryThe number of transactions to return in a given results set. For example, if limit is set to 10, the response will be limited to 10 transactions. (If this parameter is not provided, the results set to include up to 500 transactions by default.)
500 queryOldest posting date from which to start returning transactions. If not provided, default to 30 days ago.
date queryMost recent posting date for which transactions may be included. If not provided, default to the current date.
date queryWhen considering whether a pending transaction (one which has not yet posted)
should be included in a TransactionsResponse, evaluate whether the transaction
date (transacted_at) falls within the range.
Responses
200 OK
The request was authorized and well-formed.
TransactionsResponse
Successful response to Transactions request. Either offset or total can be used when paging. If both are used, total will be used instead of offset.
Properties
The number of transactions matching the request. This must count the _total number of transactions_ matching the query, not just the length of this response.
A natural number, i.e. a non-negative integer.
0 A cursor string that represents the next page of transactions. Sending a blank offset will indicate the final page.
Initial call will be a 0.
Sequence of BaseTransaction subclass instances, across all accounts, matching the query.
Permanent, unique transaction identifier. Must survive changes to pending status or amount.
References to the account that this transaction is posting against.
Description of the transaction.
Nullable: true
Addenda or distinguishing information for the transaction.
Hierarchical categorization, use multi-valued array to indicate hierarchy.
Flat categorization. For hashtags omit leading #.
The balance of the account after this transaction posts.
^-?(\d*)(?:\.\d{1,2})?$ The date/time when the transaction was authorized, in the time zone local to the transaction or to the customer.
date-time The date/time when the transaction settled, in the time zone local to the customer. Must be null if the transaction is pending.
Nullable: true
date-time Reference to the identity of the authorized spender who conducted this transaction.
Reference to the identity of the merchant related to this transaction.
Geographic location where this transaction occurs.
Geographic coordinates in EPSG:4326 WGS84 (lat/long)
Latitude coordinate.
Longitude coordinate.
City name.
Region identifier.
Country identifier.
The ISO 4217 currency in which this transaction's reward contribution is denominated. example: USD
If the reward contribution is denominated in a non-ISO currency, provide the currency's symbol.
The ISO 4217 currency in which this transaction is denominated. One of either the currency or non_iso_currency fields is required.
If the transaction is denominated in a non-ISO currency, provide the currency's symbol.
pending,fee_amount,reward_amount,reward_rate,transfer_account_id,method.security_id,quantity,price,fees,status,cancel_transaction_id.principal_amount,interest_amount,escrow_amount.
Indicates that this transaction has not posted.
The amount of fees associated with this transaction.
^-?(\d*)(?:\.\d{1,2})?$ The amount of rewards associated with this transaction.
^-?(\d*)(?:\.\d{1,2})?$ The effective rate of reward for this transaction.
^\d*(\.\d{1,4})?$ If this transaction is an internal transfer type, references the account_id associated with this transaction.
Classification of DepositoryOrCreditTransaction by method.
card present: Transaction was conducted by a physical payment card interaction (e.g. swipe, chip-and-sign, contactless).
card not present: Card was not physically present for transaction (e.g. online or phone order).
check: Check drafted against account.
eft: Electronic funds transfer.
card present, card not present, check, eftReference to the security that the transaction is posting for.
The quantity of the security involved in this transaction.
^-?(\d*)(?:\.\d{1,2})?$ The price of the security at which the transaction occured.
^-?(\d*)(?:\.\d{1,2})?$ The total combined fees associated with this transaction.
^-?(\d*)(?:\.\d{1,2})?$ Status of an InvestmentTransaction.
pending: The trade is in progress, or transfer is pending.
settled: The transaction has completed.
cancelled: The transaction was cancelled, or represents the cancelled portion of a previous order.
pending, settled, cancelledIf the status is cancelled, but this transaction represents the unfulfilled portion of a partially filled order, provide the transaction_id of the transaction representing the filled portion.
The amount affecting the principal balance.
^-?(\d*)(?:\.\d{1,2})?$ The amount affecting the interest balance.
^-?(\d*)(?:\.\d{1,2})?$ The amount affecting the escrow account (mortgages only, required.)
^-?(\d*)(?:\.\d{1,2})?$ {
"total": 1,
"transactions": [
{
"type": "transfer",
"pending": false,
"amount": "250",
"fee_amount": "0",
"reward_amount": "0",
"reward_rate": "0",
"transfer_account_id": "3AP9Lwoo3s30E",
"method": "eft",
"id": "6AOU0jwFQw3sMZJ",
"account_id": "account1234",
"description": "Finance Charge",
"memo": "Transfer to Checking",
"category": null,
"tags": null,
"ending_balance": "1820.95",
"transacted_at": "2019-08-24T14:15:22Z",
"settled_at": "2019-08-25T08:15:42Z",
"spender_identity_id": "uid_1234",
"merchant_identity_id": null,
"geolocation": {
"coordinates": {
"lat": 40.7128,
"lon": 74.006
},
"city": "New York",
"region": "US-NY",
"country": "US"
},
"reward_currency": "USD",
"reward_non_iso_currency": null,
"currency": "USD",
"non_iso_currency": null
}
]
}