Income

API reference for Income endpoints and webhooks

Verify a user's income via payroll or bank account data.

Endpoints
/credit/bank_income/getRetrieve information from the bank accounts used for income verification
/credit/payroll_income/getRetrieve information from the pay stubs or tax forms used for income verification
/credit/payroll_income/precheckCheck digital income verification eligibility and optimize conversion
/credit/employment/get(Beta) Retrieve employment information about the end user
/user/createCreate a user for use with the income verification product
/income/verification/precheck(Deprecated) Check a user's eligibility for the income verification product
/income/verification/paystubs/get(Deprecated) Retrieve the information collected from the paystubs that were used to verify an end user's income
/income/verification/documents/download(Deprecated) Download a ZIP file containing the original documents used for income verification
/income/verification/taxforms/get(Deprecated) Retrieve the information from taxforms associated with the verification
/employment/verification/get(Deprecated) Retrieve employment information about the end user
See also
/sandbox/income/fire_webhookManually fire an Income webhook (Sandbox only)
Webhooks
INCOME_VERIFICATIONWebhook to notify that income verification has completed

Endpoints

/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.

credit/bank_income/get

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 
1// Sample code coming soon
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.
masknullable string
The last 2-4 alphanumeric characters of an account's official account number. Note that the mask may be non-unique between an Item's accounts, and it may also not match the mask that the bank displays to the user.
namestring
The name of the bank account.
official_namenullable string
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, all
typestring
The account type. This will always be depository.

Possible values: depository
owners[object]
names[string]
A list of names associated with the account by the financial institution. These should always be the names of individuals, even for business accounts. If the name of a business is reported, please contact Plaid Support. In the case of a joint account, Plaid will make a best effort to report the names of all account holders.
If an Item contains multiple accounts with different owner names, some institutions will report all names associated with the Item in each account's names array.
phone_numbers[object]
A list of phone numbers associated with the account by the financial institution. May be an empty array if no relevant information is returned from the financial institution.
datastring
The phone number.
primaryboolean
When true, identifies the phone number as the primary number on an account.
typestring
The type of phone number.

Possible values: home, work, office, mobile, mobile1, other
emails[object]
A list of email addresses associated with the account by the financial institution. May be an empty array if no relevant information is returned from the financial institution.
datastring
The email address.
primaryboolean
When true, identifies the email address as the primary email on an account.
typestring
The type of email account as described by the financial institution.

Possible values: primary, secondary, other
addresses[object]
Data about the various addresses associated with the account by the financial institution. May be an empty array if no relevant information is returned from the financial institution.
dataobject
Data about the components comprising an address.
citystring
The full city name
regionnullable string
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_codenullable string
The postal code. In API versions 2018-05-22 and earlier, this field is called zip.
countrynullable string
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.

Possible values: SALARY, UNEMPLOYMENT, CASH, GIG_ECONOMY, RENTAL, CHILD_SUPPORT, MILITARY, RETIREMENT, LONG_TERM_DISABILITY, BANK_INTEREST, OTHER
account_idstring
Plaid's unique idenfier 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, UNKNOWN
total_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_amountnumber
Total amount of earnings for the income source(s) of the user for the month in the summary.
iso_currency_codenullable string
The ISO 4217 currency code of the amount or balance.
unofficial_currency_codenullable string
The unofficial currency code associated with the amount or balance. Always null if iso_currency_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.
start_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 account'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_descriptionnullable string
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_numbernullable string
The check number of the transaction. This field is only populated for check transactions.
iso_currency_codenullable string
The ISO 4217 currency code of the amount or balance.
unofficial_currency_codenullable string
The unofficial currency code associated with the amount or balance. Always null if iso_currency_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.
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_amountnumber
Total amount of earnings across all the income sources in the end user's Items for the days requested by the client.
iso_currency_codenullable string
The ISO 4217 currency code of the amount or balance.
unofficial_currency_codenullable string
The unofficial currency code associated with the amount or balance. Always null if iso_currency_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.
start_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_categories_countinteger
Number of income categories per end user.
income_transactions_countinteger
Number of income transactions per end user.
historical_summary[object]
total_amountnumber
Total amount of earnings for the income source(s) of the user for the month in the summary.
iso_currency_codenullable string
The ISO 4217 currency code of the amount or balance.
unofficial_currency_codenullable string
The unofficial currency code associated with the amount or balance. Always null if iso_currency_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.
start_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 account'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_descriptionnullable string
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_numbernullable string
The check number of the transaction. This field is only populated for check transactions.
iso_currency_codenullable string
The ISO 4217 currency code of the amount or balance.
unofficial_currency_codenullable string
The unofficial currency code associated with the amount or balance. Always null if iso_currency_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.
warnings[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_WARNING
warning_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 did not grant permission to share income data for the Item REPORT_DELETED: Report deleted due to customer or consumer request

Possible values: IDENTITY_UNAVAILABLE, TRANSACTIONS_UNAVAILABLE, ITEM_UNAPPROVED, REPORT_DELETED
causeobject
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_GRANTED
error_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": true
34                    },
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": false
44                    }
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": "mobile1"
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                  "transactions": [
106                    {
107                      "amount": -100,
108                      "date": "2021-11-15",
109                      "name": "“PLAID_INC_DIRECT_DEP_PPD”",
110                      "original_description": "PLAID_INC_DIRECT_DEP_PPD 123",
111                      "pending": false,
112                      "transaction_id": "6RddrWNwE1uM63Ex5GKLhzlBl76aAZfgzlQNm",
113                      "check_number": null,
114                      "iso_currency_code": "USD",
115                      "unofficial_currency_code": null
116                    }
117                  ]
118                },
119                {
120                  "start_date": "2021-12-01",
121                  "end_date": "2021-12-31",
122                  "total_amount": 100,
123                  "iso_currency_code": "USD",
124                  "unofficial_currency_code": null,
125                  "transactions": [
126                    {
127                      "amount": -100,
128                      "date": "2021-12-15",
129                      "name": "“PLAID_INC_DIRECT_DEP_PPD”",
130                      "original_description": "PLAID_INC_DIRECT_DEP_PPD 123",
131                      "pending": false,
132                      "transaction_id": "7BddrWNwE1uM63Ex5GKLhzlBl82aAZfgzlCBl",
133                      "check_number": null,
134                      "iso_currency_code": "USD",
135                      "unofficial_currency_code": null
136                    }
137                  ]
138                },
139                {
140                  "start_date": "2022-01-01",
141                  "end_date": "2021-01-31",
142                  "total_amount": 100,
143                  "iso_currency_code": "USD",
144                  "unofficial_currency_code": null,
145                  "transactions": [
146                    {
147                      "amount": -100,
148                      "date": "2022-01-31",
149                      "name": "“PLAID_INC_DIRECT_DEP_PPD”",
150                      "original_description": "PLAID_INC_DIRECT_DEP_PPD 123",
151                      "pending": false,
152                      "transaction_id": "9FddrWNwE1uM95Ex5GKLhzlBl76aAZfgzlNQr",
153                      "check_number": null,
154                      "iso_currency_code": "USD",
155                      "unofficial_currency_code": null
156                    }
157                  ]
158                }
159              ]
160            }
161          ]
162        }
163      ],
164      "bank_income_summary": {
165        "total_amount": 300,
166        "iso_currency_code": "USD",
167        "unofficial_currency_code": null,
168        "start_date": "2021-11-15",
169        "end_date": "2022-01-15",
170        "income_sources_count": 1,
171        "income_categories_count": 1,
172        "income_transactions_count": 1,
173        "historical_summary": [
174          {
175            "start_date": "2021-11-02",
176            "end_date": "2021-11-30",
177            "total_amount": 100,
178            "iso_currency_code": "USD",
179            "unofficial_currency_code": null,
180            "transactions": [
181              {
182                "amount": -100,
183                "date": "2021-11-15",
184                "name": "“PLAID_INC_DIRECT_DEP_PPD”",
185                "original_description": "PLAID_INC_DIRECT_DEP_PPD 123",
186                "pending": false,
187                "transaction_id": "6RddrWNwE1uM63Ex5GKLhzlBl76aAZfgzlQNm",
188                "check_number": null,
189                "iso_currency_code": "USD",
190                "unofficial_currency_code": null
191              }
192            ]
193          },
194          {
195            "start_date": "2021-12-01",
196            "end_date": "2021-12-31",
197            "total_amount": 100,
198            "iso_currency_code": "USD",
199            "unofficial_currency_code": null,
200            "transactions": [
201              {
202                "amount": -100,
203                "date": "2021-12-15",
204                "name": "“PLAID_INC_DIRECT_DEP_PPD”",
205                "original_description": "PLAID_INC_DIRECT_DEP_PPD 123",
206                "pending": false,
207                "transaction_id": "7BddrWNwE1uM63Ex5GKLhzlBl82aAZfgzlCBl",
208                "check_number": null,
209                "iso_currency_code": "USD",
210                "unofficial_currency_code": null
211              }
212            ]
213          },
214          {
215            "start_date": "2022-01-01",
216            "end_date": "2021-01-31",
217            "total_amount": 100,
218            "iso_currency_code": "USD",
219            "unofficial_currency_code": null,
220            "transactions": [
221              {
222                "amount": -100,
223                "date": "2022-01-31",
224                "name": "“PLAID_INC_DIRECT_DEP_PPD”",
225                "original_description": "PLAID_INC_DIRECT_DEP_PPD 123",
226                "pending": false,
227                "transaction_id": "9FddrWNwE1uM95Ex5GKLhzlBl76aAZfgzlNQr",
228                "check_number": null,
229                "iso_currency_code": "USD",
230                "unofficial_currency_code": null
231              }
232            ]
233          }
234        ]
235      },
236      "warnings": []
237    }
238  ]
239}

