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
/credit/sessions/getGet Link session metadata and results for 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_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
user_token
string
The user token associated with the User data is being requested for.
options
object
An optional object for /credit/bank_income/get request options.
count
integer
How many Bank Income Reports should be fetched. Multiple reports may be available if the report has been re-created or refreshed. If more than one report is available, the most recent reports will be returned first.

Default: 1 
1const request: CreditBankIncomeGetRequest = {
2  user_token: 'user-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d',
3  options: {
4    count: 1,
5  },
6};
7
8try {
9  const response = await client.creditBankIncomeGet(request);
10} catch (error) {
11  // handle error
12}
credit/bank_income/get

Response fields and example

bank_income
[object]
bank_income_id
string
The unique identifier associated with the Bank Income Report.
generated_time
string
The time when the Bank Income Report was generated.

Format: date-time
days_requested
integer
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_id
string
Plaid's unique identifier for the account.
mask
nullable string
The last 2-4 alphanumeric characters of an account's official account number. Note that the mask may be non-unique between an Item's accounts, and it may also not match the mask that the bank displays to the user.
name
string
The name of the bank account.
official_name
nullable string
The official name of the bank account.
subtype
string
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
type
string
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. 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.
data
string
The phone number.
primary
boolean
When true, identifies the phone number as the primary number on an account.
type
string
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.
data
string
The email address.
primary
boolean
When true, identifies the email address as the primary email on an account.
type
string
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.
data
object
Data about the components comprising an address.
city
string
The full city name
region
nullable string
The region or state. In API versions 2018-05-22 and earlier, this field is called state. Example: "NC"
street
string
The full street address Example: "564 Main Street, APT 15"
postal_code
nullable string
The postal code. In API versions 2018-05-22 and earlier, this field is called zip.
country
nullable string
The ISO 3166-1 alpha-2 country code
primary
boolean
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_id
string
A unique identifier for an income source.
income_description
string
The most common name or original description for the underlying income transactions.
income_category
string
The income category.

Possible values: SALARY, UNEMPLOYMENT, CASH, GIG_ECONOMY, RENTAL, CHILD_SUPPORT, MILITARY, RETIREMENT, LONG_TERM_DISABILITY, BANK_INTEREST, CASH_DEPOSIT, TRANSFER_FROM_APPLICATION, TAX_REFUND, OTHER
account_id
string
Plaid's unique identifier for the account.
start_date
string
Minimum of all dates within the specific income sources in the user's bank account for days requested by the client. The date will be returned in an ISO 8601 format (YYYY-MM-DD).

Format: date
end_date
string
Maximum of all dates within the specific income sources in the user’s bank account for days requested by the client. The date will be returned in an ISO 8601 format (YYYY-MM-DD).

Format: date
pay_frequency
string
The income pay frequency.

Possible values: WEEKLY, BIWEEKLY, SEMI_MONTHLY, MONTHLY, UNKNOWN
total_amount
number
Total amount of earnings in the user’s bank account for the specific income source for days requested by the client.
transaction_count
integer
Number of transactions for the income source within the start and end date.
historical_summary
[object]
total_amount
number
Total amount of earnings for the income source(s) of the user for the month in the summary.
iso_currency_code
nullable string
The ISO 4217 currency code of the amount or balance.
unofficial_currency_code
nullable string
The unofficial currency code associated with the amount or balance. Always null if iso_currency_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.
start_date
string
The start date of the period covered in this monthly summary. This date will be the first day of the month, unless the month being covered is a partial month because it is the first month included in the summary and the date range being requested does not begin with the first day of the month. The date will be returned in an ISO 8601 format (YYYY-MM-DD).

Format: date
end_date
string
The end date of the period included in this monthly summary. This date will be the last day of the month, unless the month being covered is a partial month because it is the last month included in the summary and the date range being requested does not end with the last day of the month. The date will be returned in an ISO 8601 format (YYYY-MM-DD).

Format: date
transactions
[object]
amount
number
The settled value of the transaction, denominated in the transactions's currency as stated in iso_currency_code or unofficial_currency_code. Positive values when money moves out of the account; negative values when money moves in. For example, credit card purchases are positive; credit card payment, direct deposits, and refunds are negative.
date
string
For pending transactions, the date that the transaction occurred; for posted transactions, the date that the transaction posted. Both dates are returned in an ISO 8601 format (YYYY-MM-DD).

Format: date
name
string
The merchant name or transaction description.
original_description
nullable string
The string returned by the financial institution to describe the transaction.
pending
boolean
When true, identifies the transaction as pending or unsettled. Pending transaction details (name, type, amount, category ID) may change before they are settled.
transaction_id
string
The unique ID of the transaction. Like all Plaid identifiers, the transaction_id is case sensitive.
check_number
nullable string
The check number of the transaction. This field is only populated for check transactions.
iso_currency_code
nullable string
The ISO 4217 currency code of the amount or balance.
unofficial_currency_code
nullable 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_time
string
The time when this Item's data was last retrieved from the financial institution.

Format: date-time
institution_id
string
The unique identifier of the institution associated with the Item.
institution_name
string
The name of the institution associated with the Item.
item_id
string
The unique identifier for the Item.
bank_income_summary
object
Summary for bank income across all income sources and items (max history of 730 days).
total_amount
number
Total amount of earnings across all the income sources in the end user's Items for the days requested by the client.
iso_currency_code
nullable string
The ISO 4217 currency code of the amount or balance.
unofficial_currency_code
nullable string
The unofficial currency code associated with the amount or balance. Always null if iso_currency_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.
start_date
string
The earliest date within the days requested in which all income sources identified by Plaid appear in a user's account. The date will be returned in an ISO 8601 format (YYYY-MM-DD).

Format: date
end_date
string
The latest date in which all income sources identified by Plaid appear in the user's account. The date will be returned in an ISO 8601 format (YYYY-MM-DD).

Format: date
income_sources_count
integer
Number of income sources per end user.
income_categories_count
integer
Number of income categories per end user.
income_transactions_count
integer
Number of income transactions per end user.
historical_summary
[object]
total_amount
number
Total amount of earnings for the income source(s) of the user for the month in the summary.
iso_currency_code
nullable string
The ISO 4217 currency code of the amount or balance.
unofficial_currency_code
nullable string
The unofficial currency code associated with the amount or balance. Always null if iso_currency_code is non-null. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.
start_date
string
The start date of the period covered in this monthly summary. This date will be the first day of the month, unless the month being covered is a partial month because it is the first month included in the summary and the date range being requested does not begin with the first day of the month. The date will be returned in an ISO 8601 format (YYYY-MM-DD).

