Retrieve information from the bank accounts used for income verification

POST /credit/bank_income/get

/credit/bank_income/get returns the bank income report(s) for a specified user. A single report corresponds to all institutions linked in a single Link session. To include multiple institutions in a single report, use Multi-Item Link. To return older reports, use the options.count field.

Request Body

Required

CreditBankIncomeGetRequest defines the request schema for /credit/bank_income/get.

Parameters

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.
user_token
string
The user token associated with the User data is being requested for.
options
object
An optional object for /credit/bank_income/get request options.
count
integer
How many Bank Income Reports should be fetched. Multiple reports may be available if the report has been re-created or refreshed. If more than one report is available, the most recent reports will be returned first.

Response

CreditBankIncomeGetResponse defines the response schema for /credit/bank_income/get

Response Properties

bank_income
array[object]
bank_income_id
string
The unique identifier associated with the Bank Income Report.
generated_time
string
The time when the report was generated.
days_requested
integer
The number of days requested by the customer for the report.
items
array[object]
The list of Items in the report along with the associated metadata about the Item.
bank_income_accounts
array[object]
The Item’s accounts that have Bank Income data.
account_id
required, string
Plaid’s unique identifier for the account.
mask
required, string
The last 2-4 alphanumeric characters of an account’s official account number. Note that the mask may be non-unique between an Item’s accounts, and it may also not match the mask that the bank displays to the user.
name
required, string
The name of the bank account.
official_name
required, string
The official name of the bank account.
subtype
required, string
Valid account subtypes for depository accounts. For a list containing descriptions of each subtype, see Account schemas.
type
required, string
The account type. This will always be depository.
owners
required, array[object]
Data returned by the financial institution about the account owner or owners. Identity information is optional, so field may return an empty array.
names
required, array[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
required, array[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.
emails
required, array[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.
addresses
required, array[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.
bank_income_sources
array[object]
The income sources for this Item. Each entry in the array is a single income source.
income_source_id
string
A unique identifier for an income source.
income_description
string
The most common name or original description for the underlying income transactions.
income_category
string
The income category. BANK_INTEREST: Interest earned from a bank account. BENEFIT_OTHER: Government benefits other than retirement, unemployment, child support, or disability. Currently used only in the UK, to represent benefits such as Cost of Living Payments. CASH: Deprecated and used only for existing legacy implementations. Has been replaced by CASH_DEPOSIT and TRANSFER_FROM_APPLICATION. CASH_DEPOSIT: A cash or check deposit. CHILD_SUPPORT: Child support payments received. GIG_ECONOMY: Income earned as a gig economy worker, e.g. driving for Uber, Lyft, Postmates, DoorDash, etc. LONG_TERM_DISABILITY: Disability payments, including Social Security disability benefits. OTHER: Income that could not be categorized as any other income category. MILITARY: Veterans benefits. Income earned as salary for serving in the military (e.g. through DFAS) will be classified as SALARY rather than MILITARY. RENTAL: Income earned from a rental property. Income may be identified as rental when the payment is received through a rental platform, e.g. Airbnb; rent paid directly by the tenant to the property owner (e.g. via cash, check, or ACH) will typically not be classified as rental income. RETIREMENT: Payments from private retirement systems, pensions, and government retirement programs, including Social Security retirement benefits. SALARY: Payment from an employer to an earner or other form of permanent employment. TAX_REFUND: A tax refund. TRANSFER_FROM_APPLICATION: Deposits from a money transfer app, such as Venmo, Cash App, or Zelle. UNEMPLOYMENT: Unemployment benefits. In the UK, includes certain low-income benefits such as the Universal Credit.
account_id
string
Plaid’s unique identifier for the account.
start_date
string
Minimum of all dates within the specific income sources in the user’s bank account for days requested by the client. The date will be returned in an ISO 8601 format (YYYY-MM-DD).
end_date
string
Maximum of all dates within the specific income sources in the user’s bank account for days requested by the client. The date will be returned in an ISO 8601 format (YYYY-MM-DD).
pay_frequency
string
The income pay frequency.
total_amount
number
Total amount of earnings in the user’s bank account for the specific income source for days requested by the client.
transaction_count
integer
Number of transactions for the income source within the start and end date.
historical_summary
array[object]
total_amount
number
Total amount of earnings for the income source(s) of the user for the month in the summary. This may return an incorrect value if the summary includes income sources in multiple currencies. Please use total_amounts instead.
iso_currency_code
string
The ISO 4217 currency code of the amount or balance. Please use total_amounts instead.
unofficial_currency_code
string
The unofficial currency code associated with the amount or 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. Please use total_amounts instead.
total_amounts
array[object]
Total amount of earnings for the income source(s) of the user for the month in the summary. This can contain multiple amounts, with each amount denominated in one unique currency.
start_date
string
The start date of the period covered in this monthly summary. This date will be the first day of the month, unless the month being covered is a partial month because it is the first month included in the summary and the date range being requested does not begin with the first day of the month. The date will be returned in an ISO 8601 format (YYYY-MM-DD).
end_date
string
The end date of the period included in this monthly summary. This date will be the last day of the month, unless the month being covered is a partial month because it is the last month included in the summary and the date range being requested does not end with the last day of the month. The date will be returned in an ISO 8601 format (YYYY-MM-DD).
transactions
array[object]
last_updated_time
string
The time when this Item’s data was last retrieved from the financial institution.
institution_id
string
The unique identifier of the institution associated with the Item.
institution_name
string
The name of the institution associated with the Item.
item_id
string
The unique identifier for the Item.
bank_income_summary
object
Summary for bank income across all income sources and items (max history of 730 days).
total_amount
number
Total amount of earnings across all the income sources in the end user’s Items for the days requested by the client. This may return an incorrect value if the summary includes income sources in multiple currencies. Please use total_amounts instead.
iso_currency_code
string
The ISO 4217 currency code of the amount or balance. Please use total_amounts instead.
unofficial_currency_code
string
The unofficial currency code associated with the amount or 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. Please use total_amounts instead.
total_amounts
array[object]
Total amount of earnings across all the income sources in the end user’s Items for the days requested by the client. This can contain multiple amounts, with each amount denominated in one unique currency.
amount
required, number
Value of amount with up to 2 decimal places.
iso_currency_code
required, string
The ISO 4217 currency code of the amount or balance.
unofficial_currency_code
required, string
The unofficial currency code associated with the amount or 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.
start_date
string
The earliest date within the days requested in which all income sources identified by Plaid appear in a user’s account. The date will be returned in an ISO 8601 format (YYYY-MM-DD).
end_date
string
The latest date in which all income sources identified by Plaid appear in the user’s account. The date will be returned in an ISO 8601 format (YYYY-MM-DD).
income_sources_count
integer
Number of income sources per end user.
income_categories_count
integer
Number of income categories per end user.
income_transactions_count
integer
Number of income transactions per end user.
historical_summary
array[object]
total_amount
number
Total amount of earnings for the income source(s) of the user for the month in the summary. This may return an incorrect value if the summary includes income sources in multiple currencies. Please use total_amounts instead.
iso_currency_code
string
The ISO 4217 currency code of the amount or balance. Please use total_amounts instead.
unofficial_currency_code
string
The unofficial currency code associated with the amount or 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. Please use total_amounts instead.
total_amounts
array[object]
Total amount of earnings for the income source(s) of the user for the month in the summary. This can contain multiple amounts, with each amount denominated in one unique currency.
amount
required, number
Value of amount with up to 2 decimal places.
iso_currency_code
required, string
The ISO 4217 currency code of the amount or balance.
unofficial_currency_code
required, string
The unofficial currency code associated with the amount or 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.
start_date
string
The start date of the period covered in this monthly summary. This date will be the first day of the month, unless the month being covered is a partial month because it is the first month included in the summary and the date range being requested does not begin with the first day of the month. The date will be returned in an ISO 8601 format (YYYY-MM-DD).
end_date
string
The end date of the period included in this monthly summary. This date will be the last day of the month, unless the month being covered is a partial month because it is the last month included in the summary and the date range being requested does not end with the last day of the month. The date will be returned in an ISO 8601 format (YYYY-MM-DD).
transactions
array[object]
amount
number
The settled value of the transaction, denominated in the transactions’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, credit card purchases are positive; credit card payment, direct deposits, and refunds are negative.
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).
name
string
The merchant name or transaction description.
original_description
string
The string returned by the financial institution to describe the transaction.
pending
boolean
When true, identifies the transaction as pending or unsettled. Pending transaction details (name, type, amount, category ID) may change before they are settled.
transaction_id
string
The unique ID of the transaction. Like all Plaid identifiers, the transaction_id is case sensitive.
check_number
string
The check number of the transaction. This field is only populated for check transactions.
iso_currency_code
string
The ISO 4217 currency code of the amount or balance.
unofficial_currency_code
string
The unofficial currency code associated with the amount or 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.
warnings
array[object]
If data from the report was unable to be retrieved, the warnings will contain information about the error that caused the data to be incomplete.
warning_type
string
The warning type which will always be BANK_INCOME_WARNING.
warning_code
string
The warning code identifies a specific kind of warning. IDENTITY_UNAVAILABLE: Unable to extract identity for the Item TRANSACTIONS_UNAVAILABLE: Unable to extract transactions for the Item ITEM_UNAPPROVED: User exited flow before giving permission to share data for the Item REPORT_DELETED: Report deleted due to customer or consumer request DATA_UNAVAILABLE: No relevant data was found for the Item
cause
object
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
required, string
A broad categorization of the error. Safe for programmatic use.
error_code
required, string
We use standard HTTP response codes for success and failure notifications, and our errors are further classified by error_type. In general, 200 HTTP codes correspond to success, 40X codes are for developer- or user-related failures, and 50X codes are for Plaid-related issues. Error fields will be null if no error has occurred.
error_message
required, string
A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use.
display_message
required, 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.
item_id
required, string
The item_id of the Item associated with this warning.
request_id
required, string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.