/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/get

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.
1// Sample code coming soon
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 error
payroll_income[object]
account_idnullable string
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_amountnullable number
Raw amount of the deduction

Format: double
descriptionnullable string
Description of the deduction line item
iso_currency_codenullable string
The ISO-4217 currency code of the line item. Always null if unofficial_currency_code is non-null.
unofficial_currency_codenullable string
The unofficial currency code associated with the line item. Always null if iso_currency_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.
See the currency code schema for a full listing of supported iso_currency_codes.
ytd_amountnullable number
The year-to-date amount of the deduction

Format: double
totalobject
An object representing the total deductions for the pay period
current_amountnullable number
Raw amount of the deduction

Format: double
iso_currency_codenullable string
The ISO-4217 currency code of the line item. Always null if unofficial_currency_code is non-null.
unofficial_currency_codenullable string
The unofficial currency code associated with the line item. Always null if iso_currency_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.
See the currency code schema for a full listing of supported iso_currency_codes.
ytd_amountnullable number
The year-to-date total amount of the deductions

Format: double
document_idnullable string
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_typenullable string
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.
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, NONE
download_urlnullable string
Signed URL to retrieve the underlying file.
statusnullable string
The processing status of the document.
earningsobject
An object representing both a breakdown of earnings on a pay stub and the total earnings.
breakdown[object]
canonical_descriptionnullable string
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, null
current_amountnullable number
Raw amount of the earning line item.

Format: double
descriptionnullable string
Description of the earning line item.
hoursnullable number
Number of hours applicable for this earning.
iso_currency_codenullable string
The ISO-4217 currency code of the line item. Always null if unofficial_currency_code is non-null.
ratenullable number
Hourly rate applicable for this earning.

Format: double
unofficial_currency_codenullable string
The unofficial currency code associated with the line item. Always null if iso_currency_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.
See the currency code schema for a full listing of supported iso_currency_codes.
ytd_amountnullable number
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_amountnullable number
Total amount of the earnings for this pay period.

Format: double
hoursnullable number
Total number of hours worked for this pay period.
iso_currency_codenullable string
The ISO-4217 currency code of the line item. Always null if unofficial_currency_code is non-null.
unofficial_currency_codenullable string
The unofficial currency code associated with the security. Always null if iso_currency_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.
See the currency code schema for a full listing of supported iso_currency_codes.
ytd_amountnullable number
The total year-to-date amount of the earnings.

Format: double
employeeobject
Data about the employee.
addressobject
Address on the pay stub.
citynullable string
The full city name.
countrynullable string
The ISO 3166-1 alpha-2 country code.
postal_codenullable string
The postal code of the address.
regionnullable string
The region or state. Example: "NC"
streetnullable string
The full street address.
namenullable string
The name of the employee.
marital_statusnullable string
Marital status of the employee - either SINGLE or MARRIED.

Possible values: SINGLE, MARRIED, null
taxpayer_idobject
Taxpayer ID of the individual receiving the paystub.
id_typenullable string
Type of ID, e.g. 'SSN'.
id_masknullable string
ID mask; i.e. last 4 digits of the taxpayer ID.
employerobject
Information about the employer on the pay stub.
addressobject
Address on the pay stub.
citynullable string
The full city name.
countrynullable string
The ISO 3166-1 alpha-2 country code.
postal_codenullable string
The postal code of the address.
regionnullable string
The region or state. Example: "NC"
streetnullable string
The full street address.
namenullable string
The name of the employer on the pay stub.
net_payobject
An object representing information about the net pay amount on the pay stub.
current_amountnullable number
Raw amount of the net pay for the pay period.

Format: double
descriptionnullable string
Description of the net pay.
iso_currency_codenullable string
The ISO-4217 currency code of the net pay. Always null if unofficial_currency_code is non-null.
unofficial_currency_codenullable string
The unofficial currency code associated with the net pay. Always null if iso_currency_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.
See the currency code schema for a full listing of supported iso_currency_codes.
ytd_amountnullable number
The year-to-date amount of the net pay.

Format: double
pay_period_detailsobject
Details about the pay period.
pay_amountnullable number
The amount of the paycheck.

Format: double
distribution_breakdown[object]
account_namenullable string
Name of the account for the given distribution.
bank_namenullable string
The name of the bank that the payment is being deposited to.
current_amountnullable number
The amount distributed to this account.

Format: double
iso_currency_codenullable string
The ISO-4217 currency code of the net pay. Always null if unofficial_currency_code is non-null.
masknullable string
The last 2-4 alphanumeric characters of an account's official account number.
typenullable string
Type of the account that the paystub was sent to (e.g. 'checking').
unofficial_currency_codenullable string
The unofficial currency code associated with the net pay. Always null if iso_currency_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.
See the currency code schema for a full listing of supported iso_currency_codes.
end_datenullable string
The date on which the pay period ended, in ISO 8601 format ("yyyy-mm-dd").

Format: date
gross_earningsnullable number
Total earnings before tax/deductions.

Format: double
iso_currency_codenullable string
The ISO-4217 currency code of the net pay. Always null if unofficial_currency_code is non-null.
pay_datenullable string
The date on which the pay stub was issued, in ISO 8601 format ("yyyy-mm-dd").