Format: date
end_date
string
The end date of the period included in this monthly summary. This date will be the last day of the month, unless the month being covered is a partial month because it is the last month included in the summary and the date range being requested does not end with the last day of the month. The date will be returned in an ISO 8601 format (YYYY-MM-DD).

Format: date
transactions
[object]
amount
number
The settled value of the transaction, denominated in the transactions's currency as stated in iso_currency_code or unofficial_currency_code. Positive values when money moves out of the account; negative values when money moves in. For example, credit card purchases are positive; credit card payment, direct deposits, and refunds are negative.
date
string
For pending transactions, the date that the transaction occurred; for posted transactions, the date that the transaction posted. Both dates are returned in an ISO 8601 format (YYYY-MM-DD).

Format: date
name
string
The merchant name or transaction description.
original_description
nullable string
The string returned by the financial institution to describe the transaction.
pending
boolean
When true, identifies the transaction as pending or unsettled. Pending transaction details (name, type, amount, category ID) may change before they are settled.
transaction_id
string
The unique ID of the transaction. Like all Plaid identifiers, the transaction_id is case sensitive.
check_number
nullable string
The check number of the transaction. This field is only populated for check transactions.
iso_currency_code
nullable string
The ISO 4217 currency code of the amount or balance.
unofficial_currency_code
nullable 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_type
string
The warning type which will always be BANK_INCOME_WARNING.

Possible values: BANK_INCOME_WARNING
warning_code
string
The warning code identifies a specific kind of warning. IDENTITY_UNAVAILABLE: Unable to extract identity for the Item TRANSACTIONS_UNAVAILABLE: Unable to extract transactions for the Item ITEM_UNAPPROVED: User 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
cause
object
An error object and associated item_id used to identify a specific Item and error when a batch operation operating on multiple Items has encountered an error in one of the Items.
error_type
string
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_code
string
We use standard HTTP response codes for success and failure notifications, and our errors are further classified by error_type. In general, 200 HTTP codes correspond to success, 40X codes are for developer- or user-related failures, and 50X codes are for Plaid-related issues. Error fields will be null if no error has occurred.
error_message
string
A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use.
display_message
string
A user-friendly representation of the error code. null if the error is not related to user action. This may change over time and is not safe for programmatic use.
item_id
string
The item_id of the Item associated with this warning.
request_id
string
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_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
user_token
string
The user token associated with the User data is being requested for.
1const request: CreditPayrollIncomeGetRequest = {
2  user_token: 'user-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d',
3};
4
5try {
6  const response = await client.creditPayrollIncomeGet(request);
7} catch (error) {
8  // handle error
9}
credit/payroll_income/get

Response fields and example

items
[object]
Array of payroll items.
item_id
string
The item_id of the Item associated with this webhook, warning, or error
institution_id
string
The unique identifier of the institution associated with the Item.
institution_name
string
The name of the institution associated with the Item.
accounts
[object]
account_id
nullable string
ID of the payroll provider account.
rate_of_pay
object
An object representing the rate at which an individual is paid.
pay_rate
nullable string
The rate at which an employee is paid.

Possible values: ANNUAL, HOURLY, CONTRACT, OTHER, null
pay_amount
nullable number
The amount at which an employee is paid.

Format: double
pay_frequency
nullable string
The frequency at which an individual is paid.

Possible values: DAILY, WEEKLY, BIWEEKLY, SEMI_MONTHLY, MONTHLY, CONTRACT, QUARTERLY, SEMI_ANNUALLY, ANNUALLY, OTHER, null
payroll_income
[object]
account_id
nullable string
ID of the payroll provider account.
pay_stubs
[object]
Array of pay stubs for the user.
deductions
object
An object with the deduction information found on a pay stub.
breakdown
[object]
current_amount
nullable number
Raw amount of the deduction

Format: double
description
nullable string
Description of the deduction line item
iso_currency_code
nullable string
The ISO-4217 currency code of the line item. Always null if unofficial_currency_code is non-null.
unofficial_currency_code
nullable 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_amount
nullable number
The year-to-date amount of the deduction

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

Format: double
iso_currency_code
nullable string
The ISO-4217 currency code of the line item. Always null if unofficial_currency_code is non-null.
unofficial_currency_code
nullable 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_amount
nullable number
The year-to-date total amount of the deductions

Format: double
document_id
nullable string
An identifier of the document referenced by the document metadata.
document_metadata
object
Object representing metadata pertaining to the document.
name
string
The name of the document.
document_type
nullable 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.
PLAID_GENERATED_PAYSTUB_PDF: Used to indicate that the PDF for the paystub was generated by Plaid.
NONE: Used to indicate that there is no underlying document for the data.
UNKNOWN: Document type could not be determined.

Possible values: UNKNOWN, PAYSTUB, BANK_STATEMENT, US_TAX_W2, US_MILITARY_ERAS, US_MILITARY_LES, US_MILITARY_CLES, GIG, PLAID_GENERATED_PAYSTUB_PDF, NONE
download_url
nullable string
Signed URL to retrieve the underlying file.
status
nullable string
The processing status of the document.
earnings
object
An object representing both a breakdown of earnings on a pay stub and the total earnings.
breakdown
[object]
canonical_description
nullable 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_amount
nullable number
Raw amount of the earning line item.

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

Format: double
unofficial_currency_code
nullable 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_amount
nullable number
The year-to-date amount of the deduction.

Format: double
total
object
An object representing both the current pay period and year to date amount for an earning category.
current_amount
nullable number
Total amount of the earnings for this pay period.

Format: double
hours
nullable number
Total number of hours worked for this pay period.
iso_currency_code
nullable string
The ISO-4217 currency code of the line item. Always null if unofficial_currency_code is non-null.
unofficial_currency_code
nullable 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_amount
nullable number
The total year-to-date amount of the earnings.

Format: double
employee
object
Data about the employee.
address
object
Address on the pay stub.
city
nullable string
The full city name.
country
nullable string
The ISO 3166-1 alpha-2 country code.
postal_code
nullable string
The postal code of the address.
region
nullable string
The region or state. Example: "NC"
street
nullable string
The full street address.
name
nullable string
The name of the employee.
marital_status
nullable string
Marital status of the employee - either SINGLE or MARRIED.

