Income
API reference for Income endpoints and webhooks
Verify a user's income via payroll or bank account data.
| Endpoints | |
|---|---|
/user/create | Create a user for use with the income verification product |
/credit/sessions/get | Get Link session metadata and results for the end user |
/credit/bank_income/get | Retrieve information from the bank accounts used for income verification |
/credit/bank_income/pdf/get | Retrieve information from the bank accounts used for income verification in PDF format |
/credit/bank_income/refresh | Refresh a user's bank income information |
/credit/bank_income/webhook/update | Subscribe and unsubscribe to proactive notifications for a user's income profile |
/credit/bank_statements/uploads/get | Retrieve information from the bank statements used for income verification |
/credit/payroll_income/get | Retrieve information from the pay stubs or tax forms used for income verification |
/credit/payroll_income/risk_signals/get | Analyze uploaded income documents for indications of potential fraud |
/credit/payroll_income/parsing_config/update | Update the parsing configuration for a document verification |
/credit/employment/get | (Beta) Retrieve employment information about the end user |
/credit/payroll_income/refresh | (Beta) Retrieve updated payroll income data on a linked account |
| See also | |
|---|---|
/sandbox/income/fire_webhook | Manually fire an Income webhook (Sandbox only) |
| Webhooks | |
|---|---|
INCOME_VERIFICATION | Income verification has completed |
INCOME_VERIFICATION_RISK_SIGNALS | Risk evaluation of user-uploaded documents has completed |
BANK_INCOME_REFRESH_UPDATE | A change to user's income has been detected |
BANK_INCOME_REFRESH_COMPLETE | The refreshed report has finished generating |
INCOME_VERIFICATION_REFRESH_RECONNECT_NEEDED | A Payroll Income verification could not be refreshed |
Endpoints
/user/create
Create user
This endpoint should be called for each of your end users before they begin a Plaid income flow. This provides you a single token to access all income data associated with the user. You should only create one per end user.
If you call the endpoint multiple times with the same client_user_id, the first creation call will succeed and the rest will fail with an error message indicating that the user has been created for the given client_user_id.
Ensure that you store the user_token along with your user's identifier in your database, as it is not possible to retrieve a previously created user_token.
Request fields and example
client_idstring
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.secretstring
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.client_user_idrequiredstring
A unique ID representing the end user. Maximum of 128 characters. Typically this will be a user ID number from your application. Personally identifiable information, such as an email address or phone number, should not be used in the
client_user_id.Max length:
128 Min length:
1 1const request: UserCreateRequest = {2 client_user_id: 'c0e2c4ee-b763-4af5-cfe9-46a46bce883d',3};45try {6 const response = await client.userCreate(request);7} catch (error) {8 // handle error9}user/create
Response fields and example
user_tokenstring
The user token associated with the User data is being requested for.
user_idstring
The Plaid
user_id of the User associated with this webhook, warning, or error.request_idstring
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{2 "user_token": "user-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d",3 "user_id": "wz666MBjYWTp2PDzzggYhM6oWWmBb",4 "request_id": "Aim3b"5}Was this helpful?
/credit/sessions/get
Retrieve Link sessions for your user
This endpoint can be used for your end users after they complete the Link flow. This endpoint returns a list of Link sessions that your user completed, where each session includes the results from the Link flow.
These results include details about the Item that was created and some product related metadata (showing, for example, whether the user finished the bank income verification step).
Request fields and example
client_idstring
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.secretstring
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_tokenrequiredstring
The user token associated with the User data is being requested for.
1const request: CreditSessionsGetRequest = {2 user_token: 'user-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d',3};45try {6 const response = await client.creditSessionsGet(request);7} catch (error) {8 // handle error9}credit/sessions/get
Response fields and example
sessions[object]
A list of Link sessions for the user. Sessions will be sorted in reverse chronological order.
link_session_idstring
The unique identifier associated with the Link session. This identifier matches the
link_session_id returned in the onSuccess/onExit callbacks.session_start_timestring
The time when the Link session started
Format:
date-time resultsobject
The set of results for a Link session.
item_add_results[object]
The set of Item adds for the Link session.
public_tokenstring
Returned once a user has successfully linked their Item.
item_idstring
The Plaid Item ID. The
item_id is always unique; linking the same account at the same institution twice will result in two Items with different item_id values. Like all Plaid identifiers, the item_id is case-sensitive.institution_idstring
The Plaid Institution ID associated with the Item.
bank_income_results[object]
The set of bank income verifications for the Link session.
statusstring
Status of the Bank Income Link session.
APPROVED: User has approved and verified their incomeNO_DEPOSITS_FOUND: We attempted, but were unable to find any income in the connected account.USER_REPORTED_NO_INCOME: The user explicitly indicated that they don't receive income in the connected account.STARTED: The user began the bank income portion of the link flow.INTERNAL_ERROR: The user encountered an internal error.Possible values:
APPROVED, NO_DEPOSITS_FOUND, USER_REPORTED_NO_INCOMEitem_idstring
The Plaid Item ID. The
item_id is always unique; linking the same account at the same institution twice will result in two Items with different item_id values. Like all Plaid identifiers, the item_id is case-sensitive.institution_idstring
The Plaid Institution ID associated with the Item.
bank_employment[object]
The set of bank employment verifications for the Link session.
statusstring
Status of the Bank Employment Link session.
APPROVED: User has approved and verified their employment.NO_EMPLOYMENTS_FOUND: We attempted, but were unable to find any employment in the connected account.EMPLOYER_NOT_LISTED: The user explicitly indicated that they did not see their current or previous employer in the list of employer names found.STARTED: The user began the bank income portion of the link flow.INTERNAL_ERROR: The user encountered an internal error.Possible values:
APPROVED, NO_EMPLOYERS_FOUND, EMPLOYER_NOT_LISTEDitem_idstring
The Plaid Item ID. The
item_id is always unique; linking the same account at the same institution twice will result in two Items with different item_id values. Like all Plaid identifiers, the item_id is case-sensitive.institution_idstring
The Plaid Institution ID associated with the Item.
payroll_income_results[object]
The set of payroll income verifications for the Link session.
num_paystubs_retrievedinteger
The number of paystubs retrieved from a payroll provider.
num_w2s_retrievedinteger
The number of w2s retrieved from a payroll provider.
institution_idstring
The Plaid Institution ID associated with the Item.
institution_namestring
The Institution Name associated with the Item.
document_incomenullableobject
The details of a document income verification in Link
num_paystubs_uploadedinteger
The number of paystubs uploaded by the user.
num_w2s_uploadedinteger
The number of w2s uploaded by the user.
num_bank_statementsinteger
The number of bank statements uploaded by the user.
num_1099s_uploadedinteger
The number of 1099s uploaded by the user
errors[object]
The set of errors that occurred during the Link session.
error_typestring
A broad categorization of the error.
error_codestring
The particular error code.
error_messagestring
A developer-friendly representation of the error code.
display_messagenullablestring
A user-friendly representation of the error code.
null if the error is not related to user action.request_idstring
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{2 "request_id": "Aim3b",3 "sessions": [4 {5 "link_session_id": "356dbb28-7f98-44d1-8e6d-0cec580f3171",6 "results": {7 "item_add_results": [8 {9 "public_token": "public-sandbox-5c224a01-8314-4491-a06f-39e193d5cddc",10 "item_id": "M5eVJqLnv3tbzdngLDp9FL5OlDNxlNhlE55op",11 "institution_id": "ins_56"12 }13 ],14 "bank_income_results": [15 {16 "status": "APPROVED",17 "item_id": "M5eVJqLnv3tbzdngLDp9FL5OlDNxlNhlE55op",18 "institution_id": "ins_56"19 }20 ]21 },22 "session_start_time": "2022-09-30T23:40:30.946225Z"23 },24 {25 "link_session_id": "f742cae8-31e4-49cc-a621-6cafbdb26fb9",26 "results": {27 "payroll_income_results": [28 {29 "num_paystubs_retrieved": 2,30 "num_w2s_retrieved": 1,31 "institution_id": "ins_92"32 }33 ]34 },35 "session_start_time": "2022-09-26T23:40:30.946225Z"36 }37 ]38}Was this helpful?
/credit/bank_income/get
Retrieve information from the bank accounts used for income verification
/credit/bank_income/get returns the bank income report(s) for a specified user.
Request fields and example
client_idstring
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.secretstring
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_tokenstring
The user token associated with the User data is being requested for.
optionsobject
An optional object for
/credit/bank_income/get request options.countinteger
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.
Default:
1 1const request: CreditBankIncomeGetRequest = {2 user_token: 'user-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d',3 options: {4 count: 1,5 },6};78try {9 const response = await client.creditBankIncomeGet(request);10} catch (error) {11 // handle error12}credit/bank_income/get
Response fields and example
bank_income[object]
bank_income_idstring
The unique identifier associated with the Bank Income Report.
generated_timestring
The time when the Bank Income Report was generated.
Format:
date-time days_requestedinteger
The number of days requested by the customer for the Bank Income Report.
items[object]
The list of Items in the report along with the associated metadata about the Item.
bank_income_accounts[object]
The Item's accounts that have Bank Income data.
account_idstring
Plaid's unique identifier for the account.
masknullablestring
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.
namestring
The name of the bank account.
official_namenullablestring
The official name of the bank account.
subtypestring
Valid account subtypes for depository accounts. For a list containing descriptions of each subtype, see Account schemas.
Possible values:
checking, savings, hsa, cd, money market, paypal, prepaid, cash management, ebt, alltypestring
The account type. This will always be
depository.Possible values:
depositoryowners[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[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
If an Item contains multiple accounts with different owner names, some institutions will report all names associated with the Item in each account's
names array.phone_numbers[object]
A list of phone numbers associated with the account by the financial institution. May be an empty array if no relevant information is returned from the financial institution.
emails[object]
A list of email addresses associated with the account by the financial institution. May be an empty array if no relevant information is returned from the financial institution.
addresses[object]
Data about the various addresses associated with the account by the financial institution. May be an empty array if no relevant information is returned from the financial institution.
dataobject
Data about the components comprising an address.
citynullablestring
The full city name
regionnullablestring
The region or state. In API versions 2018-05-22 and earlier, this field is called
state.
Example: "NC"streetstring
The full street address
Example:
"564 Main Street, APT 15"postal_codenullablestring
The postal code. In API versions 2018-05-22 and earlier, this field is called
zip.countrynullablestring
The ISO 3166-1 alpha-2 country code
primaryboolean
When
true, identifies the address as the primary address on an account.bank_income_sources[object]
The income sources for this Item. Each entry in the array is a single income source.
income_source_idstring
A unique identifier for an income source.
income_descriptionstring
The most common name or original description for the underlying income transactions.
income_categorystring
The income category. Note that the
CASH value has been deprecated and is used only for existing legacy implementations. It has been replaced by the new categories CASH_DEPOSIT (representing cash or check deposits) and TRANSFER_FROM_APPLICATION (representing cash transfers originating from apps, such as Zelle or Venmo).Possible values:
SALARY, UNEMPLOYMENT, CASH, GIG_ECONOMY, RENTAL, CHILD_SUPPORT, MILITARY, RETIREMENT, LONG_TERM_DISABILITY, BANK_INTEREST, CASH_DEPOSIT, TRANSFER_FROM_APPLICATION, TAX_REFUND, BENEFIT_OTHER, OTHERaccount_idstring
Plaid's unique identifier for the account.
start_datestring
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).
Format:
date end_datestring
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).
Format:
date pay_frequencystring
The income pay frequency.
Possible values:
WEEKLY, BIWEEKLY, SEMI_MONTHLY, MONTHLY, DAILY, UNKNOWNtotal_amountnumber
Total amount of earnings in the user’s bank account for the specific income source for days requested by the client.
transaction_countinteger
Number of transactions for the income source within the start and end date.
historical_summary[object]
total_amountdeprecatednumber
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_codedeprecatednullablestring
The ISO 4217 currency code of the amount or balance.
Please use
total_amounts instead.unofficial_currencydeprecatednullablestring
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[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.
amountnumber
Value of amount with up to 2 decimal places.
iso_currency_codenullablestring
The ISO 4217 currency code of the amount or balance.
unofficial_currencynullablestring
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_datestring
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).
Format:
date end_datestring
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).
Format:
date transactions[object]
amountnumber
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.datestring
For pending transactions, the date that the transaction occurred; for posted transactions, the date that the transaction posted.
Both dates are returned in an ISO 8601 format (YYYY-MM-DD).
Format:
date namestring
The merchant name or transaction description.
original_descriptionnullablestring
The string returned by the financial institution to describe the transaction.
pendingboolean
When true, identifies the transaction as pending or unsettled.
Pending transaction details (name, type, amount, category ID) may change before they are settled.
transaction_idstring
The unique ID of the transaction. Like all Plaid identifiers, the
transaction_id is case sensitive.check_numbernullablestring
The check number of the transaction. This field is only populated for check transactions.
iso_currency_codenullablestring
The ISO 4217 currency code of the amount or balance.
unofficial_currencynullablestring
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.last_updated_timestring
The time when this Item's data was last retrieved from the financial institution.
Format:
date-time institution_idstring
The unique identifier of the institution associated with the Item.
institution_namestring
The name of the institution associated with the Item.
item_idstring
The unique identifier for the Item.
bank_income_summaryobject
Summary for bank income across all income sources and items (max history of 730 days).
total_amountdeprecatednumber
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_codedeprecatednullablestring
The ISO 4217 currency code of the amount or balance.
Please use
total_amounts instead.unofficial_currencydeprecatednullablestring
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[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.
amountnumber
Value of amount with up to 2 decimal places.
iso_currency_codenullablestring
The ISO 4217 currency code of the amount or balance.
unofficial_currencynullablestring
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_datestring
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).
Format:
date end_datestring
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).
Format:
date income_sources_countinteger
Number of income sources per end user.
income_categoriesinteger
Number of income categories per end user.
income_transactionsinteger
Number of income transactions per end user.
historical_summary[object]
total_amountdeprecatednumber
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_codedeprecatednullablestring
The ISO 4217 currency code of the amount or balance.
Please use
total_amounts instead.unofficial_currencydeprecatednullablestring
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[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.
amountnumber
Value of amount with up to 2 decimal places.
iso_currency_codenullablestring
The ISO 4217 currency code of the amount or balance.
unofficial_currencynullablestring
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_datestring
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).
Format:
date end_datestring
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).
Format:
date transactions[object]
amountnumber
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.datestring
For pending transactions, the date that the transaction occurred; for posted transactions, the date that the transaction posted.
Both dates are returned in an ISO 8601 format (YYYY-MM-DD).
Format:
date namestring
The merchant name or transaction description.
original_descriptionnullablestring
The string returned by the financial institution to describe the transaction.
pendingboolean
When true, identifies the transaction as pending or unsettled.
Pending transaction details (name, type, amount, category ID) may change before they are settled.
transaction_idstring
The unique ID of the transaction. Like all Plaid identifiers, the
transaction_id is case sensitive.check_numbernullablestring
The check number of the transaction. This field is only populated for check transactions.
iso_currency_codenullablestring
The ISO 4217 currency code of the amount or balance.
unofficial_currencynullablestring
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[object]
If data from the Bank Income report was unable to be retrieved, the warnings will contain information about the error that caused the data to be incomplete.
warning_typestring
The warning type which will always be
BANK_INCOME_WARNING.Possible values:
BANK_INCOME_WARNINGwarning_codestring
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 ItemPossible values:
IDENTITY_UNAVAILABLE, TRANSACTIONS_UNAVAILABLE, ITEM_UNAPPROVED, REPORT_DELETED, DATA_UNAVAILABLEcauseobject
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_typestring
A broad categorization of the error. Safe for programmatic use.
Possible values:
INTERNAL_SERVER_ERROR, INSUFFICIENT_CREDENTIALS, ITEM_LOCKED, USER_SETUP_REQUIRED, COUNTRY_NOT_SUPPORTED, INSTITUTION_DOWN, INSTITUTION_NO_LONGER_SUPPORTED, INSTITUTION_NOT_RESPONDING, INVALID_CREDENTIALS, INVALID_MFA, INVALID_SEND_METHOD, ITEM_LOGIN_REQUIRED, MFA_NOT_SUPPORTED, NO_ACCOUNTS, ITEM_NOT_SUPPORTED, ACCESS_NOT_GRANTEDerror_codestring
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_messagestring
A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use.
display_messagestring
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_idstring
The
item_id of the Item associated with this warning.request_idstring
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{2 "request_id": "LhQf0THi8SH1yJm",3 "bank_income": [4 {5 "bank_income_id": "abc123",6 "generated_time": "2022-01-31T22:47:53Z",7 "days_requested": 90,8 "items": [9 {10 "last_updated_time": "2022-01-31T22:47:53Z",11 "institution_id": "ins_0",12 "institution_name": "Plaid Bank",13 "item_id": "“eVBnVMp7zdTJLkRNr33Rs6zr7KNJqBFL9DrE6”",14 "bank_income_accounts": [15 {16 "account_id": "“GeooLPBGDEunl54q7N3ZcyD5aLPLEai1nkzM9”",17 "mask": "8888",18 "name": "Plaid Checking Account",19 "official_name": "Plaid Checking Account",20 "type": "depository",21 "subtype": "checking",22 "owners": [23 {24 "addresses": [25 {26 "data": {27 "city": "Malakoff",28 "country": "US",29 "postal_code": "14236",30 "region": "NY",31 "street": "2992 Cameron Road"32 },33 "primary": true34 },35 {36 "data": {37 "city": "San Matias",38 "country": "US",39 "postal_code": "93405-2255",40 "region": "CA",41 "street": "2493 Leisure Lane"42 },43 "primary": false44 }45 ],46 "emails": [47 {48 "data": "accountholder0@example.com",49 "primary": true,50 "type": "primary"51 },52 {53 "data": "accountholder1@example.com",54 "primary": false,55 "type": "secondary"56 },57 {58 "data": "extraordinarily.long.email.username.123456@reallylonghostname.com",59 "primary": false,60 "type": "other"61 }62 ],63 "names": [64 "Alberta Bobbeth Charleson"65 ],66 "phone_numbers": [67 {68 "data": "1112223333",69 "primary": false,70 "type": "home"71 },72 {73 "data": "1112224444",74 "primary": false,75 "type": "work"76 },77 {78 "data": "1112225555",79 "primary": false,80 "type": "mobile"81 }82 ]83 }84 ]85 }86 ],87 "bank_income_sources": [88 {89 "account_id": "GeooLPBGDEunl54q7N3ZcyD5aLPLEai1nkzM9",90 "income_source_id": "“f17efbdd-caab-4278-8ece-963511cd3d51”",91 "income_description": "“PLAID_INC_DIRECT_DEP_PPD”",92 "income_category": "SALARY",93 "start_date": "2021-11-15",94 "end_date": "2022-01-15",95 "pay_frequency": "MONTHLY",96 "total_amount": 300,97 "transaction_count": 1,98 "historical_summary": [99 {100 "start_date": "2021-11-02",101 "end_date": "2021-11-30",102 "total_amount": 100,103 "iso_currency_code": "USD",104 "unofficial_currency_code": null,105 "total_amounts": [106 {107 "amount": 100,108 "iso_currency_code": "USD",109 "unofficial_currency_code": null110 }111 ],112 "transactions": [113 {114 "amount": -100,115 "date": "2021-11-15",116 "name": "“PLAID_INC_DIRECT_DEP_PPD”",117 "original_description": "PLAID_INC_DIRECT_DEP_PPD 123",118 "pending": false,119 "transaction_id": "6RddrWNwE1uM63Ex5GKLhzlBl76aAZfgzlQNm",120 "check_number": null,121 "iso_currency_code": "USD",122 "unofficial_currency_code": null123 }124 ]125 },126 {127 "start_date": "2021-12-01",128 "end_date": "2021-12-31",129 "total_amount": 100,130 "iso_currency_code": "USD",131 "unofficial_currency_code": null,132 "total_amounts": [133 {134 "amount": 100,135 "iso_currency_code": "USD",136 "unofficial_currency_code": null137 }138 ],139 "transactions": [140 {141 "amount": -100,142 "date": "2021-12-15",143 "name": "“PLAID_INC_DIRECT_DEP_PPD”",144 "original_description": "PLAID_INC_DIRECT_DEP_PPD 123",145 "pending": false,146 "transaction_id": "7BddrWNwE1uM63Ex5GKLhzlBl82aAZfgzlCBl",147 "check_number": null,148 "iso_currency_code": "USD",149 "unofficial_currency_code": null150 }151 ]152 },153 {154 "start_date": "2022-01-01",155 "end_date": "2021-01-31",156 "total_amount": 100,157 "iso_currency_code": "USD",158 "unofficial_currency_code": null,159 "total_amounts": [160 {161 "amount": 100,162 "iso_currency_code": "USD",163 "unofficial_currency_code": null164 }165 ],166 "transactions": [167 {168 "amount": -100,169 "date": "2022-01-31",170 "name": "“PLAID_INC_DIRECT_DEP_PPD”",171 "original_description": "PLAID_INC_DIRECT_DEP_PPD 123",172 "pending": false,173 "transaction_id": "9FddrWNwE1uM95Ex5GKLhzlBl76aAZfgzlNQr",174 "check_number": null,175 "iso_currency_code": "USD",176 "unofficial_currency_code": null177 }178 ]179 }180 ]181 }182 ]183 }184 ],185 "bank_income_summary": {186 "total_amount": 300,187 "iso_currency_code": "USD",188 "unofficial_currency_code": null,189 "total_amounts": [190 {191 "amount": 300,192 "iso_currency_code": "USD",193 "unofficial_currency_code": null194 }195 ],196 "start_date": "2021-11-15",197 "end_date": "2022-01-15",198 "income_sources_count": 1,199 "income_categories_count": 1,200 "income_transactions_count": 1,201 "historical_summary": [202 {203 "start_date": "2021-11-02",204 "end_date": "2021-11-30",205 "total_amount": 100,206 "iso_currency_code": "USD",207 "unofficial_currency_code": null,208 "total_amounts": [209 {210 "amount": 100,211 "iso_currency_code": "USD",212 "unofficial_currency_code": null213 }214 ],215 "transactions": [216 {217 "amount": -100,218 "date": "2021-11-15",219 "name": "“PLAID_INC_DIRECT_DEP_PPD”",220 "original_description": "PLAID_INC_DIRECT_DEP_PPD 123",221 "pending": false,222 "transaction_id": "6RddrWNwE1uM63Ex5GKLhzlBl76aAZfgzlQNm",223 "check_number": null,224 "iso_currency_code": "USD",225 "unofficial_currency_code": null226 }227 ]228 },229 {230 "start_date": "2021-12-01",231 "end_date": "2021-12-31",232 "total_amount": 100,233 "iso_currency_code": "USD",234 "unofficial_currency_code": null,235 "total_amounts": [236 {237 "amount": 100,238 "iso_currency_code": "USD",239 "unofficial_currency_code": null240 }241 ],242 "transactions": [243 {244 "amount": -100,245 "date": "2021-12-15",246 "name": "“PLAID_INC_DIRECT_DEP_PPD”",247 "original_description": "PLAID_INC_DIRECT_DEP_PPD 123",248 "pending": false,249 "transaction_id": "7BddrWNwE1uM63Ex5GKLhzlBl82aAZfgzlCBl",250 "check_number": null,251 "iso_currency_code": "USD",252 "unofficial_currency_code": null253 }254 ]255 },256 {257 "start_date": "2022-01-01",258 "end_date": "2021-01-31",259 "total_amount": 100,260 "iso_currency_code": "USD",261 "unofficial_currency_code": null,262 "total_amounts": [263 {264 "amount": 100,265 "iso_currency_code": "USD",266 "unofficial_currency_code": null267 }268 ],269 "transactions": [270 {271 "amount": -100,272 "date": "2022-01-31",273 "name": "“PLAID_INC_DIRECT_DEP_PPD”",274 "original_description": "PLAID_INC_DIRECT_DEP_PPD 123",275 "pending": false,276 "transaction_id": "9FddrWNwE1uM95Ex5GKLhzlBl76aAZfgzlNQr",277 "check_number": null,278 "iso_currency_code": "USD",279 "unofficial_currency_code": null280 }281 ]282 }283 ]284 },285 "warnings": []286 }287 ]288}Was this helpful?
/credit/bank_income/pdf/get
Retrieve information from the bank accounts used for income verification in PDF format
/credit/bank_income/pdf/get returns the most recent bank income report for a specified user in PDF format.
Request fields and example
client_idstring
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.secretstring
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_tokenrequiredstring
The user token associated with the User data is being requested for.
1const request: CreditBankIncomePDFGetRequest = {2 user_token: 'user-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d',3};45try {6 const response = await client.creditBankIncomePdfGet(request, {7 responseType: 'arraybuffer',8 });9 const pdf = response.buffer.toString('base64');10} catch (error) {11 // handle error12}Response
This endpoint returns binary PDF data. View a sample Bank Income PDF.
/credit/bank_income/refresh
Refresh a user's bank income information
/credit/bank_income/refresh refreshes the bank income report data for a specific user.
Request fields and example
client_idstring
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.secretstring
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_tokenrequiredstring
The user token associated with the User data is being requested for.
optionsobject
An optional object for
/credit/bank_income/refresh request options.days_requestedinteger
How many days of data to include in the refresh. If not specified, this will default to the days requested in the most recently generated bank income report for the user.
1const request: CreditBankIncomeRefreshRequest = {2 user_token: 'user-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d',3 options: {4 days_requested: 90,5 },6};78try {9 const response = await client.creditBankIncomeRefresh(request);10} catch (error) {11 // handle error12}credit/bank_income/refresh
Response fields and example
request_idstring
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{2 "request_id": "LhQf0THi8SH1yJm"3}Was this helpful?
/credit/bank_income/webhook/update
Subscribe and unsubscribe to proactive notifications for a user's income profile
/credit/bank_income/webhook/update allows you to subscribe or unsubscribe a user for income webhook notifications. By default, all users start out unsubscribed.
If a user is subscribed, on significant changes to the user's income profile, you will receive a BANK_INCOME_REFRESH_UPDATE webhook, prompting you to refresh bank income data for the user.
Request fields and example
client_idstring
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.secretstring
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_tokenrequiredstring
The user token associated with the User data is being requested for.
enable_webhooksrequiredboolean
Whether the user should be enabled for proactive webhook notifications when their income changes
1const request: CreditBankIncomeWebhookUpdateRequest = {2 user_token: 'user-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d',3 enable_webhooks: true,4};56try {7 const response = await client.creditBankIncomeWebhookUpdateRequest(request);8} catch (error) {9 // handle error10}credit/bank_income/webhook/update
Response fields and example
request_idstring
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{2 "request_id": "LhQf0THi8SH1yJm"3}Was this helpful?
/credit/bank_statements/uploads/get
Retrieve data for a user's uploaded bank statements
/credit/bank_statements/uploads/get returns parsed data from bank statements uploaded by users as part of the Document Income flow. If your account is not enabled for Document Parsing, contact your account manager to request access.
Request fields and example
client_idstring
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.secretstring
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_tokenrequiredstring
The user token associated with the User data is being requested for.
optionsobject
An optional object for
/credit/bank_statements/uploads/get request options.item_ids[string]
An array of
item_ids whose bank statements information is returned. Each item_id should uniquely identify a bank statements uploaded item. If this field is not provided, all item_ids associated with the user_token will returned in the response.1const request: CreditBankStatementsUploadsGetRequest = {2 user_token: 'user-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d',3};45try {6 const response = await client.creditBankStatementsUploadsGet(request);7} catch (error) {8 // handle error9}credit/bank_statements/uploads/get
Response fields and example
items[object]
Array of bank statement upload items.
item_idstring
The
item_id of the Item associated with this webhook, warning, or errorbank_statements[object]
transactions[object]
An array of transactions appearing on the bank statement.
amountnullablenumber
The value of the transaction. A negative amount indicates that money moved into the account (such as a paycheck being deposited).
datenullablestring
The date of when the transaction was made, in ISO 8601 format (YYYY-MM-DD).
Format:
date original_descriptionnullablestring
The raw description of the transaction as it appears on the bank statement.
account_idnullablestring
The unique id of the bank account that this transaction occurs in
document_metadataobject
Object representing metadata pertaining to the document.
namestring
The name of the document.
document_typenullablestring
The type of document.
PAYSTUB: A paystub.BANK_STATEMENT: A bank statement.US_TAX_W2: A W-2 wage and tax statement provided by a US employer reflecting wages earned by the employee.US_MILITARY_ERAS: An electronic Retirement Account Statement (eRAS) issued by the US military.US_MILITARY_LES: A Leave and Earnings Statement (LES) issued by the US military.US_MILITARY_CLES: A Civilian Leave and Earnings Statment (CLES) issued by the US military.GIG: Used to indicate that the income is related to gig work. Does not necessarily correspond to a specific document type.PLAID_GENERATED_PAYSTUB_PDF: Used to indicate that the PDF for the paystub was generated by Plaid.NONE: Used to indicate that there is no underlying document for the data.UNKNOWN: Document type could not be determined.Possible values:
UNKNOWN, PAYSTUB, BANK_STATEMENT, US_TAX_W2, US_MILITARY_ERAS, US_MILITARY_LES, US_MILITARY_CLES, GIG, PLAID_GENERATED_PAYSTUB_PDF, NONEdownload_urlnullablestring
Signed URL to retrieve the underlying file. For Payroll Income, the file type will always be PDF, and the file may not be available, in which case the field will be
For Document Income, this field will not be
This download URL can only be used once and expires after two minutes. To generate a new download URL, call
null. If you would like Plaid to generate a PDF if the original is not available, contact your Account Manager. Example generated pay stub.For Document Income, this field will not be
null, and the file type will be the original file type uploaded by the user. For more details on available file types, see the Document Income documentation.This download URL can only be used once and expires after two minutes. To generate a new download URL, call
/credit/payroll_income/get again.statusnullablestring
The processing status of the document.
PROCESSING_COMPLETE: The document was successfully processed.DOCUMENT_ERROR: The document could not be processed. Possible causes include: The document was an unacceptable document type such as an offer letter or bank statement, the document image was cropped or blurry, or the document was corrupted.UNKNOWN or null: An internal error occurred. If this happens repeatedly, contact support or your Plaid account manager.Possible values:
UNKNOWN, PROCESSING_COMPLETE, DOCUMENT_ERROR, nullpage_countnullableinteger
The number of pages of the uploaded document (if available).
document_idnullablestring
An identifier of the document referenced by the document metadata.
bank_accounts[object]
An array of bank accounts associated with the uploaded bank statement.
namenullablestring
The name of the bank account
bank_namenullablestring
The name of the bank institution.
account_typenullablestring
The type of the bank account.
account_numbernullablestring
The bank account number.
periods[object]
An array of period objects, containing more data on the overall period of the statement.
start_datenullablestring
The start date of the statement period in ISO 8601 format (YYYY-MM-DD).
Format:
date end_datenullablestring
The end date of the statement period in ISO 8601 format (YYYY-MM-DD).
Format:
date starting_balancenullablenumber
The starting balance of the bank account for the period.
ending_balancenullablenumber
The ending balance of the bank account for the period.
account_idnullablestring
The unique id of the bank account
statusnullableobject
Details about the status of the payroll item.
processing_statusnullablestring
Denotes the processing status for the verification.
UNKNOWN: The processing status could not be determined.PROCESSING_COMPLETE: The processing has completed and the user has approved for sharing. The data is available to be retrieved.PROCESSING: The verification is still processing. The data is not available yet.FAILED: The processing failed to complete successfully.APPROVAL_STATUS_PENDING: The processing has completed but the user has not yet approved the sharing of the data.Possible values:
UNKNOWN, PROCESSING_COMPLETE, PROCESSING, FAILED, APPROVAL_STATUS_PENDINGupdated_atnullablestring
Timestamp in ISO 8601 format (YYYY-MM-DDTHH:mm:ssZ) indicating the last time that the Item was updated.
Format:
date-time request_idstring
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{2 "items": [3 {4 "item_id": "eVBnVMp7zdTJLkRNr33Rs6zr7KNJqBFL9DrE6",5 "bank_statements": [6 {7 "transactions": [8 {9 "amount": -1000,10 "date": "2023-01-01",11 "original_description": "PAYCHECK",12 "account_id": "c6778d3f-e44c-4348-874e-71507c1ac12d"13 }14 ],15 "document_metadata": {16 "document_type": "BANK_STATEMENT",17 "name": "statement_01.pdf",18 "status": "PROCESSING_COMPLETE",19 "download_url": null,20 "page_count": 221 },22 "document_id": "2jkflanbd",23 "bank_accounts": [24 {25 "name": "CHASE CHECKING",26 "bank_name": "CHASE",27 "account_type": "CHECKING",28 "account_number": "000009752",29 "account_id": "c6778d3f-e44c-4348-874e-71507c1ac12d",30 "owner": {31 "name": "JANE DOE",32 "address": {33 "postal_code": "94133",34 "country": "US",35 "region": "CA",36 "city": "SAN FRANCISCO",37 "street": "2140 TAYLOR ST"38 }39 },40 "periods": [41 {42 "start_date": "2023-01-01",43 "end_date": "2023-02-01",44 "starting_balance": 2500,45 "ending_balance": 350046 }47 ]48 }49 ]50 }51 ],52 "status": {53 "processing_status": "PROCESSING_COMPLETE"54 },55 "updated_at": "2023-02-01T21:14:54Z"56 }57 ],58 "request_id": "LhQf0THi8SH1yJm"59}Was this helpful?
/credit/payroll_income/get
Retrieve a user's payroll information
This endpoint gets payroll income information for a specific user, either as a result of the user connecting to their payroll provider or uploading a pay related document.
credit/payroll_income/getRequest fields and example
client_idstring
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.secretstring
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_tokenstring
The user token associated with the User data is being requested for.
optionsobject
An optional object for
/credit/payroll_income/get request options.item_ids[string]
An array of
item_ids whose payroll information is returned. Each item_id should uniquely identify a payroll income item. If this field is not provided, all item_ids associated with the user_token will returned in the response.1const request: CreditPayrollIncomeGetRequest = {2 user_token: 'user-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d',3};45try {6 const response = await client.creditPayrollIncomeGet(request);7} catch (error) {8 // handle error9}credit/payroll_income/get
Response fields and example
items[object]
Array of payroll items.
item_idstring
The
item_id of the Item associated with this webhook, warning, or errorinstitution_idstring
The unique identifier of the institution associated with the Item.
institution_namestring
The name of the institution associated with the Item.
accounts[object]
account_idnullablestring
ID of the payroll provider account.
rate_of_payobject
An object representing the rate at which an individual is paid.
pay_ratenullablestring
The rate at which an employee is paid.
Possible values:
ANNUAL, HOURLY, CONTRACT, WEEKLY, BI_WEEKLY, MONTHLY, SEMI_MONTHLY, DAILY, COMMISSION, OTHER, nullpay_amountnullablenumber
The amount at which an employee is paid.
Format:
double pay_frequencynullablestring
The frequency at which an individual is paid.
Possible values:
DAILY, WEEKLY, BIWEEKLY, SEMI_MONTHLY, MONTHLY, CONTRACT, QUARTERLY, SEMI_ANNUALLY, ANNUALLY, OTHER, nullpayroll_income[object]
account_idnullablestring
ID of the payroll provider account.
pay_stubs[object]
Array of pay stubs for the user.
deductionsobject
An object with the deduction information found on a pay stub.
breakdown[object]
current_amountnullablenumber
Raw amount of the deduction
Format:
double descriptionnullablestring
Description of the deduction line item
iso_currency_codenullablestring
The ISO-4217 currency code of the line item. Always
null if unofficial_currency_code is non-null.unofficial_currencynullablestring
The unofficial currency code associated with the line item. Always
See the currency code schema for a full listing of supported
null if iso_currency_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.See the currency code schema for a full listing of supported
iso_currency_codes.ytd_amountnullablenumber
The year-to-date amount of the deduction
Format:
double totalobject
An object representing the total deductions for the pay period
current_amountnullablenumber
Raw amount of the deduction
Format:
double iso_currency_codenullablestring
The ISO-4217 currency code of the line item. Always
null if unofficial_currency_code is non-null.unofficial_currencynullablestring
The unofficial currency code associated with the line item. Always
See the currency code schema for a full listing of supported
null if iso_currency_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.See the currency code schema for a full listing of supported
iso_currency_codes.ytd_amountnullablenumber
The year-to-date total amount of the deductions
Format:
double document_idnullablestring
An identifier of the document referenced by the document metadata.
document_metadataobject
Object representing metadata pertaining to the document.
namestring
The name of the document.
document_typenullablestring
The type of document.
PAYSTUB: A paystub.BANK_STATEMENT: A bank statement.US_TAX_W2: A W-2 wage and tax statement provided by a US employer reflecting wages earned by the employee.US_MILITARY_ERAS: An electronic Retirement Account Statement (eRAS) issued by the US military.US_MILITARY_LES: A Leave and Earnings Statement (LES) issued by the US military.US_MILITARY_CLES: A Civilian Leave and Earnings Statment (CLES) issued by the US military.GIG: Used to indicate that the income is related to gig work. Does not necessarily correspond to a specific document type.PLAID_GENERATED_PAYSTUB_PDF: Used to indicate that the PDF for the paystub was generated by Plaid.NONE: Used to indicate that there is no underlying document for the data.UNKNOWN: Document type could not be determined.Possible values:
UNKNOWN, PAYSTUB, BANK_STATEMENT, US_TAX_W2, US_MILITARY_ERAS, US_MILITARY_LES, US_MILITARY_CLES, GIG, PLAID_GENERATED_PAYSTUB_PDF, NONEdownload_urlnullablestring
Signed URL to retrieve the underlying file. For Payroll Income, the file type will always be PDF, and the file may not be available, in which case the field will be
For Document Income, this field will not be
This download URL can only be used once and expires after two minutes. To generate a new download URL, call
null. If you would like Plaid to generate a PDF if the original is not available, contact your Account Manager. Example generated pay stub.For Document Income, this field will not be
null, and the file type will be the original file type uploaded by the user. For more details on available file types, see the Document Income documentation.This download URL can only be used once and expires after two minutes. To generate a new download URL, call
/credit/payroll_income/get again.statusnullablestring
The processing status of the document.
PROCESSING_COMPLETE: The document was successfully processed.DOCUMENT_ERROR: The document could not be processed. Possible causes include: The document was an unacceptable document type such as an offer letter or bank statement, the document image was cropped or blurry, or the document was corrupted.UNKNOWN or null: An internal error occurred. If this happens repeatedly, contact support or your Plaid account manager.Possible values:
UNKNOWN, PROCESSING_COMPLETE, DOCUMENT_ERROR, nullpage_countnullableinteger
The number of pages of the uploaded document (if available).
earningsobject
An object representing both a breakdown of earnings on a pay stub and the total earnings.
breakdown[object]
canonical_descriptionnullablestring
Commonly used term to describe the earning line item.
Possible values:
BONUS, COMMISSION, OVERTIME, PAID_TIME_OFF, REGULAR_PAY, VACATION, BASIC_ALLOWANCE_HOUSING, BASIC_ALLOWANCE_SUBSISTENCE, OTHER, ALLOWANCE, BEREAVEMENT, HOLIDAY_PAY, JURY_DUTY, LEAVE, LONG_TERM_DISABILITY_PAY, MILITARY_PAY, PER_DIEM, REFERRAL_BONUS, REIMBURSEMENTS, RETENTION_BONUS, RETROACTIVE_PAY, SEVERANCE_PAY, SHIFT_DIFFERENTIAL, SHORT_TERM_DISABILITY_PAY, SICK_PAY, SIGNING_BONUS, TIPS_INCOME, nullcurrent_amountnullablenumber
Raw amount of the earning line item.
Format:
double descriptionnullablestring
Description of the earning line item.
hoursnullablenumber
Number of hours applicable for this earning.
iso_currency_codenullablestring
The ISO-4217 currency code of the line item. Always
null if unofficial_currency_code is non-null.ratenullablenumber
Hourly rate applicable for this earning.
Format:
double unofficial_currencynullablestring
The unofficial currency code associated with the line item. Always
See the currency code schema for a full listing of supported
null if iso_currency_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.See the currency code schema for a full listing of supported
iso_currency_codes.ytd_amountnullablenumber
The year-to-date amount of the deduction.
Format:
double totalobject
An object representing both the current pay period and year to date amount for an earning category.
current_amountnullablenumber
Total amount of the earnings for this pay period.
Format:
double hoursnullablenumber
Total number of hours worked for this pay period.
iso_currency_codenullablestring
The ISO-4217 currency code of the line item. Always
null if unofficial_currency_code is non-null.unofficial_currencynullablestring
The unofficial currency code associated with the security. Always
See the currency code schema for a full listing of supported
null if iso_currency_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.See the currency code schema for a full listing of supported
iso_currency_codes.ytd_amountnullablenumber
The total year-to-date amount of the earnings.
Format:
double employeeobject
Data about the employee.
namenullablestring
The name of the employee.
marital_statusnullablestring
Marital status of the employee - either
SINGLE or MARRIED or NOT LISTED.Possible values:
SINGLE, MARRIED, NOT LISTED, nulltaxpayer_idobject
Taxpayer ID of the individual receiving the paystub.
net_payobject
An object representing information about the net pay amount on the pay stub.
current_amountnullablenumber
Raw amount of the net pay for the pay period.
Format:
double descriptionnullablestring
Description of the net pay.
iso_currency_codenullablestring
The ISO-4217 currency code of the net pay. Always
null if unofficial_currency_code is non-null.unofficial_currencynullablestring
The unofficial currency code associated with the net pay. Always
See the currency code schema for a full listing of supported
null if iso_currency_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.See the currency code schema for a full listing of supported
iso_currency_codes.ytd_amountnullablenumber
The year-to-date amount of the net pay.
Format:
double pay_period_detailsobject
Details about the pay period.
pay_amountnullablenumber
The amount of the paycheck.
Format:
double distribution_breakdown[object]
account_namenullablestring
Name of the account for the given distribution.
bank_namenullablestring
The name of the bank that the payment is being deposited to.
current_amountnullablenumber
The amount distributed to this account.
Format:
double iso_currency_codenullablestring
The ISO-4217 currency code of the net pay. Always
null if unofficial_currency_code is non-null.masknullablestring
The last 2-4 alphanumeric characters of an account's official account number.
typenullablestring
Type of the account that the paystub was sent to (e.g. 'checking').
unofficial_currencynullablestring
The unofficial currency code associated with the net pay. Always
See the currency code schema for a full listing of supported
null if iso_currency_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.See the currency code schema for a full listing of supported
iso_currency_codes.gross_earningsnullablenumber
Total earnings before tax/deductions.
Format:
double iso_currency_codenullablestring
The ISO-4217 currency code of the net pay. Always
null if unofficial_currency_code is non-null.pay_frequencynullablestring
The frequency at which an individual is paid.
Possible values:
UNKNOWN, WEEKLY, BIWEEKLY, SEMI_MONTHLY, MONTHLY, nullpay_basisstring
The explicit pay basis on the paystub (if present).
Possible values:
SALARY, HOURLY, COMMISSIONstart_datenullablestring
unofficial_currencynullablestring
The unofficial currency code associated with the net pay. Always
See the currency code schema for a full listing of supported
null if iso_currency_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.See the currency code schema for a full listing of supported
iso_currency_codes.w2s[object]
Array of tax form W-2s.
document_metadataobject
Object representing metadata pertaining to the document.
namestring
The name of the document.
document_typenullablestring
The type of document.
PAYSTUB: A paystub.BANK_STATEMENT: A bank statement.US_TAX_W2: A W-2 wage and tax statement provided by a US employer reflecting wages earned by the employee.US_MILITARY_ERAS: An electronic Retirement Account Statement (eRAS) issued by the US military.US_MILITARY_LES: A Leave and Earnings Statement (LES) issued by the US military.US_MILITARY_CLES: A Civilian Leave and Earnings Statment (CLES) issued by the US military.GIG: Used to indicate that the income is related to gig work. Does not necessarily correspond to a specific document type.PLAID_GENERATED_PAYSTUB_PDF: Used to indicate that the PDF for the paystub was generated by Plaid.NONE: Used to indicate that there is no underlying document for the data.UNKNOWN: Document type could not be determined.Possible values:
UNKNOWN, PAYSTUB, BANK_STATEMENT, US_TAX_W2, US_MILITARY_ERAS, US_MILITARY_LES, US_MILITARY_CLES, GIG, PLAID_GENERATED_PAYSTUB_PDF, NONEdownload_urlnullablestring
Signed URL to retrieve the underlying file. For Payroll Income, the file type will always be PDF, and the file may not be available, in which case the field will be
For Document Income, this field will not be
This download URL can only be used once and expires after two minutes. To generate a new download URL, call
null. If you would like Plaid to generate a PDF if the original is not available, contact your Account Manager. Example generated pay stub.For Document Income, this field will not be
null, and the file type will be the original file type uploaded by the user. For more details on available file types, see the Document Income documentation.This download URL can only be used once and expires after two minutes. To generate a new download URL, call
/credit/payroll_income/get again.statusnullablestring
The processing status of the document.
PROCESSING_COMPLETE: The document was successfully processed.DOCUMENT_ERROR: The document could not be processed. Possible causes include: The document was an unacceptable document type such as an offer letter or bank statement, the document image was cropped or blurry, or the document was corrupted.UNKNOWN or null: An internal error occurred. If this happens repeatedly, contact support or your Plaid account manager.Possible values:
UNKNOWN, PROCESSING_COMPLETE, DOCUMENT_ERROR, nullpage_countnullableinteger
The number of pages of the uploaded document (if available).
document_idstring
An identifier of the document referenced by the document metadata.
employeeobject
Data about the employee.
namenullablestring
The name of the employee.
marital_statusnullablestring
Marital status of the employee - either
SINGLE or MARRIED or NOT LISTED.Possible values:
SINGLE, MARRIED, NOT LISTED, nulltaxpayer_idobject
Taxpayer ID of the individual receiving the paystub.
tax_yearnullablestring
The tax year of the W2 document.
employer_id_numbernullablestring
An employee identification number or EIN.
wages_tips_other_compnullablestring
Wages from tips and other compensation.
federal_income_taxnullablestring
Federal income tax withheld for the tax year.
social_security_wagesnullablestring
Wages from social security.
social_security_taxnullablestring
Social security tax withheld for the tax year.
medicare_wages_andnullablestring
Wages and tips from medicare.
medicare_tax_withheldnullablestring
Medicare tax withheld for the tax year.
social_security_tipsnullablestring
Tips from social security.
allocated_tipsnullablestring
Allocated tips.
box_9nullablestring
Contents from box 9 on the W2.
dependent_carenullablestring
Dependent care benefits.
nonqualified_plansnullablestring
Nonqualified plans.
statutory_employeenullablestring
Statutory employee.
retirement_plannullablestring
Retirement plan.
third_party_sick_paynullablestring
Third party sick pay.
othernullablestring
Other.
state_and_local_wages[object]
statenullablestring
State associated with the wage.
employer_state_idnullablestring
State identification number of the employer.
state_wages_tipsnullablestring
Wages and tips from the specified state.
state_income_taxnullablestring
Income tax from the specified state.
local_wages_tipsnullablestring
Wages and tips from the locality.
local_income_taxnullablestring
Income tax from the locality.
locality_namenullablestring
Name of the locality.
form1099s[object]
Array of tax form 1099s.
document_idnullablestring
An identifier of the document referenced by the document metadata.
document_metadataobject
Object representing metadata pertaining to the document.
namestring
The name of the document.
document_typenullablestring
The type of document.
PAYSTUB: A paystub.BANK_STATEMENT: A bank statement.US_TAX_W2: A W-2 wage and tax statement provided by a US employer reflecting wages earned by the employee.US_MILITARY_ERAS: An electronic Retirement Account Statement (eRAS) issued by the US military.US_MILITARY_LES: A Leave and Earnings Statement (LES) issued by the US military.US_MILITARY_CLES: A Civilian Leave and Earnings Statment (CLES) issued by the US military.GIG: Used to indicate that the income is related to gig work. Does not necessarily correspond to a specific document type.PLAID_GENERATED_PAYSTUB_PDF: Used to indicate that the PDF for the paystub was generated by Plaid.NONE: Used to indicate that there is no underlying document for the data.UNKNOWN: Document type could not be determined.Possible values:
UNKNOWN, PAYSTUB, BANK_STATEMENT, US_TAX_W2, US_MILITARY_ERAS, US_MILITARY_LES, US_MILITARY_CLES, GIG, PLAID_GENERATED_PAYSTUB_PDF, NONEdownload_urlnullablestring
Signed URL to retrieve the underlying file. For Payroll Income, the file type will always be PDF, and the file may not be available, in which case the field will be
For Document Income, this field will not be
This download URL can only be used once and expires after two minutes. To generate a new download URL, call
null. If you would like Plaid to generate a PDF if the original is not available, contact your Account Manager. Example generated pay stub.For Document Income, this field will not be
null, and the file type will be the original file type uploaded by the user. For more details on available file types, see the Document Income documentation.This download URL can only be used once and expires after two minutes. To generate a new download URL, call
/credit/payroll_income/get again.statusnullablestring
The processing status of the document.
PROCESSING_COMPLETE: The document was successfully processed.DOCUMENT_ERROR: The document could not be processed. Possible causes include: The document was an unacceptable document type such as an offer letter or bank statement, the document image was cropped or blurry, or the document was corrupted.UNKNOWN or null: An internal error occurred. If this happens repeatedly, contact support or your Plaid account manager.Possible values:
UNKNOWN, PROCESSING_COMPLETE, DOCUMENT_ERROR, nullpage_countnullableinteger
The number of pages of the uploaded document (if available).
form_1099_typestring
Form 1099 Type
Possible values:
FORM_1099_TYPE_UNKNOWN, FORM_1099_TYPE_MISC, FORM_1099_TYPE_Krecipientobject
An object representing a recipient used in both 1099-K and 1099-MISC tax documents.
namenullablestring
Name of recipient.
tinnullablestring
Tax identification number of recipient.
account_numbernullablestring
Account number number of recipient.
facta_filingnullablestring
Checked if FACTA is a filing requirement.
Possible values:
CHECKED, NOT CHECKEDsecond_tin_existsnullablestring
Checked if 2nd TIN exists.
Possible values:
CHECKED, NOT CHECKEDpayerobject
An object representing a payer used by 1099-MISC tax documents.
namenullablestring
Name of payer.
tinnullablestring
Tax identification number of payer.
telephone_numbernullablestring
Telephone number of payer.
filerobject
An object representing a filer used by 1099-K tax documents.
namenullablestring
Name of filer.
tinnullablestring
Tax identification number of filer.
typenullablestring
One of the following values will be provided: Payment Settlement Entity (PSE), Electronic Payment Facilitator (EPF), Other Third Party
Possible values:
Payment Settlement Entity (PSE), Electronic Payment Facilitator (EPF), Other Third Partytax_yearnullablestring
Tax year of the tax form.
rentsnullablenumber
Amount in rent by payer.
Format:
double royaltiesnullablenumber
Amount in royalties by payer.
Format:
double other_incomenullablenumber
Amount in other income by payer.
Format:
double federal_income_taxnullablenumber
Amount of federal income tax withheld from payer.
Format:
double fishing_boat_proceedsnullablenumber
Amount of fishing boat proceeds from payer.
Format:
double medical_andnullablenumber
Amount of medical and healthcare payments from payer.
Format:
double nonemployeenullablenumber
Amount of nonemployee compensation from payer.
Format:
double substitute_paymentsnullablenumber
Amount of substitute payments made by payer.
Format:
double payer_made_directnullablestring
Whether or not payer made direct sales over $5000 of consumer products.
crop_insurancenullablenumber
Amount of crop insurance proceeds.
Format:
double excess_goldennullablenumber
Amount of golden parachute payments made by payer.
Format:
double gross_proceeds_paidnullablenumber
Amount of gross proceeds paid to an attorney by payer.
Format:
double section_409a_deferralsnullablenumber
Amount of 409A deferrals earned by payer.
Format:
double section_409a_incomenullablenumber
Amount of 409A income earned by payer.
Format:
double state_tax_withheldnullablenumber
Amount of state tax withheld of payer for primary state.
Format:
double state_tax_withheldnullablenumber
Amount of state tax withheld of payer for secondary state.
Format:
double payer_state_numbernullablestring
Primary state ID.
payer_state_numbernullablestring
Secondary state ID.
state_incomenullablenumber
State income reported for primary state.
Format:
double state_income_lowernullablenumber
State income reported for secondary state.
Format:
double transactions_reportednullablestring
One of the values will be provided Payment card Third party network
Possible values:
Payment card, Third party networkpse_namenullablestring
Name of the PSE (Payment Settlement Entity).
pse_telephone_numbernullablestring
Formatted (XXX) XXX-XXXX. Phone number of the PSE (Payment Settlement Entity).
gross_amountnullablenumber
Gross amount reported.
Format:
double card_not_presentnullablenumber
Amount in card not present transactions.
Format:
double merchant_category_codenullablestring
Merchant category of filer.
number_of_paymentnullablestring
Number of payment transactions made.
january_amountnullablenumber
Amount reported for January.
Format:
double february_amountnullablenumber
Amount reported for February.
Format:
double march_amountnullablenumber
Amount reported for March.
Format:
double april_amountnullablenumber
Amount reported for April.
Format:
double may_amountnullablenumber
Amount reported for May.
Format:
double june_amountnullablenumber
Amount reported for June.
Format:
double july_amountnullablenumber
Amount reported for July.
Format:
double august_amountnullablenumber
Amount reported for August.
Format:
double september_amountnullablenumber
Amount reported for September.
Format:
double october_amountnullablenumber
Amount reported for October.
Format:
double november_amountnullablenumber
Amount reported for November.
Format:
double december_amountnullablenumber
Amount reported for December.
Format:
double primary_statenullablestring
Primary state of business.
secondary_statenullablestring
Secondary state of business.
primary_state_idnullablestring
Primary state ID.
secondary_state_idnullablestring
Secondary state ID.
primary_state_incomenullablenumber
State income tax reported for primary state.
Format:
double secondary_statenullablenumber
State income tax reported for secondary state.
Format:
double statusnullableobject
Details about the status of the payroll item.
processing_statusnullablestring
Denotes the processing status for the verification.
UNKNOWN: The processing status could not be determined.PROCESSING_COMPLETE: The processing has completed and the user has approved for sharing. The data is available to be retrieved.PROCESSING: The verification is still processing. The data is not available yet.FAILED: The processing failed to complete successfully.APPROVAL_STATUS_PENDING: The processing has completed but the user has not yet approved the sharing of the data.Possible values:
UNKNOWN, PROCESSING_COMPLETE, PROCESSING, FAILED, APPROVAL_STATUS_PENDINGupdated_atnullablestring
Timestamp in ISO 8601 format (YYYY-MM-DDTHH:mm:ssZ) indicating the last time that the Item was updated.
Format:
date-time errornullableobject
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. 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_typestring
A broad categorization of the error. Safe for programmatic use.
Possible values:
INVALID_REQUEST, INVALID_RESULT, INVALID_INPUT, INSTITUTION_ERROR, RATE_LIMIT_EXCEEDED, API_ERROR, ITEM_ERROR, ASSET_REPORT_ERROR, RECAPTCHA_ERROR, OAUTH_ERROR, PAYMENT_ERROR, BANK_TRANSFER_ERROR, INCOME_VERIFICATION_ERROR, MICRODEPOSITS_ERRORerror_codestring
The particular error code. Safe for programmatic use.
error_messagestring
A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use.
display_messagenullablestring
A user-friendly representation of the error code.
This may change over time and is not safe for programmatic use.
null if the error is not related to user action.This may change over time and is not safe for programmatic use.
request_idstring
A unique ID identifying the request, to be used for troubleshooting purposes. This field will be omitted in errors provided by webhooks.
causesarray
In the Assets product, a request can pertain to more than one Item. If an error is returned for such a request,
causes will return an array of errors containing a breakdown of these errors on the individual Item level, if any can be identified.causes will only be provided for the error_type ASSET_REPORT_ERROR. causes will also not be populated inside an error nested within a warning object.statusnullableinteger
The HTTP status code associated with the error. This will only be returned in the response body when the error information is provided via a webhook.
documentation_urlstring
The URL of a Plaid documentation page with more information about the error
suggested_actionnullablestring
Suggested steps for resolving the error
request_idstring
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{2 "items": [3 {4 "item_id": "eVBnVMp7zdTJLkRNr33Rs6zr7KNJqBFL9DrE6",5 "institution_id": "ins_92",6 "institution_name": "ADP",7 "accounts": [8 {9 "account_id": "GeooLPBGDEunl54q7N3ZcyD5aLPLEai1nkzM9",10 "rate_of_pay": {11 "pay_amount": 100000,12 "pay_rate": "ANNUAL"13 },14 "pay_frequency": "BIWEEKLY"15 }16 ],17 "payroll_income": [18 {19 "account_id": "GeooLPBGDEunl54q7N3ZcyD5aLPLEai1nkzM9",20 "pay_stubs": [21 {22 "deductions": {23 "breakdown": [24 {25 "current_amount": 123.45,26 "description": "taxes",27 "iso_currency_code": "USD",28 "unofficial_currency_code": null,29 "ytd_amount": 246.930 }31 ],32 "total": {33 "current_amount": 123.45,34 "iso_currency_code": "USD",35 "unofficial_currency_code": null,36 "ytd_amount": 246.937 }38 },39 "document_metadata": {40 "document_type": "PAYSTUB",41 "name": "paystub.pdf",42 "status": "PROCESSING_COMPLETE",43 "download_url": null44 },45 "document_id": "2jkflanbd",46 "earnings": {47 "breakdown": [48 {49 "canonical_description": "REGULAR_PAY",50 "current_amount": 200.22,51 "description": "salary earned",52 "hours": 80,53 "iso_currency_code": "USD",54 "rate": null,55 "unofficial_currency_code": null,56 "ytd_amount": 400.4457 },58 {59 "canonical_description": "BONUS",60 "current_amount": 100,61 "description": "bonus earned",62 "hours": null,63 "iso_currency_code": "USD",64 "rate": null,65 "unofficial_currency_code": null,66 "ytd_amount": 10067 }68 ],69 "total": {70 "current_amount": 300.22,71 "hours": 160,72 "iso_currency_code": "USD",73 "unofficial_currency_code": null,74 "ytd_amount": 500.4475 }76 },77 "employee": {78 "address": {79 "city": "SAN FRANCISCO",80 "country": "US",81 "postal_code": "94133",82 "region": "CA",83 "street": "2140 TAYLOR ST"84 },85 "name": "ANNA CHARLESTON",86 "marital_status": "SINGLE",87 "taxpayer_id": {88 "id_type": "SSN",89 "id_mask": "3333"90 }91 },92 "employer": {93 "name": "PLAID INC",94 "address": {95 "city": "SAN FRANCISCO",96 "country": "US",97 "postal_code": "94111",98 "region": "CA",99 "street": "1098 HARRISON ST"100 }101 },102 "net_pay": {103 "current_amount": 123.34,104 "description": "TOTAL NET PAY",105 "iso_currency_code": "USD",106 "unofficial_currency_code": null,107 "ytd_amount": 253.54108 },109 "pay_period_details": {110 "distribution_breakdown": [111 {112 "account_name": "Big time checking",113 "bank_name": "bank of plaid",114 "current_amount": 176.77,115 "iso_currency_code": "USD",116 "mask": "1223",117 "type": "checking",118 "unofficial_currency_code": null119 }120 ],121 "end_date": "2020-12-15",122 "gross_earnings": 4500,123 "iso_currency_code": "USD",124 "pay_amount": 1490.21,125 "pay_date": "2020-12-15",126 "pay_frequency": "BIWEEKLY",127 "start_date": "2020-12-01",128 "unofficial_currency_code": null129 }130 }131 ],132 "w2s": [133 {134 "allocated_tips": "1000",135 "box_12": [136 {137 "amount": "200",138 "code": "AA"139 }140 ],141 "box_9": "box9",142 "dependent_care_benefits": "1000",143 "document_metadata": {144 "document_type": "US_TAX_W2",145 "download_url": null,146 "name": "w_2.pdf",147 "status": "PROCESSING_COMPLETE"148 },149 "document_id": "1pkflebk4",150 "employee": {151 "address": {152 "city": "San Francisco",153 "country": "US",154 "postal_code": "94103",155 "region": "CA",156 "street": "1234 Grand St"157 },158 "name": "Josie Georgia Harrison",159 "marital_status": "SINGLE",160 "taxpayer_id": {161 "id_type": "SSN",162 "id_mask": "1234"163 }164 },165 "employer": {166 "address": {167 "city": "New York",168 "country": "US",169 "postal_code": "10010",170 "region": "NY",171 "street": "456 Main St"172 },173 "name": "Acme Inc"174 },175 "employer_id_number": "12-1234567",176 "federal_income_tax_withheld": "1000",177 "medicare_tax_withheld": "1000",178 "medicare_wages_and_tips": "1000",179 "nonqualified_plans": "1000",180 "other": "other",181 "retirement_plan": "CHECKED",182 "social_security_tax_withheld": "1000",183 "social_security_tips": "1000",184 "social_security_wages": "1000",185 "state_and_local_wages": [186 {187 "employer_state_id_number": "11111111111AAA",188 "local_income_tax": "200",189 "local_wages_and_tips": "200",190 "locality_name": "local",191 "state": "UT",192 "state_income_tax": "200",193 "state_wages_tips": "200"194 }195 ],196 "statutory_employee": "CHECKED",197 "tax_year": "2020",198 "third_party_sick_pay": "CHECKED",199 "wages_tips_other_comp": "1000"200 }201 ],202 "form1099s": [203 {204 "april_amount": null,205 "august_amount": null,206 "card_not_present_transaction": null,207 "crop_insurance_proceeds": 1000,208 "december_amount": null,209 "document_id": "mvMZ59Z2a5",210 "document_metadata": {211 "document_type": "US_TAX_1099_MISC",212 "download_url": null,213 "name": "form_1099_misc.pdf",214 "status": "PROCESSING_COMPLETE"215 },216 "excess_golden_parachute_payments": 1000,217 "feburary_amount": null,218 "federal_income_tax_withheld": 1000,219 "filer": {220 "address": {221 "city": null,222 "country": null,223 "postal_code": null,224 "region": null,225 "street": null226 },227 "name": null,228 "tin": null,229 "type": null230 },231 "fishing_boat_proceeds": 1000,232 "form_1099_type": "FORM_1099_TYPE_MISC",233 "gross_amount": 1000,234 "gross_proceeds_paid_to_an_attorney": 1000,235 "january_amount": null,236 "july_amount": null,237 "june_amount": null,238 "march_amount": null,239 "may_amount": null,240 "medical_and_healthcare_payments": 1000,241 "merchant_category_code": null,242 "nonemployee_compensation": 1000,243 "november_amount": null,244 "number_of_payment_transactions": null,245 "october_amount": null,246 "other_income": 1000,247 "payer": {248 "address": {249 "city": "SAN FRANCISCO",250 "country": "US",251 "postal_code": "94111",252 "region": "CA",253 "street": "1098 HARRISON ST"254 },255 "name": "PLAID INC",256 "telephone_number": "(123)456-7890",257 "tin": "12-3456789"258 },259 "payer_made_direct_sales_of_500_or_more_of_consumer_products_to_buyer": null,260 "payer_state_number": "CA 12345",261 "payer_state_number_lower": null,262 "primary_state": null,263 "primary_state_id": "CA 12345",264 "primary_state_income_tax": 1000,265 "pse_name": null,266 "pse_telephone_number": null,267 "recipient": {268 "account_number": "45678",269 "address": {270 "city": "SAN FRANCISCO",271 "country": "US",272 "postal_code": "94133",273 "region": "CA",274 "street": "2140 TAYLOR ST"275 },276 "facta_filing_requirement": "CHECKED",277 "name": "Josie Georgia Harrison",278 "second_tin_exists": "NOT CHECKED",279 "tin": "12-3456789"280 },281 "rents": 1000,282 "royalties": 1000,283 "secondary_state": null,284 "secondary_state_id": null,285 "secondary_state_income_tax": null,286 "section_409a_deferrals": 1000,287 "section_409a_income": 1000,288 "september_amount": null,289 "state_income": 1000,290 "state_income_lower": null,291 "state_tax_withheld": 1000,292 "state_tax_withheld_lower": null,293 "substitute_payments_in_lieu_of_dividends_or_interest": null,294 "tax_year": "2022",295 "transactions_reported": null296 }297 ]298 }299 ],300 "status": {301 "processing_status": "PROCESSING_COMPLETE"302 },303 "updated_at": "2022-08-02T21:14:54Z"304 }305 ],306 "request_id": "2pxQ59buGdsHRef"307}Was this helpful?
/credit/payroll_income/risk_signals/get
Retrieve fraud insights for a user's manually uploaded document(s).
/credit/payroll_income/risk_signals/get can be used as part of the Document Income flow to assess a user-uploaded document for signs of potential fraud or tampering. It returns a risk score for each uploaded document that indicates the likelihood of the document being fraudulent, in addition to details on the individual risk signals contributing to the score.
To trigger risk signal generation for an Item, call /link/token/create with parsing_config set to include risk_signals, or call /credit/payroll_income/parsing_config/update. Once risk signal generation has been triggered, /credit/payroll_income/risk_signals/get can be called at any time after the INCOME_VERIFICATION_RISK_SIGNALS webhook has been fired./credit/payroll_income/risk_signals/get is offered as an add-on to Document Income and is billed separately. To request access to this endpoint, submit a product access request or contact your Plaid account manager.
Request fields and example
client_idstring
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.secretstring
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_tokenstring
The user token associated with the User data is being requested for.
1const request: CreditPayrollIncomeRiskSignalsGetRequest = {2 user_token: 'user-sandbox-dd4c42bd-4a81-4089-8146-40671e81dd12',3};4try {5 const response = await client.creditPayrollIncomeRiskSignalsGet(request);6} catch (error) {7 // handle error8}credit/payroll_income/risk_signals/get
Response fields and example
items[object]
Array of payroll items.
item_idstring
The
item_id of the Item associated with this webhook, warning, or errorverification_risk[object]
Array of payroll income document authenticity data retrieved for each of the user's accounts.
account_idnullablestring
ID of the payroll provider account.
single_document_risk[object]
Array of document metadata and associated risk signals per document
document_referenceobject
Object containing metadata for the document
document_idnullablestring
An identifier of the document referenced by the document metadata.
document_namestring
The name of the document
statusstring
Status of a document for risk signal analysis
Possible values:
PROCESSING, PROCESSING_COMPLETE, PROCESSING_ERROR, PASSWORD_PROTECTED, VIRUS_DETECTEDrisk_signals[object]
Array of attributes that indicate whether or not there is fraud risk with a document
typenullablestring
The result from the risk signal check.
Possible values:
FONT, MASKING, OVERLAID_TEXT, EDITED_TEXT, TEXT_COMPRESSION, ADDRESS_FORMAT_ANOMALY, DATE_FORMAT_ANOMALY, FONT_ANOMALY, NAME_FORMAT_ANOMALY, PDF_ALIGNMENT, BRUSH_DETECTION, METADATA_DATES_OUTSIDE_WINDOW, METADATA_DATES_INSIDE_WINDOW, METADATA_DATES_MISSING, METADATA_DATES_MATCH, ADOBE_FONTS, ANNOTATION_DATES, ANNOTATIONS, EDITED_WHILE_SCANNED, EXIF_DATA_MODIFIED, HIGH_USER_ACCESS, MALFORMED_DATE, QPDF, TEXT_LAYER_TEXT, TOUCHUP_TEXT, FLATTENED_PDF, BLACKLISTS, COPYCAT_IMAGE, COPYCAT_TEXT, REJECTED_CUSTOMER, TEMPLATES, SOFTWARE_BLACKLISTfieldnullablestring
The field which the risk signal was computed for
has_fraud_risknullableboolean
A flag used to quickly identify if the signal indicates that this field is authentic or fraudulent
institution_metadatanullableobject
An object which contains additional metadata about the institution used to compute the verification attribute
item_idstring
The
item_id of the Item associated with this webhook, warning, or errorexpected_valuenullablestring
The expected value of the field, as seen on the document
actual_valuenullablestring
The derived value obtained in the risk signal calculation process for this field
signal_descriptionnullablestring
A human-readable explanation providing more detail into the particular risk signal
page_numbernullableinteger
The relevant page associated with the risk signal
risk_summaryobject
A summary across all risk signals associated with a document
risk_scorenullablenumber
A number between 0 and 100, inclusive, where a score closer to 0 indicates a document is likely to be trustworthy and a score closer to 100 indicates a document is likely to be fraudulent
multi_document_risk[object]
Array of risk signals computed from a set of uploaded documents and the associated documents' metadata
document_references[object]
Array of objects containing attributes that could indicate if a document is fraudulent
document_idnullablestring
An identifier of the document referenced by the document metadata.
document_namestring
The name of the document
statusstring
Status of a document for risk signal analysis
Possible values:
PROCESSING, PROCESSING_COMPLETE, PROCESSING_ERROR, PASSWORD_PROTECTED, VIRUS_DETECTEDrisk_signals[object]
Array of attributes that indicate whether or not there is fraud risk with a set of documents
typenullablestring
The result from the risk signal check.
Possible values:
FONT, MASKING, OVERLAID_TEXT, EDITED_TEXT, TEXT_COMPRESSION, ADDRESS_FORMAT_ANOMALY, DATE_FORMAT_ANOMALY, FONT_ANOMALY, NAME_FORMAT_ANOMALY, PDF_ALIGNMENT, BRUSH_DETECTION, METADATA_DATES_OUTSIDE_WINDOW, METADATA_DATES_INSIDE_WINDOW, METADATA_DATES_MISSING, METADATA_DATES_MATCH, ADOBE_FONTS, ANNOTATION_DATES, ANNOTATIONS, EDITED_WHILE_SCANNED, EXIF_DATA_MODIFIED, HIGH_USER_ACCESS, MALFORMED_DATE, QPDF, TEXT_LAYER_TEXT, TOUCHUP_TEXT, FLATTENED_PDF, BLACKLISTS, COPYCAT_IMAGE, COPYCAT_TEXT, REJECTED_CUSTOMER, TEMPLATES, SOFTWARE_BLACKLISTfieldnullablestring
The field which the risk signal was computed for
has_fraud_risknullableboolean
A flag used to quickly identify if the signal indicates that this field is authentic or fraudulent
institution_metadatanullableobject
An object which contains additional metadata about the institution used to compute the verification attribute
item_idstring
The
item_id of the Item associated with this webhook, warning, or errorexpected_valuenullablestring
The expected value of the field, as seen on the document
actual_valuenullablestring
The derived value obtained in the risk signal calculation process for this field
signal_descriptionnullablestring
A human-readable explanation providing more detail into the particular risk signal
page_numbernullableinteger
The relevant page associated with the risk signal
errornullableobject
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. 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_typestring
A broad categorization of the error. Safe for programmatic use.
Possible values:
INVALID_REQUEST, INVALID_RESULT, INVALID_INPUT, INSTITUTION_ERROR, RATE_LIMIT_EXCEEDED, API_ERROR, ITEM_ERROR, ASSET_REPORT_ERROR, RECAPTCHA_ERROR, OAUTH_ERROR, PAYMENT_ERROR, BANK_TRANSFER_ERROR, INCOME_VERIFICATION_ERROR, MICRODEPOSITS_ERRORerror_codestring
The particular error code. Safe for programmatic use.
error_messagestring
A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use.
display_messagenullablestring
A user-friendly representation of the error code.
This may change over time and is not safe for programmatic use.
null if the error is not related to user action.This may change over time and is not safe for programmatic use.
request_idstring
A unique ID identifying the request, to be used for troubleshooting purposes. This field will be omitted in errors provided by webhooks.
causesarray
In the Assets product, a request can pertain to more than one Item. If an error is returned for such a request,
causes will return an array of errors containing a breakdown of these errors on the individual Item level, if any can be identified.causes will only be provided for the error_type ASSET_REPORT_ERROR. causes will also not be populated inside an error nested within a warning object.statusnullableinteger
The HTTP status code associated with the error. This will only be returned in the response body when the error information is provided via a webhook.
documentation_urlstring
The URL of a Plaid documentation page with more information about the error
suggested_actionnullablestring
Suggested steps for resolving the error
request_idstring
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{2 "items": [3 {4 "item_id": "testItemID",5 "verification_risk_signals": [6 {7 "account_id": null,8 "multi_document_risk_signals": [],9 "single_document_risk_signals": [10 {11 "document_reference": {12 "document_id": "lRepoQjxlJ1nz",13 "document_name": "Paystub.pdf"14 },15 "risk_summary": {16 "risk_score": 7017 },18 "risk_signals": [19 {20 "actual_value": "0.00",21 "expected_value": "25.09",22 "field": null,23 "signal_description": null,24 "has_fraud_risk": true,25 "type": "MASKING",26 "page_number": 1,27 "institution_metadata": {28 "item_id": "testItemID"29 }30 },31 {32 "actual_value": null,33 "expected_value": null,34 "field": null,35 "signal_description": "Creation date and modification date do not match",36 "has_fraud_risk": true,37 "institution_metadata": null,38 "type": "METADATA_DATES_OUTSIDE_WINDOW",39 "page_number": 040 }41 ]42 }43 ]44 }45 ]46 }47 ],48 "request_id": "LhQf0THi8SH1yJm"49}Was this helpful?
/credit/employment/get
Retrieve a summary of an individual's employment information
/credit/employment/get returns a list of items with employment information from a user's payroll provider that was verified by an end user.
Request fields and example
client_idstring
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.secretstring
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_tokenrequiredstring
The user token associated with the User data is being requested for.
1const request: CreditEmploymentGetRequest = {2 user_token: 'user-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d',3};45try {6 const response = await client.creditEmploymentGet(request);7} catch (error) {8 // handle error9}credit/employment/get
Response fields and example
items[object]
Array of employment items.
item_idstring
The
item_id of the Item associated with this webhook, warning, or erroremployments[object]
account_idnullablestring
ID of the payroll provider account.
statusnullablestring
Current employment status.
Possible values:
ACTIVE, INACTIVE, nullstart_datenullablestring
Start of employment in ISO 8601 format (YYYY-MM-DD).
Format:
date end_datenullablestring
End of employment, if applicable. Provided in ISO 8601 format (YYY-MM-DD).
Format:
date titlenullablestring
Current title of employee.
platform_idsobject
The object containing a set of ids related to an employee.
employee_idnullablestring
The ID of an employee as given by their employer.
payroll_idnullablestring
The ID of an employee as given by their payroll.
position_idnullablestring
The ID of the position of the employee.
employee_typenullablestring
The type of employment for the individual.
"FULL_TIME": A full-time employee.
"PART_TIME": A part-time employee.
"CONTRACTOR": An employee typically hired externally through a contracting group.
"TEMPORARY": A temporary employee.
"OTHER": The employee type is not one of the above defined types.Possible values:
FULL_TIME, PART_TIME, CONTRACTOR, TEMPORARY, OTHER, nulllast_paystub_datenullablestring
The date of the employee's most recent paystub in ISO 8601 format (YYYY-MM-DD).
Format:
date request_idstring
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{2 "items": [3 {4 "item_id": "eVBnVMp7zdTJLkRNr33Rs6zr7KNJqBFL9DrE6",5 "employments": [6 {7 "account_id": "GeooLPBGDEunl54q7N3ZcyD5aLPLEai1nkzM9",8 "status": "ACTIVE",9 "start_date": "2020-01-01",10 "end_date": null,11 "employer": {12 "name": "Plaid Inc"13 },14 "title": "Software Engineer",15 "platform_ids": {16 "employee_id": "1234567",17 "position_id": "8888",18 "payroll_id": "1234567"19 },20 "employee_type": "FULL_TIME",21 "last_paystub_date": "2022-01-15"22 }23 ]24 }25 ],26 "request_id": "LhQf0THi8SH1yJm"27}Was this helpful?
/credit/payroll_income/parsing_config/update
Update the parsing configuration for a document income verification
/credit/payroll_income/parsing_config/update updates the parsing configuration for a document income verification.
Request fields and example
client_idstring
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.secretstring
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_tokenrequiredstring
The user token associated with the User data is being requested for.
item_idstring
The
item_id of the Item associated with this webhook, warning, or errorparsing_configrequired[string]
The types of analysis to enable for the document income verification session
Possible values:
ocr, risk_signals1const request: CreditPayrollIncomeParsingConfigUpdateRequest = {2 user_token: 'user-sandbox-dd4c42bd-4a81-4089-8146-40671e81dd12',3 parsing_config: ['fraud_risk'],4};5try {6 const response = await client.creditPayrollIncomeParsingConfigUpdate(request);7} catch (error) {8 // handle error9}credit/payroll_income/parsing_config/update
Response fields and example
request_idstring
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{2 "request_id": "LhQf0THi8SH1yJm"3}Was this helpful?
/credit/payroll_income/refresh
Refresh a digital payroll income verification
/credit/payroll_income/refresh refreshes a given digital payroll income verification.
Request fields and example
client_idstring
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.secretstring
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_tokenrequiredstring
The user token associated with the User data is being requested for.
optionsobject
An optional object for
/credit/payroll_income/refresh request options.1const request: PayrollIncomeRefreshRequest = {2 client_user_id: 'c0e2c4ee-b763-4af5-cfe9-46a46bce883d',3};45try {6 const response = await client.userCreate(request);7} catch (error) {8 // handle error9}credit/payroll_income/refresh
Response fields and example
request_idstring
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
verification_refreshstring
The verification refresh status. One of the following:
"USER_PRESENCE_REQUIRED" User presence is required to refresh an income verification.
"SUCCESSFUL" The income verification refresh was successful.
"NOT_FOUND" No new data was found after the income verification refresh.Possible values:
USER_PRESENCE_REQUIRED, SUCCESSFUL, NOT_FOUND1{2 "request_id": "nTkbCH41HYmpbm5",3 "verification_refresh_status": "USER_PRESENCE_REQUIRED"4}Was this helpful?
Webhooks
Income webhooks are sent to indicate when an income verification or document fraud risk evaluation has finished processing.
INCOME_VERIFICATION
Fired when the status of an income verification instance has changed. It will typically take several minutes for this webhook to fire after the end user has uploaded their documents in the Document Income flow.
webhook_typestring
"INCOME"webhook_codestring
INCOME_VERIFICATIONitem_idstring
The Item ID associated with the verification.
user_idstring
The Plaid
user_id of the User associated with this webhook, warning, or error.verification_statusstring
VERIFICATION_STATUS_PROCESSING_COMPLETE: The income verification processing has completed. This indicates that the documents have been parsed successfully or that the documents were not parsable. If the user uploaded multiple documents, this webhook will fire when all documents have finished processing. Call the /credit/payroll_income/get endpoint and check the document metadata to see which documents were successfully parsed.VERIFICATION_STATUS_PROCESSING_FAILED: An unexpected internal error occurred when attempting to process the verification documentation.VERIFICATION_STATUS_PENDING_APPROVAL: (deprecated) The income verification has been sent to the user for review.environmentstring
The Plaid environment the webhook was sent from
Possible values:
development, sandbox, production1{2 "webhook_type": "INCOME",3 "webhook_code": "INCOME_VERIFICATION",4 "item_id": "gAXlMgVEw5uEGoQnnXZ6tn9E7Mn3LBc4PJVKZ",5 "user_id": "9eaba3c2fdc916bc197f279185b986607dd21682a5b04eab04a5a03e8b3f3334",6 "verification_status": "VERIFICATION_STATUS_PROCESSING_COMPLETE",7 "environment": "production"8}Was this helpful?
INCOME_VERIFICATION_RISK_SIGNALS
Fired when risk signals have been processed for documents uploaded via Document Income. It will typically take a minute or two for this webhook to fire after the end user has uploaded their documents in the Document Income flow. Once this webhook has fired, /credit/payroll_income/risk_signals/get may then be called to determine whether the documents were successfully processed and to retrieve risk data.
webhook_typestring
"INCOME"webhook_codestring
INCOME_VERIFICATION_RISK_SIGNALSitem_idstring
The Item ID associated with the verification.
user_idstring
The Plaid
user_id of the User associated with this webhook, warning, or error.risk_signals_statusstring
RISK_SIGNALS_PROCESSING_COMPLETE: The income verification fraud detection processing has completed. If the user uploaded multiple documents, this webhook will fire when all documents have finished processing. Call the /credit/payroll_income/risk_signals/get endpoint to get all risk signal data.environmentstring
The Plaid environment the webhook was sent from
Possible values:
development, sandbox, production1{2 "webhook_type": "INCOME",3 "webhook_code": "INCOME_VERIFICATION_RISK_SIGNALS",4 "item_id": "gAXlMgVEw5uEGoQnnXZ6tn9E7Mn3LBc4PJVKZ",5 "user_id": "9eaba3c2fdc916bc197f279185b986607dd21682a5b04eab04a5a03e8b3f3334",6 "status": "RISK_SIGNALS_PROCESSING_COMPLETE",7 "environment": "production"8}Was this helpful?
BANK_INCOME_REFRESH_UPDATE
Fired when a change to the user's income is detected. You should call /credit/bank_income/refresh to get updated income data for the user. To receive this webhook, subscribe in the Dashboard.
webhook_typestring
INCOMEwebhook_codestring
BANK_INCOME_REFRESH_UPDATEuser_idstring
The
user_id corresponding to the user the webhook has fired for.environmentstring
The Plaid environment the webhook was sent from
Possible values:
development, sandbox, production1{2 "webhook_type": "INCOME",3 "webhook_code": "BANK_INCOME_REFRESH_UPDATE",4 "user_id": "wz666MBjYWTp2PDzzggYhM6oWWmBb",5 "environment": "production"6}Was this helpful?
BANK_INCOME_REFRESH_COMPLETE
Fired when a refreshed bank income report has finished generating or failed to generate, triggered by calling /credit/bank_income/refresh. To get this webhook, subscribe via the Dashboard.
webhook_typestring
INCOMEwebhook_codestring
BANK_INCOME_REFRESH_COMPLETEuser_idstring
The
user_id corresponding to the user the webhook has fired for.resultstring
The result of the bank income refresh report generation
SUCCESS: The refreshed report was successfully generated and can be retrieved via /credit/bank_income/get.FAILURE: The refreshed report failed to be generatedPossible values:
SUCCESS, FAILUREenvironmentstring
The Plaid environment the webhook was sent from
Possible values:
development, sandbox, production1{2 "webhook_type": "INCOME",3 "webhook_code": "BANK_INCOME_REFRESH_COMPLETE",4 "user_id": "wz666MBjYWTp2PDzzggYhM6oWWmBb",5 "result": "SUCCESS",6 "environment": "production"7}Was this helpful?
INCOME_VERIFICATION_REFRESH_RECONNECT_NEEDED
Fired when the attempt to refresh Payroll Income data for a user via /credit/payroll_income/refresh failed because the user must re-connect their payroll account.
webhook_typestring
INCOMEwebhook_codestring
INCOME_VERIFICATION_REFRESH_RECONNECT_NEEDEDuser_idstring
The
user_id corresponding to the user the webhook has fired for.environmentstring
The Plaid environment the webhook was sent from
Possible values:
development, sandbox, production1{2 "webhook_type": "INCOME",3 "webhook_code": "INCOME_VERIFICATION_REFRESH_RECONNECT_NEEDED",4 "user_id": "wz666MBjYWTp2PDzzggYhM6oWWmBb",5 "environment": "production"6}