Format: date
pay_frequencynullable string
The frequency at which an individual is paid.

Possible values: UNKNOWN, WEEKLY, BIWEEKLY, SEMI_MONTHLY, MONTHLY, null
start_datenullable string
The date on which the pay period started, in ISO 8601 format ("yyyy-mm-dd").

Format: date
unofficial_currency_codenullable string
The unofficial currency code associated with the net pay. Always null if iso_currency_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.
See the currency code schema for a full listing of supported iso_currency_codes.
verificationnullable object
An object containing details on the paystub's verification status. This object will only be populated if the income_verification.access_tokens parameter was provided during the /link/token/create call or if a problem was detected with the information supplied by the user; otherwise it will be null.
verification_statusnullable string
Derived verification status.

Possible values: UNKNOWN, VERIFIED, FRAUDULENT, null
verification_attributes[object]
typenullable string
Message indicating the reason as to why the verification failed.

Possible values: UNKNOWN, AMOUNT_MATCH, DATE_MATCH, DATE_MISMATCH, FILE_TAMPERING, DESCRIPTION_MATCH, DESCRIPTION_MISMATCH, FIRST_NAME_MATCH, FIRST_NAME_MISMATCH, LAST_NAME_MATCH, LAST_NAME_MISMATCH, null
w2s[object]
Array of tax form W-2s.
document_metadataobject
Object representing metadata pertaining to the document.
namestring
The name of the document.
document_typenullable string
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.
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, NONE
download_urlnullable string
Signed URL to retrieve the underlying file.
statusnullable string
The processing status of the document.
document_idstring
An identifier of the document referenced by the document metadata.
employerobject
Information about the employer on the pay stub.
addressobject
Address on the pay stub.
citynullable string
The full city name.
countrynullable string
The ISO 3166-1 alpha-2 country code.
postal_codenullable string
The postal code of the address.
regionnullable string
The region or state. Example: "NC"
streetnullable string
The full street address.
namenullable string
The name of the employer on the pay stub.
employeeobject
Data about the employee.
addressobject
Address on the pay stub.
citynullable string
The full city name.
countrynullable string
The ISO 3166-1 alpha-2 country code.
postal_codenullable string
The postal code of the address.
regionnullable string
The region or state. Example: "NC"
streetnullable string
The full street address.
namenullable string
The name of the employee.
marital_statusnullable string
Marital status of the employee - either SINGLE or MARRIED.

Possible values: SINGLE, MARRIED, null
taxpayer_idobject
Taxpayer ID of the individual receiving the paystub.
id_typenullable string
Type of ID, e.g. 'SSN'.
id_masknullable string
ID mask; i.e. last 4 digits of the taxpayer ID.
tax_yearnullable string
The tax year of the W2 document.
employer_id_numbernullable string
An employee identification number or EIN.
wages_tips_other_compnullable string
Wages from tips and other compensation.
federal_income_tax_withheldnullable string
Federal income tax withheld for the tax year.
social_security_wagesnullable string
Wages from social security.
social_security_tax_withheldnullable string
Social security tax withheld for the tax year.
medicare_wages_and_tipsnullable string
Wages and tips from medicare.
medicare_tax_withheldnullable string
Medicare tax withheld for the tax year.
social_security_tipsnullable string
Tips from social security.
allocated_tipsnullable string
Allocated tips.
box_9nullable string
Contents from box 9 on the W2.
dependent_care_benefitsnullable string
Dependent care benefits.
nonqualified_plansnullable string
Nonqualified plans.
box_12[object]
codenullable string
W2 Box 12 code.
amountnullable string
W2 Box 12 amount.
statutory_employeenullable string
Statutory employee.
retirement_plannullable string
Retirement plan.
third_party_sick_paynullable string
Third party sick pay.
othernullable string
Other.
state_and_local_wages[object]
statenullable string
State associated with the wage.
employer_state_id_numbernullable string
State identification number of the employer.
state_wages_tipsnullable string
Wages and tips from the specified state.
state_income_taxnullable string
Income tax from the specified state.
local_wages_tipsnullable string
Wages and tips from the locality.
local_income_taxnullable string
Income tax from the locality.
locality_namenullable string
Name of the locality.
statusnullable object
Details about the status of the payroll item.
processing_statusnullable string
Denotes the processing status for the verification.
UNKNOWN: The processing status could not be determined.
PROCESSING_COMPLETE: The processing has completed and the data is available to be retrieved.
PROCESSING: The verification is still processing. The data is not available yet.
UPLOADED: The user uploaded a document. The document has not yet begun processing.
CREATED: The verification has been created but no data is associated with it yet.
FAILED: The processing failed to complete successfully.
APPROVAL_STATUS_PENDING: The user has not yet approved the sharing of the data.
APPROVAL_STATUS_APPROVED: The user has approved the sharing of the data.