Possible values: SINGLE, MARRIED, null
taxpayer_id
object
Taxpayer ID of the individual receiving the paystub.
id_type
nullable string
Type of ID, e.g. 'SSN'.
id_mask
nullable string
ID mask; i.e. last 4 digits of the taxpayer ID.
employer
object
Information about the employer on the pay stub.
address
object
Address on the pay stub.
city
nullable string
The full city name.
country
nullable string
The ISO 3166-1 alpha-2 country code.
postal_code
nullable string
The postal code of the address.
region
nullable string
The region or state. Example: "NC"
street
nullable string
The full street address.
name
nullable string
The name of the employer on the pay stub.
net_pay
object
An object representing information about the net pay amount on the pay stub.
current_amount
nullable number
Raw amount of the net pay for the pay period.

Format: double
description
nullable string
Description of the net pay.
iso_currency_code
nullable string
The ISO-4217 currency code of the net pay. Always null if unofficial_currency_code is non-null.
unofficial_currency_code
nullable 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_amount
nullable number
The year-to-date amount of the net pay.

Format: double
pay_period_details
object
Details about the pay period.
pay_amount
nullable number
The amount of the paycheck.

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

Format: double
iso_currency_code
nullable string
The ISO-4217 currency code of the net pay. Always null if unofficial_currency_code is non-null.
mask
nullable string
The last 2-4 alphanumeric characters of an account's official account number.
type
nullable string
Type of the account that the paystub was sent to (e.g. 'checking').
unofficial_currency_code
nullable 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_date
nullable string
The date on which the pay period ended, in ISO 8601 format ("yyyy-mm-dd").

Format: date
gross_earnings
nullable number
Total earnings before tax/deductions.

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

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

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

Format: date
unofficial_currency_code
nullable 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.
w2s
[object]
Array of tax form W-2s.
document_metadata
object
Object representing metadata pertaining to the document.
name
string
The name of the document.
document_type
nullable 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.
PLAID_GENERATED_PAYSTUB_PDF: Used to indicate that the PDF for the paystub was generated by Plaid.
NONE: Used to indicate that there is no underlying document for the data.
UNKNOWN: Document type could not be determined.

Possible values: UNKNOWN, PAYSTUB, BANK_STATEMENT, US_TAX_W2, US_MILITARY_ERAS, US_MILITARY_LES, US_MILITARY_CLES, GIG, PLAID_GENERATED_PAYSTUB_PDF, NONE
download_url
nullable string
Signed URL to retrieve the underlying file.
status
nullable string
The processing status of the document.
document_id
string
An identifier of the document referenced by the document metadata.
employer
object
Information about the employer on the pay stub.
address
object
Address on the pay stub.
city
nullable string
The full city name.
country
nullable string
The ISO 3166-1 alpha-2 country code.
postal_code
nullable string
The postal code of the address.
region
nullable string
The region or state. Example: "NC"
street
nullable string
The full street address.
name
nullable string
The name of the employer on the pay stub.
employee
object
Data about the employee.
address
object
Address on the pay stub.
city
nullable string
The full city name.
country
nullable string
The ISO 3166-1 alpha-2 country code.
postal_code
nullable string
The postal code of the address.
region
nullable string
The region or state. Example: "NC"
street
nullable string
The full street address.
name
nullable string
The name of the employee.
marital_status
nullable string
Marital status of the employee - either SINGLE or MARRIED.

Possible values: SINGLE, MARRIED, null
taxpayer_id
object
Taxpayer ID of the individual receiving the paystub.
id_type
nullable string
Type of ID, e.g. 'SSN'.
id_mask
nullable string
ID mask; i.e. last 4 digits of the taxpayer ID.
tax_year
nullable string
The tax year of the W2 document.
employer_id_number
nullable string
An employee identification number or EIN.
wages_tips_other_comp
nullable string
Wages from tips and other compensation.
federal_income_tax_withheld
nullable string
Federal income tax withheld for the tax year.
social_security_wages
nullable string
Wages from social security.
social_security_tax_withheld
nullable string
Social security tax withheld for the tax year.
medicare_wages_and_tips
nullable string
Wages and tips from medicare.
medicare_tax_withheld
nullable string
Medicare tax withheld for the tax year.
social_security_tips
nullable string
Tips from social security.
allocated_tips
nullable string
Allocated tips.
box_9
nullable string
Contents from box 9 on the W2.
dependent_care_benefits
nullable string
Dependent care benefits.
nonqualified_plans
nullable string
Nonqualified plans.
box_12
[object]
code
nullable string
W2 Box 12 code.
amount
nullable string
W2 Box 12 amount.
statutory_employee
nullable string
Statutory employee.
retirement_plan
nullable string
Retirement plan.
third_party_sick_pay
nullable string
Third party sick pay.
other
nullable string
Other.
state_and_local_wages
[object]
state
nullable string
State associated with the wage.
employer_state_id_number
nullable string
State identification number of the employer.
state_wages_tips
nullable string
Wages and tips from the specified state.
state_income_tax
nullable string
Income tax from the specified state.
local_wages_tips
nullable string
Wages and tips from the locality.
local_income_tax
nullable string
Income tax from the locality.
locality_name
nullable string
Name of the locality.
form1099s
[object]
Array of tax form 1099s.
document_id
nullable string
An identifier of the document referenced by the document metadata.
document_metadata
object
Object representing metadata pertaining to the document.
name
string
The name of the document.
document_type
nullable 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.
PLAID_GENERATED_PAYSTUB_PDF: Used to indicate that the PDF for the paystub was generated by Plaid.
NONE: Used to indicate that there is no underlying document for the data.
UNKNOWN: Document type could not be determined.

Possible values: UNKNOWN, PAYSTUB, BANK_STATEMENT, US_TAX_W2, US_MILITARY_ERAS, US_MILITARY_LES, US_MILITARY_CLES, GIG, PLAID_GENERATED_PAYSTUB_PDF, NONE
download_url
nullable string
Signed URL to retrieve the underlying file.
status
nullable string
The processing status of the document.
form_1099_type
string
Form 1099 Type

Possible values: FORM_1099_TYPE_UNKNOWN, FORM_1099_TYPE_MISC, FORM_1099_TYPE_K
recipient
object
An object representing a recipient used in both 1099-K and 1099-MISC tax documents.
address
object
Address on the pay stub.
city
nullable string
The full city name.
country
nullable string
The ISO 3166-1 alpha-2 country code.
postal_code
nullable string
The postal code of the address.
region
nullable string
The region or state. Example: "NC"
street
nullable string
The full street address.
name
nullable string
Name of recipient.
tin
nullable string
Tax identification number of recipient.
account_number
nullable string
Account number number of recipient.
facta_filing_requirement
nullable string
Checked if FACTA is a filing requirement.

Possible values: CHECKED, NOT CHECKED
second_tin_exists
nullable string
Checked if 2nd TIN exists.

Possible values: CHECKED, NOT CHECKED
payer
object
An object representing a payer used by 1099-MISC tax documents.
address
object
Address on the pay stub.
city
nullable string
The full city name.
country
nullable string
The ISO 3166-1 alpha-2 country code.
postal_code
nullable string
The postal code of the address.
region
nullable string
The region or state. Example: "NC"
street
nullable string
The full street address.
name
nullable string
Name of payer.
tin
nullable string
Tax identification number of payer.
telephone_number
nullable string
Telephone number of payer.
filer
object
An object representing a filer used by 1099-K tax documents.
address
object
Address on the pay stub.
city
nullable string
The full city name.
country
nullable string
The ISO 3166-1 alpha-2 country code.
postal_code
nullable string
The postal code of the address.
region
nullable string
The region or state. Example: "NC"
street
nullable string
The full street address.
name
nullable string
Name of filer.
tin
nullable string
Tax identification number of filer.
type
nullable string
One of the following values will be provided: Payment Settlement Entity (PSE), Electronic Payment Facilitator (EPF), Other Third Party

Possible values: Payment Settlement Entity (PSE), Electronic Payment Facilitator (EPF), Other Third Party
tax_year
nullable string
Tax year of the tax form.
rents
nullable number
Amount in rent by payer.

Format: double
royalties
nullable number
Amount in royalties by payer.

Format: double
other_income
nullable number
Amount in other income by payer.

Format: double
federal_income_tax_withheld
nullable number
Amount of federal income tax withheld from payer.

Format: double
fishing_boat_proceeds
nullable number
Amount of fishing boat proceeds from payer.

Format: double
medical_and_healthcare_payments
nullable number
Amount of medical and healthcare payments from payer.

Format: double
nonemployee_compensation
nullable number
Amount of nonemployee compensation from payer.

Format: double
substitute_payments_in_lieu_of_dividends_or_interest
nullable number
Amount of substitute payments made by payer.

Format: double
payer_made_direct_sales_of_5000_or_more_of_consumer_products_to_buyer
nullable string
Whether or not payer made direct sales over $5000 of consumer products.
crop_insurance_proceeds
nullable number
Amount of crop insurance proceeds.

Format: double
excess_golden_parachute_payments
nullable number
Amount of golden parachute payments made by payer.

Format: double
gross_proceeds_paid_to_an_attorney
nullable number
Amount of gross proceeds paid to an attorney by payer.

Format: double
section_409a_deferrals
nullable number
Amount of 409A deferrals earned by payer.

Format: double
section_409a_income
nullable number
Amount of 409A income earned by payer.

Format: double
state_tax_withheld
nullable number
Amount of state tax withheld of payer for primary state.

Format: double
state_tax_withheld_lower
nullable number
Amount of state tax withheld of payer for secondary state.

Format: double
payer_state_number
nullable string
Primary state ID.
payer_state_number_lower
nullable string
Secondary state ID.
state_income
nullable number
State income reported for primary state.

Format: double
state_income_lower
nullable number
State income reported for secondary state.

Format: double
transactions_reported
nullable string
One of the values will be provided Payment card Third party network

Possible values: Payment card, Third party network
pse_name
nullable string
Name of the PSE (Payment Settlement Entity).
pse_telephone_number
nullable string
Formatted (XXX) XXX-XXXX. Phone number of the PSE (Payment Settlement Entity).
gross_amount
nullable number
Gross amount reported.

Format: double
card_not_present_transaction
nullable number
Amount in card not present transactions.

Format: double
merchant_category_code
nullable string
Merchant category of filer.
number_of_payment_transactions
nullable string
Number of payment transactions made.
january_amount
nullable number
Amount reported for January.

Format: double
february_amount
nullable number
Amount reported for February.

Format: double
march_amount
nullable number
Amount reported for March.

Format: double
april_amount
nullable number
Amount reported for April.

Format: double
may_amount
nullable number
Amount reported for May.

Format: double
june_amount
nullable number
Amount reported for June.

Format: double
july_amount
nullable number
Amount reported for July.

Format: double
august_amount
nullable number
Amount reported for August.

Format: double
september_amount
nullable number
Amount reported for September.

Format: double
october_amount
nullable number
Amount reported for October.

Format: double
november_amount
nullable number
Amount reported for November.

Format: double
december_amount
nullable number
Amount reported for December.

Format: double
primary_state
nullable string
Primary state of business.
secondary_state
nullable string
Secondary state of business.
primary_state_id
nullable string
Primary state ID.
secondary_state_id
nullable string
Secondary state ID.
primary_state_income_tax
nullable number
State income tax reported for primary state.

Format: double
secondary_state_income_tax
nullable number
State income tax reported for secondary state.

Format: double
status
nullable object
Details about the status of the payroll item.
processing_status
nullable string
Denotes the processing status for the verification.
UNKNOWN: The processing status could not be determined.
PROCESSING_COMPLETE: The processing has completed and the user has approved for sharing. The data is available to be retrieved.
PROCESSING: The verification is still processing. The data is not available yet.
FAILED: The processing failed to complete successfully.
APPROVAL_STATUS_PENDING: The processing has completed but the user has not yet approved the sharing of the data.

Possible values: UNKNOWN, PROCESSING_COMPLETE, PROCESSING, FAILED, APPROVAL_STATUS_PENDING
updated_at
nullable string
Timestamp in ISO 8601 format (YYYY-MM-DDTHH:mm:ssZ) indicating the last time that the Item was updated.

Format: date-time
error
nullable 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. An Item with a non-null error object will only be part of an API response when calling /item/get to view Item status. Otherwise, error fields will be null if no error has occurred; if an error has occurred, an error code will be returned instead.
error_type
string
A broad categorization of the error. Safe for programmatic use.