Possible values: UNKNOWN, PROCESSING_COMPLETE, PROCESSING, UPLOADED, CREATED, FAILED, APPROVAL_STATUS_APPROVED, APPROVAL_STATUS_PENDING
errornullable object
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_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
error_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_messagenullable string
A user-friendly representation of the error code. null if the error is not related to user action.
This may change over time and is not safe for programmatic use.
request_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.
statusnullable number
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_actionnullable string
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.
income_report_tokenstring
A token to reference what payroll data was returned from this endpoint
1{
2  "items": [
3    {
4      "item_id": "eVBnVMp7zdTJLkRNr33Rs6zr7KNJqBFL9DrE6",
5      "payroll_income": [
6        {
7          "account_id": "GeooLPBGDEunl54q7N3ZcyD5aLPLEai1nkzM9",
8          "pay_stubs": [
9            {
10              "deductions": {
11                "breakdown": [
12                  {
13                    "current_amount": 123.45,
14                    "description": "taxes",
15                    "iso_currency_code": "USD",
16                    "unofficial_currency_code": null,
17                    "ytd_amount": 246.9
18                  }
19                ],
20                "total": {
21                  "current_amount": 123.45,
22                  "iso_currency_code": "USD",
23                  "unofficial_currency_code": null,
24                  "ytd_amount": 246.9
25                }
26              },
27              "document_metadata": {
28                "document_type": "PAYSTUB",
29                "name": "paystub.pdf",
30                "status": "PROCESSING_COMPLETE",
31                "download_url": null
32              },
33              "document_id": "2jkflanbd",
34              "earnings": {
35                "breakdown": [
36                  {
37                    "canonical_description": "REGULAR_PAY",
38                    "current_amount": 200.22,
39                    "description": "salary earned",
40                    "hours": 80,
41                    "iso_currency_code": "USD",
42                    "rate": null,
43                    "unofficial_currency_code": null,
44                    "ytd_amount": 400.44
45                  },
46                  {
47                    "canonical_description": "BONUS",
48                    "current_amount": 100,
49                    "description": "bonus earned",
50                    "hours": null,
51                    "iso_currency_code": "USD",
52                    "rate": null,
53                    "unofficial_currency_code": null,
54                    "ytd_amount": 100
55                  }
56                ],
57                "total": {
58                  "current_amount": 300.22,
59                  "hours": 160,
60                  "iso_currency_code": "USD",
61                  "unofficial_currency_code": null,
62                  "ytd_amount": 500.44
63                }
64              },
65              "employee": {
66                "address": {
67                  "city": "SAN FRANCISCO",
68                  "country": "US",
69                  "postal_code": "94133",
70                  "region": "CA",
71                  "street": "2140 TAYLOR ST"
72                },
73                "name": "ANNA CHARLESTON",
74                "marital_status": "SINGLE",
75                "taxpayer_id": {
76                  "id_type": "SSN",
77                  "id_mask": "3333"
78                }
79              },
80              "employer": {
81                "name": "PLAID INC",
82                "address": {
83                  "city": "SAN FRANCISCO",
84                  "country": "US",
85                  "postal_code": "94111",
86                  "region": "CA",
87                  "street": "1098 HARRISON ST"
88                }
89              },
90              "net_pay": {
91                "current_amount": 123.34,
92                "description": "TOTAL NET PAY",
93                "iso_currency_code": "USD",
94                "unofficial_currency_code": null,
95                "ytd_amount": 253.54
96              },
97              "pay_period_details": {
98                "distribution_breakdown": [
99                  {
100                    "account_name": "Big time checking",
101                    "bank_name": "bank of plaid",
102                    "current_amount": 176.77,
103                    "iso_currency_code": "USD",
104                    "mask": "1223",
105                    "type": "checking",
106                    "unofficial_currency_code": null
107                  }
108                ],
109                "end_date": "2020-12-15",
110                "gross_earnings": 4500,
111                "iso_currency_code": "USD",
112                "pay_amount": 1490.21,
113                "pay_date": "2020-12-15",
114                "pay_frequency": "BIWEEKLY",
115                "start_date": "2020-12-01",
116                "unofficial_currency_code": null
117              },
118              "verification": {
119                "verification_status": "VERIFIED",
120                "verification_attributes": []
121              }
122            }
123          ],
124          "w2s": [
125            {
126              "allocated_tips": "1000",
127              "box_12": [
128                {
129                  "amount": "200",
130                  "code": "AA"
131                }
132              ],
133              "box_9": "box9",
134              "dependent_care_benefits": "1000",
135              "document_metadata": {
136                "document_type": "US_TAX_W2",
137                "download_url": null,
138                "name": "w_2.pdf",
139                "status": "PROCESSING_COMPLETE"
140              },
141              "document_id": "1pkflebk4",
142              "employee": {
143                "address": {
144                  "city": "San Francisco",
145                  "country": "US",
146                  "postal_code": "94103",
147                  "region": "CA",
148                  "street": "1234 Grand St"
149                },
150                "name": "Josie Georgia Harrison",
151                "marital_status": "SINGLE",
152                "taxpayer_id": {
153                  "id_type": "SSN",
154                  "id_mask": "1234"
155                }
156              },
157              "employer": {
158                "address": {
159                  "city": "New York",
160                  "country": "US",
161                  "postal_code": "10010",
162                  "region": "NY",
163                  "street": "456 Main St"
164                },
165                "name": "Acme Inc"
166              },
167              "employer_id_number": "12-1234567",
168              "federal_income_tax_withheld": "1000",
169              "medicare_tax_withheld": "1000",
170              "medicare_wages_and_tips": "1000",
171              "nonqualified_plans": "1000",
172              "other": "other",
173              "retirement_plan": "CHECKED",
174              "social_security_tax_withheld": "1000",
175              "social_security_tips": "1000",
176              "social_security_wages": "1000",
177              "state_and_local_wages": [
178                {
179                  "employer_state_id_number": "11111111111AAA",
180                  "local_income_tax": "200",
181                  "local_wages_and_tips": "200",
182                  "locality_name": "local",
183                  "state": "UT",
184                  "state_income_tax": "200",
185                  "state_wages_tips": "200"
186                }
187              ],
188              "statutory_employee": "CHECKED",
189              "tax_year": "2020",
190              "third_party_sick_pay": "CHECKED",
191              "wages_tips_other_comp": "1000"
192            }
193          ]
194        }
195      ],
196      "status": {
197        "processing_status": "PROCESSING_COMPLETE"
198      }
199    }
200  ],
201  "request_id": "2pxQ59buGdsHRef",
202  "income_report_token": "income-sandbox-6f12f5bb-22dd-4855-b918-f47ec439198a"
203}

/credit/payroll_income/precheck

Check income verification eligibility and optimize conversion

/credit/payroll_income/precheck is an optional endpoint that can be called before initializing a Link session for income verification. It evaluates whether a given user is supportable by digital income verification. If the user is eligible for digital verification, that information will be associated with the user token, and in this way will generate a Link UI optimized for the end user and their specific employer. If the user cannot be confirmed as eligible, the user can still use the income verification flow, but they may be required to manually upload a paystub to verify their income.
While all request fields are optional, providing employer data will increase the chance of receiving a useful result.

credit/payroll_income/precheck

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.
access_tokens[string]
An array of access tokens corresponding to Items belonging to the user whose eligibility is being checked. Note that if the Items specified here are not already initialized with transactions, providing them in this field will cause these Items to be initialized with (and billed for) the Transactions product.
employerobject
Information about the end user's employer
namestring
The employer's name
addressobject
Data about the components comprising an address.
citystring
The full city name
countrystring
The ISO 3166-1 alpha-2 country code
postal_codestring
The postal code. In API versions 2018-05-22 and earlier, this field is called zip.
regionstring
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"
tax_idstring
The employer's tax id
urlstring
The URL for the employer's public website
us_military_infoobject
Data about military info in the income verification precheck.
is_active_dutyboolean
Is the user currently active duty in the US military
branchstring
If the user is currently serving in the US military, the branch of the military in which they are serving Valid values: 'AIR FORCE', 'ARMY', 'COAST GUARD', 'MARINES', 'NAVY', 'UNKNOWN'
1// Sample code coming soon
credit/payroll_income/precheck

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.
confidencestring
The confidence that Plaid can support the user in the digital income verification flow instead of requiring a manual paystub upload. One of the following:
"HIGH": It is very likely that this user can use the digital income verification flow.
"LOW": It is unlikely that this user can use the digital income verification flow.
"UNKNOWN": It was not possible to determine if the user is supportable with the information passed.

Possible values: HIGH, LOW, UNKNOWN
1{
2  "request_id": "lMjeOeu9X1VUh1F",
3  "confidence": "HIGH"
4}

/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.

credit/employment/get

Request fields and example

client_idrequiredstring
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.
secretrequiredstring
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.
1// Sample code coming soon
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 error
employments[object]
account_idnullable string
ID of the payroll provider account.
statusnullable string
Current employment status.

Possible values: ACTIVE, INACTIVE, null
start_datenullable string
Start of employment in ISO 8601 format (YYYY-MM-DD).

Format: date
end_datenullable string
End of employment, if applicable. Provided in ISO 8601 format (YYY-MM-DD).

Format: date
employerobject
An object containing employer data.
namenullable string
Name of employer.
titlenullable string
Current title of employee.
platform_idsobject
The object containing a set of ids related to an employee.
employee_idnullable string
The ID of an employee as given by their employer.
payroll_idnullable string
The ID of an employee as given by their payroll.
position_idnullable string
The ID of the position of the employee.
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        }
21      ]
22    }
23  ],
24  "request_id": "LhQf0THi8SH1yJm"
25}

/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.

user/create

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. 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.
1// Sample code coming soon
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}

/income/verification/precheck

(Deprecated) Check digital income verification eligibility and optimize conversion