Possible values: INVALID_REQUEST, INVALID_RESULT, INVALID_INPUT, INSTITUTION_ERROR, RATE_LIMIT_EXCEEDED, API_ERROR, ITEM_ERROR, ASSET_REPORT_ERROR, RECAPTCHA_ERROR, OAUTH_ERROR, PAYMENT_ERROR, BANK_TRANSFER_ERROR, INCOME_VERIFICATION_ERROR, MICRODEPOSITS_ERROR
error_code
string
The particular error code. Safe for programmatic use.
error_message
string
A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use.
display_message
nullable 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_id
string
A unique ID identifying the request, to be used for troubleshooting purposes. This field will be omitted in errors provided by webhooks.
causes
array
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.
status
nullable 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_url
string
The URL of a Plaid documentation page with more information about the error
suggested_action
nullable string
Suggested steps for resolving the error
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "items": [
3    {
4      "item_id": "eVBnVMp7zdTJLkRNr33Rs6zr7KNJqBFL9DrE6",
5      "institution_id": "ins_92",
6      "institution_name": "ADP",
7      "accounts": [
8        {
9          "account_id": "GeooLPBGDEunl54q7N3ZcyD5aLPLEai1nkzM9",
10          "rate_of_pay": {
11            "pay_amount": 100000,
12            "pay_rate": "ANNUAL"
13          },
14          "pay_frequency": "BIWEEKLY"
15        }
16      ],
17      "payroll_income": [
18        {
19          "account_id": "GeooLPBGDEunl54q7N3ZcyD5aLPLEai1nkzM9",
20          "pay_stubs": [
21            {
22              "deductions": {
23                "breakdown": [
24                  {
25                    "current_amount": 123.45,
26                    "description": "taxes",
27                    "iso_currency_code": "USD",
28                    "unofficial_currency_code": null,
29                    "ytd_amount": 246.9
30                  }
31                ],
32                "total": {
33                  "current_amount": 123.45,
34                  "iso_currency_code": "USD",
35                  "unofficial_currency_code": null,
36                  "ytd_amount": 246.9
37                }
38              },
39              "document_metadata": {
40                "document_type": "PAYSTUB",
41                "name": "paystub.pdf",
42                "status": "PROCESSING_COMPLETE",
43                "download_url": null
44              },
45              "document_id": "2jkflanbd",
46              "earnings": {
47                "breakdown": [
48                  {
49                    "canonical_description": "REGULAR_PAY",
50                    "current_amount": 200.22,
51                    "description": "salary earned",
52                    "hours": 80,
53                    "iso_currency_code": "USD",
54                    "rate": null,
55                    "unofficial_currency_code": null,
56                    "ytd_amount": 400.44
57                  },
58                  {
59                    "canonical_description": "BONUS",
60                    "current_amount": 100,
61                    "description": "bonus earned",
62                    "hours": null,
63                    "iso_currency_code": "USD",
64                    "rate": null,
65                    "unofficial_currency_code": null,
66                    "ytd_amount": 100
67                  }
68                ],
69                "total": {
70                  "current_amount": 300.22,
71                  "hours": 160,
72                  "iso_currency_code": "USD",
73                  "unofficial_currency_code": null,
74                  "ytd_amount": 500.44
75                }
76              },
77              "employee": {
78                "address": {
79                  "city": "SAN FRANCISCO",
80                  "country": "US",
81                  "postal_code": "94133",
82                  "region": "CA",
83                  "street": "2140 TAYLOR ST"
84                },
85                "name": "ANNA CHARLESTON",
86                "marital_status": "SINGLE",
87                "taxpayer_id": {
88                  "id_type": "SSN",
89                  "id_mask": "3333"
90                }
91              },
92              "employer": {
93                "name": "PLAID INC",
94                "address": {
95                  "city": "SAN FRANCISCO",
96                  "country": "US",
97                  "postal_code": "94111",
98                  "region": "CA",
99                  "street": "1098 HARRISON ST"
100                }
101              },
102              "net_pay": {
103                "current_amount": 123.34,
104                "description": "TOTAL NET PAY",
105                "iso_currency_code": "USD",
106                "unofficial_currency_code": null,
107                "ytd_amount": 253.54
108              },
109              "pay_period_details": {
110                "distribution_breakdown": [
111                  {
112                    "account_name": "Big time checking",
113                    "bank_name": "bank of plaid",
114                    "current_amount": 176.77,
115                    "iso_currency_code": "USD",
116                    "mask": "1223",
117                    "type": "checking",
118                    "unofficial_currency_code": null
119                  }
120                ],
121                "end_date": "2020-12-15",
122                "gross_earnings": 4500,
123                "iso_currency_code": "USD",
124                "pay_amount": 1490.21,
125                "pay_date": "2020-12-15",
126                "pay_frequency": "BIWEEKLY",
127                "start_date": "2020-12-01",
128                "unofficial_currency_code": null
129              }
130            }
131          ],
132          "w2s": [
133            {
134              "allocated_tips": "1000",
135              "box_12": [
136                {
137                  "amount": "200",
138                  "code": "AA"
139                }
140              ],
141              "box_9": "box9",
142              "dependent_care_benefits": "1000",
143              "document_metadata": {
144                "document_type": "US_TAX_W2",
145                "download_url": null,
146                "name": "w_2.pdf",
147                "status": "PROCESSING_COMPLETE"
148              },
149              "document_id": "1pkflebk4",
150              "employee": {
151                "address": {
152                  "city": "San Francisco",
153                  "country": "US",
154                  "postal_code": "94103",
155                  "region": "CA",
156                  "street": "1234 Grand St"
157                },
158                "name": "Josie Georgia Harrison",
159                "marital_status": "SINGLE",
160                "taxpayer_id": {
161                  "id_type": "SSN",
162                  "id_mask": "1234"
163                }
164              },
165              "employer": {
166                "address": {
167                  "city": "New York",
168                  "country": "US",
169                  "postal_code": "10010",
170                  "region": "NY",
171                  "street": "456 Main St"
172                },
173                "name": "Acme Inc"
174              },
175              "employer_id_number": "12-1234567",
176              "federal_income_tax_withheld": "1000",
177              "medicare_tax_withheld": "1000",
178              "medicare_wages_and_tips": "1000",
179              "nonqualified_plans": "1000",
180              "other": "other",
181              "retirement_plan": "CHECKED",
182              "social_security_tax_withheld": "1000",
183              "social_security_tips": "1000",
184              "social_security_wages": "1000",
185              "state_and_local_wages": [
186                {
187                  "employer_state_id_number": "11111111111AAA",
188                  "local_income_tax": "200",
189                  "local_wages_and_tips": "200",
190                  "locality_name": "local",
191                  "state": "UT",
192                  "state_income_tax": "200",
193                  "state_wages_tips": "200"
194                }
195              ],
196              "statutory_employee": "CHECKED",
197              "tax_year": "2020",
198              "third_party_sick_pay": "CHECKED",
199              "wages_tips_other_comp": "1000"
200            }
201          ],
202          "form1099s": [
203            {
204              "april_amount": null,
205              "august_amount": null,
206              "card_not_present_transaction": null,
207              "crop_insurance_proceeds": 1000,
208              "december_amount": null,
209              "document_id": "mvMZ59Z2a5",
210              "document_metadata": {
211                "document_type": "US_TAX_1099_MISC",
212                "download_url": null,
213                "name": "form_1099_misc.pdf",
214                "status": "PROCESSING_COMPLETE"
215              },
216              "excess_golden_parachute_payments": 1000,
217              "feburary_amount": null,
218              "federal_income_tax_withheld": 1000,
219              "filer": {
220                "address": {
221                  "city": null,
222                  "country": null,
223                  "postal_code": null,
224                  "region": null,
225                  "street": null
226                },
227                "name": null,
228                "tin": null,
229                "type": null
230              },
231              "fishing_boat_proceeds": 1000,
232              "form_1099_type": "FORM_1099_TYPE_MISC",
233              "gross_amount": 1000,
234              "gross_proceeds_paid_to_an_attorney": 1000,
235              "january_amount": null,
236              "july_amount": null,
237              "june_amount": null,
238              "march_amount": null,
239              "may_amount": null,
240              "medical_and_healthcare_payments": 1000,
241              "merchant_category_code": null,
242              "nonemployee_compensation": 1000,
243              "november_amount": null,
244              "number_of_payment_transactions": null,
245              "october_amount": null,
246              "other_income": 1000,
247              "payer": {
248                "address": {
249                  "city": "SAN FRANCISCO",
250                  "country": "US",
251                  "postal_code": "94111",
252                  "region": "CA",
253                  "street": "1098 HARRISON ST"
254                },
255                "name": "PLAID INC",
256                "telephone_number": "(123)456-7890",
257                "tin": "12-3456789"
258              },
259              "payer_made_direct_sales_of_500_or_more_of_consumer_products_to_buyer": null,
260              "payer_state_number": "CA 12345",
261              "payer_state_number_lower": null,
262              "primary_state": null,
263              "primary_state_id": "CA 12345",
264              "primary_state_income_tax": 1000,
265              "pse_name": null,
266              "pse_telephone_number": null,
267              "recipient": {
268                "account_number": "45678",
269                "address": {
270                  "city": "SAN FRANCISCO",
271                  "country": "US",
272                  "postal_code": "94133",
273                  "region": "CA",
274                  "street": "2140 TAYLOR ST"
275                },
276                "facta_filing_requirement": "CHECKED",
277                "name": "Josie Georgia Harrison",
278                "second_tin_exists": "NOT CHECKED",
279                "tin": "12-3456789"
280              },
281              "rents": 1000,
282              "royalties": 1000,
283              "secondary_state": null,
284              "secondary_state_id": null,
285              "secondary_state_income_tax": null,
286              "section_409a_deferrals": 1000,
287              "section_409a_income": 1000,
288              "september_amount": null,
289              "state_income": 1000,
290              "state_income_lower": null,
291              "state_tax_withheld": 1000,
292              "state_tax_withheld_lower": null,
293              "substitute_payments_in_lieu_of_dividends_or_interest": null,
294              "tax_year": "2022",
295              "transactions_reported": null
296            }
297          ]
298        }
299      ],
300      "status": {
301        "processing_status": "PROCESSING_COMPLETE"
302      },
303      "updated_at": "2022-08-02T21:14:54Z"
304    }
305  ],
306  "request_id": "2pxQ59buGdsHRef"
307}

/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.
When testing in Sandbox, you can control the results by providing special test values in the employer and access_tokens fields. employer_good and employer_bad will result in HIGH and LOW confidence values, respectively. employer_multi will result in a HIGH confidence with multiple payroll options. Likewise, access_good and access_bad will result in HIGH and LOW confidence values, respectively. Any other value for employer and access_tokens in Sandbox will result in UNKNOWN confidence.

credit/payroll_income/precheck

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
user_token
string
The user token associated with the User data is being requested for.
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.
employer
object
Information about the end user's employer
name
string
The employer's name
address
object
Data about the components comprising an address.
city
string
The full city name
country
string
The ISO 3166-1 alpha-2 country code
postal_code
string
The postal code. In API versions 2018-05-22 and earlier, this field is called zip.
region
string
The region or state. In API versions 2018-05-22 and earlier, this field is called state. Example: "NC"
street
string
The full street address Example: "564 Main Street, APT 15"
tax_id
string
The employer's tax id
url
string
The URL for the employer's public website
us_military_info
object
Data about military info in the income verification precheck.
is_active_duty
boolean
Is the user currently active duty in the US military
branch
string
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'
payroll_institution
object
Information about the end user's payroll institution
name
string
The name of payroll institution
1const request: CreditPayrollIncomePrecheckRequest = {
2  user_token: 'user-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d',
3  employer: {
4    name: 'Elm Publishing',
5    address: {
6      city: 'New York',
7      country: 'US',
8      postal_code: '10012',
9      region: 'NY',
10      street: '123 Main Street',
11    },
12    tax_id: '12-3456789',
13    url: 'https://elmpublishing.com',
14  },
15  us_military_info: {
16    is_active_duty: true,
17    branch: 'ARMY',
18  },
19};
20
21try {
22  const response = await client.creditPayrollIncomePrecheck(request);
23} catch (error) {
24  // handle error
25}
credit/payroll_income/precheck

Response fields and example

request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
confidence
string
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_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
user_token
requiredstring
The user token associated with the User data is being requested for.
1const request: CreditEmploymentGetRequest = {
2  user_token: 'user-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d',
3};
4
5try {
6  const response = await client.creditEmploymentGet(request);
7} catch (error) {
8  // handle error
9}
credit/employment/get

Response fields and example