/income/verification/precheck is an optional endpoint that can be called before initializing a Link session for income verification. It evaluates whether a given user is supportable by digital income verification and returns a precheck_id that can be provided to /link/token/create. If the user is eligible for digital verification, providing the precheck_id in this way will generate a Link UI optimized for the end user and their specific employer. If the user cannot be confirmed as eligible, the precheck_id can still be provided to /link/token/create and the user can still use the income verification flow, but they may be required to manually upload a paystub to verify their income.
While all request fields are optional, providing either employer or transactions_access_tokens data will increase the chance of receiving a useful result.
This endpoint has been deprecated; new integrations should use /credit/payroll_income/precheck instead.

income/verification/precheck

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.
userobject
Information about the user whose eligibility is being evaluated.
first_namestring
The user's first name
last_namestring
The user's last name
email_addressstring
The user's email address
home_addressobject
Data about the components comprising an address.
citystring
The full city name
regionstring
The region or state Example: "NC"
streetstring
The full street address Example: "564 Main Street, APT 15"
postal_codestring
The postal code
countrystring
The ISO 3166-1 alpha-2 country code
employerobject
Information about the end user's employer
namestring
The employer's name
addressobject
Data about the components comprising an address.
citystring
The full city name
countrystring
The ISO 3166-1 alpha-2 country code
postal_codestring
The postal code. In API versions 2018-05-22 and earlier, this field is called zip.
regionstring
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"
tax_idstring
The employer's tax id
urlstring
The URL for the employer's public website
transactions_access_tokendeprecatedstring
The access token associated with the Item data is being requested for.
transactions_access_tokens[string]
An array of access tokens corresponding to Items belonging to the user whose eligibility is being checked. Note that if the Items specified here are not already initialized with transactions, providing them in this field will cause these Items to be initialized with (and billed for) the Transactions product.
us_military_infoobject
Data about military info in the income verification precheck.
is_active_dutyboolean
Is the user currently active duty in the US military
branchstring
If the user is currently serving in the US military, the branch of the military in which they are serving Valid values: 'AIR FORCE', 'ARMY', 'COAST GUARD', 'MARINES', 'NAVY', 'UNKNOWN'
1const request: IncomeVerificationPrecheckRequest = {
2  user: {
3    first_name: 'Jane',
4    last_name: 'Doe',
5    email_address: 'janedoe@gmail.com',
6    home_address: {
7      street: '234 First St.',
8      city: 'Anytown',
9      region: 'CA',
10      postal_code: '12345',
11    },
12  },
13  employer: {
14    name: 'Plaid Inc.',
15    tax_id: '123-45-6709',
16    address: {
17      street: '234 Work St.',
18      city: 'Anytown',
19      region: 'CA',
20      postal_code: '12345',
21      country: 'US',
22    },
23    url: 'http://www.employer.com',
24  },
25};
26try {
27  const response = await plaidClient.incomeVerificationPrecheck(request);
28} catch (error) {
29  // handle error
30}
income/verification/precheck

Response fields and example

precheck_idstring
ID of the precheck. Provide this value when calling /link/token/create in order to optimize Link conversion.
request_idstring
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
confidencestring
The confidence that Plaid can support the user in the digital income verification flow instead of requiring a manual paystub upload. One of the following:
"HIGH": It is very likely that this user can use the digital income verification flow.
"LOW": It is unlikely that this user can use the digital income verification flow.
"UNKNOWN": It was not possible to determine if the user is supportable with the information passed.

Possible values: HIGH, LOW, UNKNOWN
1{
2  "request_id": "lMjeOeu9X1VUh1F",
3  "precheck_id": "n9elqYlvYm",
4  "confidence": "HIGH"
5}

/income/verification/paystubs/get

(Deprecated) Retrieve information from the paystubs used for income verification

/income/verification/paystubs/get returns the information collected from the paystubs that were used to verify an end user''s income. It can be called once the status of the verification has been set to VERIFICATION_STATUS_PROCESSING_COMPLETE, as reported by the INCOME: verification_status webhook. Attempting to call the endpoint before verification has been completed will result in an error.
This endpoint has been deprecated; new integrations should use /credit/payroll_income/get instead.

income/verification/paystubs/get

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.
income_verification_iddeprecatedstring
The ID of the verification for which to get paystub information.
access_tokenstring
The access token associated with the Item data is being requested for.
1const request: IncomeVerificationPaystubsGetRequest = {
2  access_token: accessToken,
3};
4try {
5  const response = await plaidClient.incomeVerificationPaystubsGet(request);
6} catch (error) {
7  // handle error
8}
income/verification/paystubs/get

Response fields and example

document_metadata[object]
Metadata for an income document.
namestring
The name of the document.
statusstring
The processing status of the document.
doc_idstring
An identifier of the document that is also present in the paystub response.
doc_typestring
The type of document.
DOCUMENT_TYPE_PAYSTUB: A paystub.
DOCUMENT_TYPE_BANK_STATEMENT: A bank statement.
DOCUMENT_TYPE_US_TAX_W2: A W-2 wage and tax statement provided by a US employer reflecting wages earned by the employee.
DOCUMENT_TYPE_US_MILITARY_ERAS: An electronic Retirement Account Statement (eRAS) issued by the US military.
DOCUMENT_TYPE_US_MILITARY_LES: A Leave and Earnings Statement (LES) issued by the US military.
DOCUMENT_TYPE_US_MILITARY_CLES: A Civilian Leave and Earnings Statment (CLES) issued by the US military.
DOCUMENT_TYPE_GIG: Used to indicate that the income is related to gig work. Does not necessarily correspond to a specific document type.
DOCUMENT_TYPE_NONE: Used to indicate that there is no underlying document for the data.
UNKNOWN: Document type could not be determined.

Possible values: UNKNOWN, DOCUMENT_TYPE_PAYSTUB, DOCUMENT_TYPE_BANK_STATEMENT, DOCUMENT_TYPE_US_TAX_W2, DOCUMENT_TYPE_US_MILITARY_ERAS, DOCUMENT_TYPE_US_MILITARY_LES, DOCUMENT_TYPE_US_MILITARY_CLES, DOCUMENT_TYPE_GIG, DOCUMENT_TYPE_NONE
paystubs[object]
deductionsobject
An object with the deduction information found on a paystub.
subtotalsdeprecated[object]
canonical_descriptionnullable string
Commonly used term to describe the line item.

Possible values: BONUS, COMMISSION, OVERTIME, PAID TIME OFF, REGULAR PAY, VACATION, EMPLOYEE MEDICARE, FICA, SOCIAL SECURITY EMPLOYEE TAX, MEDICAL, VISION, DENTAL, NET PAY, TAXES, NOT_FOUND, OTHER, null
descriptionnullable string
Text of the line item as printed on the paystub.
current_paydeprecatedobject
An object representing a monetary amount.
amountnullable number
A numerical amount of a specific currency.

Format: double
currencynullable string
Currency code, e.g. USD
ytd_paydeprecatedobject
An object representing a monetary amount.
amountnullable number
A numerical amount of a specific currency.

Format: double
currencynullable string
Currency code, e.g. USD
breakdown[object]
current_amountnullable number
Raw amount of the deduction

Format: double
descriptionnullable string
Description of the deduction line item
iso_currency_codenullable string
The ISO-4217 currency code of the line item. Always null if unofficial_currency_code is non-null.
unofficial_currency_codenullable string
The unofficial currency code associated with the line item. Always null if iso_currency_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.
See the currency code schema for a full listing of supported iso_currency_codes.
ytd_amountnullable number
The year-to-date amount of the deduction

Format: double
totalsdeprecated[object]
canonical_descriptionnullable string
Commonly used term to describe the line item.