items
[object]
Array of employment items.
item_id
string
The item_id of the Item associated with this webhook, warning, or error
employments
[object]
account_id
nullable string
ID of the payroll provider account.
status
nullable string
Current employment status.

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

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

Format: date
employer
object
An object containing employer data.
name
nullable string
Name of employer.
title
nullable string
Current title of employee.
platform_ids
object
The object containing a set of ids related to an employee.
employee_id
nullable string
The ID of an employee as given by their employer.
payroll_id
nullable string
The ID of an employee as given by their payroll.
position_id
nullable string
The ID of the position of the employee.
employee_type
nullable string
The type of employment for the individual. "FULL_TIME": A full-time employee. "PART_TIME": A part-time employee. "CONTRACTOR": An employee typically hired externally through a contracting group. "TEMPORARY": A temporary employee. "OTHER": The employee type is not one of the above defined types.

Possible values: FULL_TIME, PART_TIME, CONTRACTOR, TEMPORARY, OTHER, null
last_paystub_date
nullable string
The date of the employee's most recent paystub in ISO 8601 format (YYYY-MM-DD).

Format: date
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "items": [
3    {
4      "item_id": "eVBnVMp7zdTJLkRNr33Rs6zr7KNJqBFL9DrE6",
5      "employments": [
6        {
7          "account_id": "GeooLPBGDEunl54q7N3ZcyD5aLPLEai1nkzM9",
8          "status": "ACTIVE",
9          "start_date": "2020-01-01",
10          "end_date": null,
11          "employer": {
12            "name": "Plaid Inc"
13          },
14          "title": "Software Engineer",
15          "platform_ids": {
16            "employee_id": "1234567",
17            "position_id": "8888",
18            "payroll_id": "1234567"
19          },
20          "employee_type": "FULL_TIME",
21          "last_paystub_date": "2022-01-15"
22        }
23      ]
24    }
25  ],
26  "request_id": "LhQf0THi8SH1yJm"
27}

/credit/sessions/get

Retrieve Link sessions for your user

This endpoint can be used for your end users after they complete the Link flow. This endpoint returns a list of Link sessions that your user completed, where each session includes the results from the Link flow.
These results include details about the Item that was created and some product related metadata (showing, for example, whether the user finished the bank income verification step).

credit/sessions/get

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
user_token
requiredstring
The user token associated with the User data is being requested for.
1const request: CreditSessionsGetRequest = {
2  user_token: 'user-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d',
3};
4
5try {
6  const response = await client.creditSessionsGet(request);
7} catch (error) {
8  // handle error
9}
credit/sessions/get

Response fields and example

sessions
[object]
A list of Link sessions for the user. Sessions will be sorted in reverse chronological order.
link_session_id
string
The unique identifier associated with the Link session. This identifier matches the link_session_id returned in the onSuccess/onExit callbacks.
session_start_time
string
The time when the Link session started

Format: date-time
results
object
The set of results for a Link session.
item_add_results
[object]
The set of item adds for the Link session.
public_token
string
Returned once a user has successfully linked their Item.
item_id
string
The Plaid Item ID. The item_id is always unique; linking the same account at the same institution twice will result in two Items with different item_id values. Like all Plaid identifiers, the item_id is case-sensitive.
institution_id
string
The Plaid Institution ID associated with the Item.
bank_income_results
[object]
The set of bank income verifications for the Link session.
status
string
The terminal status of the bank income verification.
APPROVED: User has approved and verified their income
NO_DEPOSITS_FOUND: We attempted, but were unable to find any income in the connected account.
USER_REPORTED_NO_INCOME: The user explicitly indicated that they don't receive income in the connected account.

Possible values: APPROVED, NO_DEPOSITS_FOUND, USER_REPORTED_NO_INCOME
item_id
string
The Plaid Item ID. The item_id is always unique; linking the same account at the same institution twice will result in two Items with different item_id values. Like all Plaid identifiers, the item_id is case-sensitive.
institution_id
string
The Plaid Institution ID associated with the Item.
payroll_income_results
[object]
The set of payroll income verifications for the Link session.
num_paystubs_retrieved
integer
The number of paystubs retrieved from a payroll provider.
num_w2s_retrieved
integer
The number of w2s retrieved from a payroll provider.
institution_id
string
The Plaid Institution ID associated with the Item.
institution_name
string
The Institution Name associated with the Item.
document_income_results
nullable object
The details of a document income verification in Link
num_paystubs_uploaded
integer
The number of paystubs uploaded by the user.
num_w2s_uploaded
integer
The number of w2s uploaded by the user.
errors
[object]
The set of errors that occurred during the Link session.
error_type
string
A broad categorization of the error.
error_code
string
The particular error code.
error_message
string
A developer-friendly representation of the error code.
display_message
nullable string
A user-friendly representation of the error code. null if the error is not related to user action.
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "request_id": "Aim3b",
3  "sessions": [
4    {
5      "link_session_id": "356dbb28-7f98-44d1-8e6d-0cec580f3171",
6      "results": {
7        "item_add_results": [
8          {
9            "public_token": "public-sandbox-5c224a01-8314-4491-a06f-39e193d5cddc",
10            "item_id": "M5eVJqLnv3tbzdngLDp9FL5OlDNxlNhlE55op",
11            "institution_id": "ins_56"
12          }
13        ],
14        "bank_income_results": [
15          {
16            "status": "APPROVED",
17            "item_id": "M5eVJqLnv3tbzdngLDp9FL5OlDNxlNhlE55op",
18            "institution_id": "ins_56"
19          }
20        ]
21      },
22      "session_start_time": "2022-09-30T23:40:30.946225Z"
23    },
24    {
25      "link_session_id": "f742cae8-31e4-49cc-a621-6cafbdb26fb9",
26      "results": {
27        "payroll_income_results": [
28          {
29            "num_paystubs_retrieved": 2,
30            "num_w2s_retrieved": 1,
31            "institution_id": "ins_92"
32          }
33        ]
34      },
35      "session_start_time": "2022-09-26T23:40:30.946225Z"
36    }
37  ]
38}

/user/create

Create user

This endpoint should be called for each of your end users before they begin a Plaid income flow. This provides you a single token to access all income data associated with the user. You should only create one per end user.
If you call the endpoint multiple times with the same client_user_id, the first creation call will succeed and the rest will fail with an error message indicating that the user has been created for the given client_user_id.
Ensure that you store the user_token along with your user's identifier in your database, as it is not possible to retrieve a previously created user_token.