Possible values: BONUS, COMMISSION, OVERTIME, PAID TIME OFF, REGULAR PAY, VACATION, EMPLOYEE MEDICARE, FICA, SOCIAL SECURITY EMPLOYEE TAX, MEDICAL, VISION, DENTAL, NET PAY, TAXES, NOT_FOUND, OTHER, null
descriptionnullable string
Text of the line item as printed on the paystub.
current_paydeprecatedobject
An object representing a monetary amount.
amountnullable number
A numerical amount of a specific currency.

Format: double
currencynullable string
Currency code, e.g. USD
ytd_paydeprecatedobject
An object representing a monetary amount.
amountnullable number
A numerical amount of a specific currency.

Format: double
currencynullable string
Currency code, e.g. USD
totalobject
An object representing the total deductions for the pay period
current_amountnullable number
Raw amount of the deduction

Format: double
iso_currency_codenullable string
The ISO-4217 currency code of the line item. Always null if unofficial_currency_code is non-null.
unofficial_currency_codenullable string
The unofficial currency code associated with the line item. Always null if iso_currency_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.
See the currency code schema for a full listing of supported iso_currency_codes.
ytd_amountnullable number
The year-to-date total amount of the deductions

Format: double
doc_idstring
An identifier of the document referenced by the document metadata.
earningsobject
An object representing both a breakdown of earnings on a paystub and the total earnings.
subtotalsdeprecated[object]
current_amountnullable number
Total amount of the earnings for this pay period

Format: double
current_paydeprecatedobject
An object representing a monetary amount.
amountnullable number
A numerical amount of a specific currency.

Format: double
currencynullable string
Currency code, e.g. USD
ytd_paydeprecatedobject
An object representing a monetary amount.
amountnullable number
A numerical amount of a specific currency.

Format: double
currencynullable string
Currency code, e.g. USD
hoursnullable number
Total number of hours worked for this pay period
iso_currency_codenullable string
The ISO-4217 currency code of the line item. Always null if unofficial_currency_code is non-null.
unofficial_currency_codenullable string
The unofficial currency code associated with the security. Always null if iso_currency_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.
See the currency code schema for a full listing of supported iso_currency_codes.
ytd_amountnullable number
The total year-to-date amount of the earnings

Format: double
totalsdeprecated[object]
current_amountnullable number
Total amount of the earnings for this pay period

Format: double
current_paydeprecatedobject
An object representing a monetary amount.
amountnullable number
A numerical amount of a specific currency.

Format: double
currencynullable string
Currency code, e.g. USD
ytd_paydeprecatedobject
An object representing a monetary amount.
amountnullable number
A numerical amount of a specific currency.

Format: double
currencynullable string
Currency code, e.g. USD
hoursnullable number
Total number of hours worked for this pay period
iso_currency_codenullable string
The ISO-4217 currency code of the line item. Always null if unofficial_currency_code is non-null.
unofficial_currency_codenullable string
The unofficial currency code associated with the security. Always null if iso_currency_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.
See the currency code schema for a full listing of supported iso_currency_codes.
ytd_amountnullable number
The total year-to-date amount of the earnings

Format: double
breakdown[object]
canonical_descriptionnullable string
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, null
current_amountnullable number
Raw amount of the earning line item.

Format: double
descriptionnullable string
Description of the earning line item.
hoursnullable number
Number of hours applicable for this earning.
iso_currency_codenullable string
The ISO-4217 currency code of the line item. Always null if unofficial_currency_code is non-null.
ratenullable number
Hourly rate applicable for this earning.

Format: double
unofficial_currency_codenullable string
The unofficial currency code associated with the line item. Always null if iso_currency_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.
See the currency code schema for a full listing of supported iso_currency_codes.
ytd_amountnullable number
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_amountnullable number
Total amount of the earnings for this pay period

Format: double
current_paydeprecatedobject
An object representing a monetary amount.
amountnullable number
A numerical amount of a specific currency.

Format: double
currencynullable string
Currency code, e.g. USD
ytd_paydeprecatedobject
An object representing a monetary amount.
amountnullable number
A numerical amount of a specific currency.

Format: double
currencynullable string
Currency code, e.g. USD
hoursnullable number
Total number of hours worked for this pay period
iso_currency_codenullable string
The ISO-4217 currency code of the line item. Always null if unofficial_currency_code is non-null.
unofficial_currency_codenullable string
The unofficial currency code associated with the security. Always null if iso_currency_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.
See the currency code schema for a full listing of supported iso_currency_codes.
ytd_amountnullable number
The total year-to-date amount of the earnings

Format: double
employeeobject
Data about the employee.
addressobject
Address on the paystub
citynullable string
The full city name.
countrynullable string
The ISO 3166-1 alpha-2 country code.
postal_codenullable string
The postal code of the address.
regionnullable string
The region or state Example: "NC"
streetnullable string
The full street address.
line1deprecatednullable string
Street address line 1.
line2deprecatednullable string
Street address line 2.
state_codedeprecatednullable string
The region or state Example: "NC"
namenullable string
The name of the employee.
marital_statusnullable string
Marital status of the employee - either single or married.

Possible values: single, married
taxpayer_idobject
Taxpayer ID of the individual receiving the paystub.
id_typenullable string
Type of ID, e.g. 'SSN'
id_masknullable string
ID mask; i.e. last 4 digits of the taxpayer ID
last_4_digitsdeprecatednullable string
Last 4 digits of unique number of ID.

Min length: 4
Max length: 4
employerobject
Information about the employer on the paystub
addressobject
Address on the paystub
citynullable string
The full city name.
countrynullable string
The ISO 3166-1 alpha-2 country code.
postal_codenullable string
The postal code of the address.
regionnullable string
The region or state Example: "NC"
streetnullable string
The full street address.
line1deprecatednullable string
Street address line 1.
line2deprecatednullable string
Street address line 2.
state_codedeprecatednullable string
The region or state Example: "NC"
namenullable string
The name of the employer on the paystub.
employment_detailsdeprecatedobject
An object representing employment details found on a paystub.
annual_salarydeprecatedobject
An object representing a monetary amount.
amountnullable number
A numerical amount of a specific currency.

Format: double
currencynullable string
Currency code, e.g. USD
hire_datenullable string
Date on which the employee was hired, in the YYYY-MM-DD format.

Format: date
net_payobject
An object representing information about the net pay amount on the paystub.
current_amountnullable number
Raw amount of the net pay for the pay period

Format: double
descriptionnullable string
Description of the net pay
iso_currency_codenullable string
The ISO-4217 currency code of the net pay. Always null if unofficial_currency_code is non-null.
unofficial_currency_codenullable string
The unofficial currency code associated with the net pay. Always null if iso_currency_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.
See the currency code schema for a full listing of supported iso_currency_codes.
ytd_amountnullable number
The year-to-date amount of the net pay

Format: double
totaldeprecatedobject
An object representing both the current pay period and year to date amount for a category.
canonical_descriptionnullable string
Commonly used term to describe the line item.

Possible values: BONUS, COMMISSION, OVERTIME, PAID TIME OFF, REGULAR PAY, VACATION, EMPLOYEE MEDICARE, FICA, SOCIAL SECURITY EMPLOYEE TAX, MEDICAL, VISION, DENTAL, NET PAY, TAXES, NOT_FOUND, OTHER, null
descriptionnullable string
Text of the line item as printed on the paystub.
current_paydeprecatedobject
An object representing a monetary amount.
amountnullable number
A numerical amount of a specific currency.