user/create

Request fields and example

client_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
client_user_id
requiredstring
A unique ID representing the end user. Maximum of 128 characters. Typically this will be a user ID number from your application. Personally identifiable information, such as an email address or phone number, should not be used in the client_user_id.

Max length: 128
Min length: 1 
1const request: UserCreateRequest = {
2  client_user_id: 'user-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d',
3};
4
5try {
6  const response = await client.userCreate(request);
7} catch (error) {
8  // handle error
9}
user/create

Response fields and example

user_token
string
The user token associated with the User data is being requested for.
user_id
string
The Plaid user_id of the User associated with this webhook, warning, or error.
request_id
string
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_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
user
object
Information about the user whose eligibility is being evaluated.
first_name
string
The user's first name
last_name
string
The user's last name
email_address
string
The user's email address
home_address
object
Data about the components comprising an address.
city
string
The full city name
region
string
The region or state Example: "NC"
street
string
The full street address Example: "564 Main Street, APT 15"
postal_code
string
The postal code
country
string
The ISO 3166-1 alpha-2 country code
employer
object
Information about the end user's employer
name
string
The employer's name
address
object
Data about the components comprising an address.
city
string
The full city name
country
string
The ISO 3166-1 alpha-2 country code
postal_code
string
The postal code. In API versions 2018-05-22 and earlier, this field is called zip.
region
string
The region or state. In API versions 2018-05-22 and earlier, this field is called state. Example: "NC"
street
string
The full street address Example: "564 Main Street, APT 15"
tax_id
string
The employer's tax id
url
string
The URL for the employer's public website
payroll_institution
object
Information about the end user's payroll institution
name
string
The name of payroll institution
transactions_access_token
deprecatedstring
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_info
object
Data about military info in the income verification precheck.
is_active_duty
boolean
Is the user currently active duty in the US military
branch
string
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: 'Anne',
4    last_name: 'Charleston',
5    email_address: 'acharleston@email.com',
6    home_address: {
7      street: '123 Main St.',
8      city: 'San Francisco',
9      region: 'CA',
10      postal_code: '94053',
11      country: 'US',
12    },
13  },
14  employer: {
15    name: 'Plaid Inc.',
16    tax_id: '123-45-6709',
17    address: {
18      street: '234 Work St.',
19      city: 'San Francisco',
20      region: 'CA',
21      postal_code: '94053',
22      country: 'US',
23    },
24    url: 'http://www.employer.com',
25  },
26};
27try {
28  const response = await plaidClient.incomeVerificationPrecheck(request);
29} catch (error) {
30  // handle error
31}
income/verification/precheck

Response fields and example

precheck_id
string
ID of the precheck. Provide this value when calling /link/token/create in order to optimize Link conversion.
request_id
string
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
confidence
string
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_id
string
Your Plaid API client_id. The client_id is required and may be provided either in the PLAID-CLIENT-ID header or as part of a request body.
secret
string
Your Plaid API secret. The secret is required and may be provided either in the PLAID-SECRET header or as part of a request body.
income_verification_id
deprecatedstring
The ID of the verification for which to get paystub information.
access_token
string
The access token associated with the Item data is being requested for.
1const request: IncomeVerificationPaystubsGetRequest = {
2  client_id: clientId,
3  secret: secret,
4  access_token: accessToken,
5};
6try {
7  const response = await plaidClient.incomeVerificationPaystubsGet(request);
8} catch (error) {
9  // handle error
10}
income/verification/paystubs/get

Response fields and example

document_metadata
[object]
Metadata for an income document.
name
string
The name of the document.
status
string
The processing status of the document.
doc_id
string
An identifier of the document that is also present in the paystub response.
doc_type
string
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 Statement (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.
DOCUMENT_TYPE_PLAID_GENERATED_PAYSTUB_PDF: Used to indicate that the PDF for the paystub was generated by Plaid.
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, DOCUMENT_TYPE_US_TAX_1099_MISC, DOCUMENT_TYPE_US_TAX_1099_K, DOCUMENT_TYPE_PLAID_GENERATED_PAYSTUB_PDF
paystubs
[object]
deductions
object
An object with the deduction information found on a paystub.
subtotals
deprecated[object]
canonical_description
nullable 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
description
nullable string
Text of the line item as printed on the paystub.
current_pay
deprecatedobject
An object representing a monetary amount.
amount
nullable number
A numerical amount of a specific currency.

Format: double
currency
nullable string
Currency code, e.g. USD
ytd_pay
deprecatedobject
An object representing a monetary amount.
amount
nullable number
A numerical amount of a specific currency.

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

Format: double
description
nullable string
Description of the deduction line item
iso_currency_code
nullable string
The ISO-4217 currency code of the line item. Always null if unofficial_currency_code is non-null.
unofficial_currency_code
nullable 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_amount
nullable number
The year-to-date amount of the deduction

Format: double
totals
deprecated[object]
canonical_description
nullable 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
description
nullable string
Text of the line item as printed on the paystub.
current_pay
deprecatedobject
An object representing a monetary amount.
amount
nullable number
A numerical amount of a specific currency.

Format: double
currency
nullable string
Currency code, e.g. USD
ytd_pay
deprecatedobject
An object representing a monetary amount.
amount
nullable number
A numerical amount of a specific currency.

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

Format: double
iso_currency_code
nullable string
The ISO-4217 currency code of the line item. Always null if unofficial_currency_code is non-null.
unofficial_currency_code
nullable 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_amount
nullable number
The year-to-date total amount of the deductions

Format: double
doc_id
string
An identifier of the document referenced by the document metadata.
earnings
object
An object representing both a breakdown of earnings on a paystub and the total earnings.
subtotals
deprecated[object]
current_amount
nullable number
Total amount of the earnings for this pay period

Format: double
current_pay
deprecatedobject
An object representing a monetary amount.
amount
nullable number
A numerical amount of a specific currency.

Format: double
currency
nullable string
Currency code, e.g. USD
ytd_pay
deprecatedobject
An object representing a monetary amount.
amount
nullable number
A numerical amount of a specific currency.

Format: double
currency
nullable string
Currency code, e.g. USD
hours
nullable number
Total number of hours worked for this pay period
iso_currency_code
nullable string
The ISO-4217 currency code of the line item. Always null if unofficial_currency_code is non-null.
unofficial_currency_code