Format: double
currencynullable string
Currency code, e.g. USD
ytd_paydeprecatedobject
An object representing a monetary amount.
amountnullable number
A numerical amount of a specific currency.

Format: double
currencynullable string
Currency code, e.g. USD
pay_period_detailsobject
Details about the pay period.
check_amountnullable number
The amount of the paycheck.

Format: double
distribution_breakdown[object]
account_namenullable string
Name of the account for the given distribution.
bank_namenullable string
The name of the bank that the payment is being deposited to.
current_amountnullable number
The amount distributed to this account.

Format: double
iso_currency_codenullable string
The ISO-4217 currency code of the net pay. Always null if unofficial_currency_code is non-null.
masknullable string
The last 2-4 alphanumeric characters of an account's official account number.
typenullable string
Type of the account that the paystub was sent to (e.g. 'checking').
unofficial_currency_codenullable string
The unofficial currency code associated with the net pay. Always null if iso_currency_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.
See the currency code schema for a full listing of supported iso_currency_codes.
current_paydeprecatedobject
An object representing a monetary amount.
amountnullable number
A numerical amount of a specific currency.

Format: double
currencynullable string
Currency code, e.g. USD
end_datenullable string
The pay period end date, in ISO 8601 format: "yyyy-mm-dd".

Format: date
gross_earningsnullable number
Total earnings before tax/deductions.

Format: double
pay_datenullable string
The date on which the paystub was issued, in ISO 8601 format ("yyyy-mm-dd").

Format: date
pay_frequencynullable string
The frequency at which an individual is paid.

Possible values: PAY_FREQUENCY_UNKNOWN, PAY_FREQUENCY_WEEKLY, PAY_FREQUENCY_BIWEEKLY, PAY_FREQUENCY_SEMIMONTHLY, PAY_FREQUENCY_MONTHLY, null
pay_daydeprecatednullable string
The date on which the paystub was issued, in ISO 8601 format ("yyyy-mm-dd").

Format: date
start_datenullable string
The pay period start date, in ISO 8601 format: "yyyy-mm-dd".

Format: date
paystub_detailsdeprecatedobject
An object representing details that can be found on the paystub.
pay_period_start_datenullable string
Beginning date of the pay period on the paystub in the 'YYYY-MM-DD' format.

Format: date
pay_period_end_datenullable string
Ending date of the pay period on the paystub in the 'YYYY-MM-DD' format.

Format: date
pay_datenullable string
Pay date on the paystub in the 'YYYY-MM-DD' format.

Format: date
paystub_providernullable string
The name of the payroll provider that generated the paystub, e.g. ADP
pay_frequencynullable string
The frequency at which the employee is paid. Possible values: MONTHLY, BI-WEEKLY, WEEKLY, SEMI-MONTHLY.

Possible values: MONTHLY, BI-WEEKLY, WEEKLY, SEMI-MONTHLY, null
income_breakdowndeprecated[object]
typenullable string
The type of income. Possible values include: "regular": regular income "overtime": overtime income "bonus": bonus income

Possible values: bonus, overtime, regular, null
ratenullable number
The hourly rate at which the income is paid.

Format: double
hoursnullable number
The number of hours logged for this income for this pay period.
totalnullable number
The total pay for this pay period.

Format: double
ytd_earningsdeprecatedobject
The amount of income earned year to date, as based on paystub data.
gross_earningsnullable number
Year-to-date gross earnings.

Format: double
net_earningsnullable number
Year-to-date net (take home) earnings.

Format: double
verificationnullable object
An object containing details on the paystub's verification status. This object will only be populated if the income_verification.access_tokens parameter was provided during the /link/token/create call or if a problem was detected with the information supplied by the user; otherwise it will be null.
verification_statusnullable string
Derived verification status.

Possible values: PAYSTUB_VERIFICATION_STATUS_UNKNOWN, PAYSTUB_VERIFICATION_STATUS_VERIFIED, PAYSTUB_VERIFICATION_STATUS_FRAUDULENT, null
verification_attributes[object]
typenullable string
Message indicating the reason as to why the verification failed

Possible values: VERIFICATION_ATTRIBUTE_TYPE_UNKNOWN, VERIFICATION_ATTRIBUTE_TYPE_AMOUNT_MATCH, VERIFICATION_ATTRIBUTE_TYPE_DATE_MATCH, VERIFICATION_ATTRIBUTE_TYPE_DATE_MISMATCH, VERIFICATION_ATTRIBUTE_TYPE_FILE_TAMPERING, VERIFICATION_ATTRIBUTE_TYPE_DESCRIPTION_MATCH, VERIFICATION_ATTRIBUTE_TYPE_DESCRIPTION_MISMATCH, VERIFICATION_ATTRIBUTE_TYPE_FIRST_NAME_MATCH, VERIFICATION_ATTRIBUTE_TYPE_FIRST_NAME_MISMATCH, VERIFICATION_ATTRIBUTE_TYPE_LAST_NAME_MATCH, VERIFICATION_ATTRIBUTE_TYPE_LAST_NAME_MISMATCH, null
errornullable object
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_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
error_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_messagenullable string
A user-friendly representation of the error code. null if the error is not related to user action.
This may change over time and is not safe for programmatic use.
request_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.
statusnullable number
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_actionnullable string
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  "document_metadata": [
3    {
4      "doc_id": "2jkflanbd",
5      "doc_type": "DOCUMENT_TYPE_PAYSTUB",
6      "name": "paystub.pdf",
7      "status": "DOCUMENT_STATUS_PROCESSING_COMPLETE"
8    }
9  ],
10  "paystubs": [
11    {
12      "deductions": {
13        "breakdown": [
14          {
15            "current_amount": 123.45,
16            "description": "taxes",
17            "iso_currency_code": "USD",
18            "unofficial_currency_code": null,
19            "ytd_amount": 246.9
20          }
21        ],
22        "total": {
23          "current_amount": 123.45,
24          "iso_currency_code": "USD",
25          "unofficial_currency_code": null,
26          "ytd_amount": 246.9
27        }
28      },
29      "doc_id": "2jkflanbd",
30      "earnings": {
31        "breakdown": [
32          {
33            "canonical_description": "REGULAR PAY",
34            "current_amount": 200.22,
35            "description": "salary earned",
36            "hours": 80,
37            "iso_currency_code": "USD",
38            "rate": null,
39            "unofficial_currency_code": null,
40            "ytd_amount": 400.44
41          },
42          {
43            "canonical_desription": "BONUS",
44            "current_amount": 100,
45            "description": "bonus earned",
46            "hours": null,
47            "iso_currency_code": "USD",
48            "rate": null,
49            "unofficial_currency_code": null,
50            "ytd_amount": 100
51          }
52        ],
53        "total": {
54          "current_amount": 300.22,
55          "hours": 160,
56          "iso_currency_code": "USD",
57          "unofficial_currency_code": null,
58          "ytd_amount": 500.44
59        }
60      },
61      "employee": {
62        "address": {
63          "city": "SAN FRANCISCO",
64          "country": "US",
65          "postal_code": "94133",
66          "region": "CA",
67          "street": "2140 TAYLOR ST"
68        },
69        "name": "ANNA CHARLESTON",
70        "marital_status": "single",
71        "taxpayer_id": {
72          "id_type": "SSN",
73          "id_mask": "3333"
74        }
75      },
76      "employer": {
77        "name": "PLAID INC",
78        "address": {
79          "city": "SAN FRANCISCO",
80          "country": "US",
81          "postal_code": "94111",
82          "region": "CA",
83          "street": "1098 HARRISON ST"
84        }
85      },
86      "net_pay": {
87        "current_amount": 123.34,
88        "description": "TOTAL NET PAY",
89        "iso_currency_code": "USD",
90        "unofficial_currency_code": null,
91        "ytd_amount": 253.54
92      },
93      "pay_period_details": {
94        "check_amount": 1490.21,
95        "distribution_breakdown": [
96          {
97            "account_name": "Big time checking",
98            "bank_name": "bank of plaid",
99            "current_amount": 176.77,
100            "iso_currency_code": "USD",
101            "mask": "1223",
102            "type": "checking",
103            "unofficial_currency_code": null
104          }
105        ],
106        "end_date": "2020-12-15",
107        "gross_earnings": 4500,
108        "pay_date": "2020-12-15",
109        "start_date": "2020-12-01",
110        "pay_frequency": "PAY_FREQUENCY_BIWEEKLY"
111      },
112      "verification": {
113        "verification_status": "PAYSTUB_VERIFICATION_STATUS_VERIFIED",
114        "verification_attributes": []
115      }
116    }
117  ],
118  "request_id": "2pxQ59buGdsHRef"
119}

/income/verification/documents/download

(Deprecated) Download the original documents used for income verification

/income/verification/documents/download provides the ability to download the source documents associated with the verification.
If Document Income was used, the documents will be those the user provided in Link. For Payroll Income, the most recent files available for download from the payroll provider will be available from this endpoint.
The response to /income/verification/documents/download is a ZIP file in binary data. If a document_id is passed, a single document will be contained in this file. If not, the response will contain all documents associated with the verification.
The request_id is returned in the Plaid-Request-ID header.

income/verification/documents/download

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.
income_verification_iddeprecatedstring
The ID of the verification.
access_tokenstring
The access token associated with the Item data is being requested for.
document_idstring
The document ID to download. If passed, a single document will be returned in the resulting zip file, rather than all document
1const request: IncomeVerificationDocumentsDownloadRequest = {
2  access_token: accessToken,
3};
4try {
5  const response = await plaidClient.incomeVerificationDocumentsDownload(
6    request,
7  );
8} catch (error) {
9  // handle error
10}
Response

This endpoint returns binary ZIP data.

/income/verification/taxforms/get

(Deprecated) Retrieve information from the tax documents used for income verification

/income/verification/taxforms/get returns the information collected from forms that were used to verify an end user''s income. It can be called once the status of the verification has been set to VERIFICATION_STATUS_PROCESSING_COMPLETE, as reported by the INCOME: verification_status webhook. Attempting to call the endpoint before verification has been completed will result in an error.
This endpoint has been deprecated; new integrations should use /credit/payroll_income/get instead.

income/verification/taxforms/get

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.
income_verification_iddeprecatedstring
The ID of the verification.
access_tokenstring
The access token associated with the Item data is being requested for.
1const request: IncomeVerificationTaxformsGetRequest = {
2  access_token: accessToken,
3};
4try {
5  const response = await plaidClient.incomeVerificationTaxformsGet(request);
6} catch (error) {
7  // handle error
8}
income/verification/taxforms/get

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.
document_metadata[object]
namestring
The name of the document.
statusstring
The processing status of the document.
doc_idstring
An identifier of the document that is also present in the paystub response.
doc_typestring
The type of document.
DOCUMENT_TYPE_PAYSTUB: A paystub.
DOCUMENT_TYPE_BANK_STATEMENT: A bank statement.
DOCUMENT_TYPE_US_TAX_W2: A W-2 wage and tax statement provided by a US employer reflecting wages earned by the employee.
DOCUMENT_TYPE_US_MILITARY_ERAS: An electronic Retirement Account Statement (eRAS) issued by the US military.
DOCUMENT_TYPE_US_MILITARY_LES: A Leave and Earnings Statement (LES) issued by the US military.
DOCUMENT_TYPE_US_MILITARY_CLES: A Civilian Leave and Earnings Statment (CLES) issued by the US military.
DOCUMENT_TYPE_GIG: Used to indicate that the income is related to gig work. Does not necessarily correspond to a specific document type.
DOCUMENT_TYPE_NONE: Used to indicate that there is no underlying document for the data.
UNKNOWN: Document type could not be determined.

Possible values: UNKNOWN, DOCUMENT_TYPE_PAYSTUB, DOCUMENT_TYPE_BANK_STATEMENT, DOCUMENT_TYPE_US_TAX_W2, DOCUMENT_TYPE_US_MILITARY_ERAS, DOCUMENT_TYPE_US_MILITARY_LES, DOCUMENT_TYPE_US_MILITARY_CLES, DOCUMENT_TYPE_GIG, DOCUMENT_TYPE_NONE
taxforms[object]
A list of forms.
doc_idstring
An identifier of the document referenced by the document metadata.
document_typestring
The type of tax document. Currently, the only supported value is w2.
w2object
W2 is an object that represents income data taken from a W2 tax document.
employerobject
Information about the employer on the paystub
addressobject
Address on the paystub
citynullable string
The full city name.
countrynullable string
The ISO 3166-1 alpha-2 country code.
postal_codenullable string
The postal code of the address.
regionnullable string
The region or state Example: "NC"
streetnullable string
The full street address.
line1deprecatednullable string
Street address line 1.
line2deprecatednullable string
Street address line 2.
state_codedeprecatednullable string
The region or state Example: "NC"
namenullable string
The name of the employer on the paystub.
employeeobject
Data about the employee.
addressobject
Address on the paystub
citynullable string
The full city name.
countrynullable string
The ISO 3166-1 alpha-2 country code.
postal_codenullable string
The postal code of the address.
regionnullable string
The region or state Example: "NC"
streetnullable string
The full street address.
line1deprecatednullable string
Street address line 1.
line2deprecatednullable string
Street address line 2.
state_codedeprecatednullable string
The region or state Example: "NC"
namenullable string
The name of the employee.
marital_statusnullable string
Marital status of the employee - either single or married.

Possible values: single, married
taxpayer_idobject
Taxpayer ID of the individual receiving the paystub.
id_typenullable string
Type of ID, e.g. 'SSN'
id_masknullable string
ID mask; i.e. last 4 digits of the taxpayer ID
last_4_digitsdeprecatednullable string
Last 4 digits of unique number of ID.

Min length: 4
Max length: 4
tax_yearnullable string
The tax year of the W2 document.
employer_id_numbernullable string
An employee identification number or EIN.
wages_tips_other_compnullable string
Wages from tips and other compensation.
federal_income_tax_withheldnullable string
Federal income tax withheld for the tax year.
social_security_wagesnullable string
Wages from social security.
social_security_tax_withheldnullable string
Social security tax withheld for the tax year.
medicare_wages_and_tipsnullable string
Wages and tips from medicare.
medicare_tax_withheldnullable string
Medicare tax withheld for the tax year.
social_security_tipsnullable string
Tips from social security.
allocated_tipsnullable string
Allocated tips.
box_9nullable string
Contents from box 9 on the W2.
dependent_care_benefitsnullable string
Dependent care benefits.
nonqualified_plansnullable string
Nonqualified plans.
box_12[object]
codenullable string
W2 Box 12 code.
amountnullable string
W2 Box 12 amount.
statutory_employeenullable string
Statutory employee.
retirement_plannullable string
Retirement plan.
third_party_sick_paynullable string
Third party sick pay.