Income
API reference for Income endpoints and webhooks
Verify a user's income via payroll or bank account data.
Endpoints | |
---|---|
/credit/bank_income/get | Retrieve information from the bank accounts used for income verification |
/credit/bank_income/pdf/get | Retrieve information from the bank accounts used for income verification in PDF format |
/credit/bank_income/refresh | Refresh a user's bank income information |
/credit/bank_income/webhook/update | Subscribe and unsubscribe to proactive notifications for a user's income profile |
/credit/bank_statements/uploads/get | Retrieve information from the bank statements used for income verification |
/credit/payroll_income/get | Retrieve information from the pay stubs or tax forms used for income verification |
/credit/payroll_income/precheck | Check digital income verification eligibility and optimize conversion |
/credit/payroll_income/risk_signals/get | Analyze uploaded income documents for indications of potential fraud |
/credit/employment/get | (Beta) Retrieve employment information about the end user |
/credit/sessions/get | Get Link session metadata and results for the end user |
/user/create | Create a user for use with the income verification product |
See also | |
---|---|
/sandbox/income/fire_webhook | Manually fire an Income webhook (Sandbox only) |
Webhooks | |
---|---|
INCOME_VERIFICATION | Income verification has completed |
INCOME_VERIFICATION_RISK_SIGNALS | Risk evaluation of user-uploaded documents has completed |
BANK_INCOME_REFRESH_UPDATE | A change to user's income has been detected |
BANK_INCOME_REFRESH_COMPLETE | The refreshed report has finished generating |
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.
Request fields and example
client_id
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
secret
. The secret
is required and may be provided either in the PLAID-SECRET
header or as part of a request body.user_token
options
/credit/bank_income/get
request options.count
1
1const request: CreditBankIncomeGetRequest = {2 user_token: 'user-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d',3 options: {4 count: 1,5 },6};78try {9 const response = await client.creditBankIncomeGet(request);10} catch (error) {11 // handle error12}
Response fields and example
bank_income
bank_income_id
generated_time
date-time
days_requested
items
bank_income_accounts
account_id
mask
name
official_name
subtype
checking
, savings
, hsa
, cd
, money market
, paypal
, prepaid
, cash management
, ebt
, all
type
depository
.depository
owners
names
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
emails
addresses
data
city
region
state
.
Example: "NC"
street
"564 Main Street, APT 15"
postal_code
zip
.country
primary
true
, identifies the address as the primary address on an account.bank_income_sources
income_source_id
income_description
income_category
CASH
value has been deprecated and is used only for existing legacy implementations. It has been replaced by the new categories CASH_DEPOSIT
(representing cash or check deposits) and TRANSFER_FROM_APPLICATION
(representing cash transfers originating from apps, such as Zelle or Venmo).SALARY
, UNEMPLOYMENT
, CASH
, GIG_ECONOMY
, RENTAL
, CHILD_SUPPORT
, MILITARY
, RETIREMENT
, LONG_TERM_DISABILITY
, BANK_INTEREST
, CASH_DEPOSIT
, TRANSFER_FROM_APPLICATION
, TAX_REFUND
, BENEFIT_OTHER
, OTHER
account_id
start_date
date
end_date
date
pay_frequency
WEEKLY
, BIWEEKLY
, SEMI_MONTHLY
, MONTHLY
, DAILY
, UNKNOWN
total_amount
transaction_count
historical_summary
total_amount
total_amounts
instead.iso_currency_code
total_amounts
instead.unofficial_currency _code
null
if iso_currency_code
is non-null.
Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.
Please use total_amounts
instead.total_amounts
amount
iso_currency_code
unofficial_currency _code
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
date
end_date
date
transactions
amount
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
date
name
original_description
pending
transaction_id
transaction_id
is case sensitive.check_number
iso_currency_code
unofficial_currency _code
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
date-time
institution_id
institution_name
item_id
bank_income_summary
total_amount
total_amounts
instead.iso_currency_code
total_amounts
instead.unofficial_currency _code
null
if iso_currency_code
is non-null.
Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.
Please use total_amounts
instead.total_amounts
amount
iso_currency_code
unofficial_currency _code
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
date
end_date
date
income_sources_count
income_categories _count
income_transactions _count
historical_summary
total_amount
total_amounts
instead.iso_currency_code
total_amounts
instead.unofficial_currency _code
null
if iso_currency_code
is non-null.
Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries.
Please use total_amounts
instead.total_amounts
amount
iso_currency_code
unofficial_currency _code
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
date
end_date
date
transactions
amount
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
date
name
original_description
pending
transaction_id
transaction_id
is case sensitive.check_number
iso_currency_code
unofficial_currency _code
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
warning_type
BANK_INCOME_WARNING
.BANK_INCOME_WARNING
warning_code
IDENTITY_UNAVAILABLE
: Unable to extract identity for the Item
TRANSACTIONS_UNAVAILABLE
: Unable to extract transactions for the Item
ITEM_UNAPPROVED
: User exited flow before giving permission to share data for the Item
REPORT_DELETED
: Report deleted due to customer or consumer request
DATA_UNAVAILABLE
: No relevant data was found for the ItemIDENTITY_UNAVAILABLE
, TRANSACTIONS_UNAVAILABLE
, ITEM_UNAPPROVED
, REPORT_DELETED
, DATA_UNAVAILABLE
cause
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
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
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
display_message
item_id
item_id
of the Item associated with this warning.request_id
1{2 "request_id": "LhQf0THi8SH1yJm",3 "bank_income": [4 {5 "bank_income_id": "abc123",6 "generated_time": "2022-01-31T22:47:53Z",7 "days_requested": 90,8 "items": [9 {10 "last_updated_time": "2022-01-31T22:47:53Z",11 "institution_id": "ins_0",12 "institution_name": "Plaid Bank",13 "item_id": "“eVBnVMp7zdTJLkRNr33Rs6zr7KNJqBFL9DrE6”",14 "bank_income_accounts": [15 {16 "account_id": "“GeooLPBGDEunl54q7N3ZcyD5aLPLEai1nkzM9”",17 "mask": "8888",18 "name": "Plaid Checking Account",19 "official_name": "Plaid Checking Account",20 "type": "depository",21 "subtype": "checking",22 "owners": [23 {24 "addresses": [25 {26 "data": {27 "city": "Malakoff",28 "country": "US",29 "postal_code": "14236",30 "region": "NY",31 "street": "2992 Cameron Road"32 },33 "primary": true34 },35 {36 "data": {37 "city": "San Matias",38 "country": "US",39 "postal_code": "93405-2255",40 "region": "CA",41 "street": "2493 Leisure Lane"42 },43 "primary": false44 }45 ],46 "emails": [47 {48 "data": "accountholder0@example.com",49 "primary": true,50 "type": "primary"51 },52 {53 "data": "accountholder1@example.com",54 "primary": false,55 "type": "secondary"56 },57 {58 "data": "extraordinarily.long.email.username.123456@reallylonghostname.com",59 "primary": false,60 "type": "other"61 }62 ],63 "names": [64 "Alberta Bobbeth Charleson"65 ],66 "phone_numbers": [67 {68 "data": "1112223333",69 "primary": false,70 "type": "home"71 },72 {73 "data": "1112224444",74 "primary": false,75 "type": "work"76 },77 {78 "data": "1112225555",79 "primary": false,80 "type": "mobile"81 }82 ]83 }84 ]85 }86 ],87 "bank_income_sources": [88 {89 "account_id": "GeooLPBGDEunl54q7N3ZcyD5aLPLEai1nkzM9",90 "income_source_id": "“f17efbdd-caab-4278-8ece-963511cd3d51”",91 "income_description": "“PLAID_INC_DIRECT_DEP_PPD”",92 "income_category": "SALARY",93 "start_date": "2021-11-15",94 "end_date": "2022-01-15",95 "pay_frequency": "MONTHLY",96 "total_amount": 300,97 "transaction_count": 1,98 "historical_summary": [99 {100 "start_date": "2021-11-02",101 "end_date": "2021-11-30",102 "total_amount": 100,103 "iso_currency_code": "USD",104 "unofficial_currency_code": null,105 "total_amounts": [106 {107 "amount": 100,108 "iso_currency_code": "USD",109 "unofficial_currency_code": null110 }111 ],112 "transactions": [113 {114 "amount": -100,115 "date": "2021-11-15",116 "name": "“PLAID_INC_DIRECT_DEP_PPD”",117 "original_description": "PLAID_INC_DIRECT_DEP_PPD 123",118 "pending": false,119 "transaction_id": "6RddrWNwE1uM63Ex5GKLhzlBl76aAZfgzlQNm",120 "check_number": null,121 "iso_currency_code": "USD",122 "unofficial_currency_code": null123 }124 ]125 },126 {127 "start_date": "2021-12-01",128 "end_date": "2021-12-31",129 "total_amount": 100,130 "iso_currency_code": "USD",131 "unofficial_currency_code": null,132 "total_amounts": [133 {134 "amount": 100,135 "iso_currency_code": "USD",136 "unofficial_currency_code": null137 }138 ],139 "transactions": [140 {141 "amount": -100,142 "date": "2021-12-15",143 "name": "“PLAID_INC_DIRECT_DEP_PPD”",144 "original_description": "PLAID_INC_DIRECT_DEP_PPD 123",145 "pending": false,146 "transaction_id": "7BddrWNwE1uM63Ex5GKLhzlBl82aAZfgzlCBl",147 "check_number": null,148 "iso_currency_code": "USD",149 "unofficial_currency_code": null150 }151 ]152 },153 {154 "start_date": "2022-01-01",155 "end_date": "2021-01-31",156 "total_amount": 100,157 "iso_currency_code": "USD",158 "unofficial_currency_code": null,159 "total_amounts": [160 {161 "amount": 100,162 "iso_currency_code": "USD",163 "unofficial_currency_code": null164 }165 ],166 "transactions": [167 {168 "amount": -100,169 "date": "2022-01-31",170 "name": "“PLAID_INC_DIRECT_DEP_PPD”",171 "original_description": "PLAID_INC_DIRECT_DEP_PPD 123",172 "pending": false,173 "transaction_id": "9FddrWNwE1uM95Ex5GKLhzlBl76aAZfgzlNQr",174 "check_number": null,175 "iso_currency_code": "USD",176 "unofficial_currency_code": null177 }178 ]179 }180 ]181 }182 ]183 }184 ],185 "bank_income_summary": {186 "total_amount": 300,187 "iso_currency_code": "USD",188 "unofficial_currency_code": null,189 "total_amounts": [190 {191 "amount": 300,192 "iso_currency_code": "USD",193 "unofficial_currency_code": null194 }195 ],196 "start_date": "2021-11-15",197 "end_date": "2022-01-15",198 "income_sources_count": 1,199 "income_categories_count": 1,200 "income_transactions_count": 1,201 "historical_summary": [202 {203 "start_date": "2021-11-02",204 "end_date": "2021-11-30",205 "total_amount": 100,206 "iso_currency_code": "USD",207 "unofficial_currency_code": null,208 "total_amounts": [209 {210 "amount": 100,211 "iso_currency_code": "USD",212 "unofficial_currency_code": null213 }214 ],215 "transactions": [216 {217 "amount": -100,218 "date": "2021-11-15",219 "name": "“PLAID_INC_DIRECT_DEP_PPD”",220 "original_description": "PLAID_INC_DIRECT_DEP_PPD 123",221 "pending": false,222 "transaction_id": "6RddrWNwE1uM63Ex5GKLhzlBl76aAZfgzlQNm",223 "check_number": null,224 "iso_currency_code": "USD",225 "unofficial_currency_code": null226 }227 ]228 },229 {230 "start_date": "2021-12-01",231 "end_date": "2021-12-31",232 "total_amount": 100,233 "iso_currency_code": "USD",234 "unofficial_currency_code": null,235 "total_amounts": [236 {237 "amount": 100,238 "iso_currency_code": "USD",239 "unofficial_currency_code": null240 }241 ],242 "transactions": [243 {244 "amount": -100,245 "date": "2021-12-15",246 "name": "“PLAID_INC_DIRECT_DEP_PPD”",247 "original_description": "PLAID_INC_DIRECT_DEP_PPD 123",248 "pending": false,249 "transaction_id": "7BddrWNwE1uM63Ex5GKLhzlBl82aAZfgzlCBl",250 "check_number": null,251 "iso_currency_code": "USD",252 "unofficial_currency_code": null253 }254 ]255 },256 {257 "start_date": "2022-01-01",258 "end_date": "2021-01-31",259 "total_amount": 100,260 "iso_currency_code": "USD",261 "unofficial_currency_code": null,262 "total_amounts": [263 {264 "amount": 100,265 "iso_currency_code": "USD",266 "unofficial_currency_code": null267 }268 ],269 "transactions": [270 {271 "amount": -100,272 "date": "2022-01-31",273 "name": "“PLAID_INC_DIRECT_DEP_PPD”",274 "original_description": "PLAID_INC_DIRECT_DEP_PPD 123",275 "pending": false,276 "transaction_id": "9FddrWNwE1uM95Ex5GKLhzlBl76aAZfgzlNQr",277 "check_number": null,278 "iso_currency_code": "USD",279 "unofficial_currency_code": null280 }281 ]282 }283 ]284 },285 "warnings": []286 }287 ]288}
Was this helpful?
/credit/bank_income/pdf/get
Retrieve information from the bank accounts used for income verification in PDF format
/credit/bank_income/pdf/get
returns the most recent bank income report for a specified user in PDF format.
Request fields and example
client_id
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
secret
. The secret
is required and may be provided either in the PLAID-SECRET
header or as part of a request body.user_token
1const request: CreditBankIncomePDFGetRequest = {2 user_token: 'user-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d',3};45try {6 const response = await client.creditBankIncomePdfGet(request, {7 responseType: 'arraybuffer',8 });9 const pdf = response.buffer.toString('base64');10} catch (error) {11 // handle error12}
Response
This endpoint returns binary PDF data. View a sample Bank Income PDF.
/credit/bank_income/refresh
Refresh a user's bank income information
/credit/bank_income/refresh
refreshes the bank income report data for a specific user.
Request fields and example
client_id
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
secret
. The secret
is required and may be provided either in the PLAID-SECRET
header or as part of a request body.user_token
options
/credit/bank_income/refresh
request options.days_requested
1const request: CreditBankIncomeRefreshRequest = {2 user_token: 'user-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d',3 options: {4 days_requested: 90,5 },6};78try {9 const response = await client.creditBankIncomeRefresh(request);10} catch (error) {11 // handle error12}
Response fields and example
request_id
1{2 "request_id": "LhQf0THi8SH1yJm"3}
Was this helpful?
/credit/bank_income/webhook/update
Subscribe and unsubscribe to proactive notifications for a user's income profile
/credit/bank_income/webhook/update
allows you to subscribe or unsubscribe a user for income webhook notifications.
If a user is subscribed, on significant changes to the user's income profile, you will receive a BANK_INCOME_REFRESH_UPDATE
webhook, prompting you to refresh bank income data for the user.
Request fields and example
client_id
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
secret
. The secret
is required and may be provided either in the PLAID-SECRET
header or as part of a request body.user_token
enable_webhooks
1const request: CreditBankIncomeWebhookUpdateRequest = {2 user_token: 'user-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d',3 enable_webhooks: true,4};56try {7 const response = await client.creditBankIncomeWebhookUpdateRequest(request);8} catch (error) {9 // handle error10}
Response fields and example
request_id
1{2 "request_id": "LhQf0THi8SH1yJm"3}
Was this helpful?
/credit/bank_statements/uploads/get
Retrieve data for a user's uploaded bank statements
/credit/bank_statements/uploads/get
returns data from user-uploaded bank statements.
Request fields and example
client_id
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
secret
. The secret
is required and may be provided either in the PLAID-SECRET
header or as part of a request body.user_token
1const request: CreditBankStatementsUploadsGetRequest = {2 user_token: 'user-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d',3};45try {6 const response = await client.creditBankStatementsUploadsGet(request);7} catch (error) {8 // handle error9}
Response fields and example
items
item_id
item_id
of the Item associated with this webhook, warning, or errorbank_statements
transactions
amount
date
date
original_description
account_id
document_metadata
name
document_type
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.UNKNOWN
, PAYSTUB
, BANK_STATEMENT
, US_TAX_W2
, US_MILITARY_ERAS
, US_MILITARY_LES
, US_MILITARY_CLES
, GIG
, PLAID_GENERATED_PAYSTUB_PDF
, NONE
download_url
/credit/payroll_income/get
again.status
PROCESSING_COMPLETE
: The document was successfully processed.DOCUMENT_ERROR
: The document could not be processed. Possible causes include: The document was an unacceptable document type such as an offer letter or bank statement, the document image was cropped or blurry, or the document was corrupted.UNKNOWN
or null
: An internal error occurred. If this happens repeatedly, contact support or your Plaid account manager.UNKNOWN
, PROCESSING_COMPLETE
, DOCUMENT_ERROR
, null
page_count
document_id
bank_accounts
name
bank_name
account_type
account_number
periods
start_date
date
end_date
date
starting_balance
ending_balance
account_id
status
processing_status
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.UNKNOWN
, PROCESSING_COMPLETE
, PROCESSING
, FAILED
, APPROVAL_STATUS_PENDING
updated_at
date-time
request_id
1{2 "items": [3 {4 "item_id": "eVBnVMp7zdTJLkRNr33Rs6zr7KNJqBFL9DrE6",5 "bank_statements": [6 {7 "transactions": [8 {9 "amount": -1000,10 "date": "2023-01-01",11 "original_description": "PAYCHECK",12 "account_id": "c6778d3f-e44c-4348-874e-71507c1ac12d"13 }14 ],15 "document_metadata": {16 "document_type": "BANK_STATEMENT",17 "name": "statement_01.pdf",18 "status": "PROCESSING_COMPLETE",19 "download_url": null,20 "page_count": 221 },22 "document_id": "2jkflanbd",23 "bank_accounts": [24 {25 "name": "CHASE CHECKING",26 "bank_name": "CHASE",27 "account_type": "CHECKING",28 "account_number": "000009752",29 "account_id": "c6778d3f-e44c-4348-874e-71507c1ac12d",30 "owner": {31 "name": "JANE DOE",32 "address": {33 "postal_code": "94133",34 "country": "US",35 "region": "CA",36 "city": "SAN FRANCISCO",37 "street": "2140 TAYLOR ST"38 }39 },40 "periods": [41 {42 "start_date": "2023-01-01",43 "end_date": "2023-02-01",44 "starting_balance": 2500,45 "ending_balance": 350046 }47 ]48 }49 ]50 }51 ],52 "status": {53 "processing_status": "PROCESSING_COMPLETE"54 },55 "updated_at": "2023-02-01T21:14:54Z"56 }57 ],58 "request_id": "LhQf0THi8SH1yJm"59}
Was this helpful?
/credit/payroll_income/get
Retrieve a user's payroll information
This endpoint gets payroll income information for a specific user, either as a result of the user connecting to their payroll provider or uploading a pay related document.
credit/payroll_income/getRequest fields and example
client_id
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
secret
. The secret
is required and may be provided either in the PLAID-SECRET
header or as part of a request body.user_token
1const request: CreditPayrollIncomeGetRequest = {2 user_token: 'user-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d',3};45try {6 const response = await client.creditPayrollIncomeGet(request);7} catch (error) {8 // handle error9}
Response fields and example
items
item_id
item_id
of the Item associated with this webhook, warning, or errorinstitution_id
institution_name
accounts
account_id
rate_of_pay
pay_rate
ANNUAL
, HOURLY
, CONTRACT
, WEEKLY
, BI_WEEKLY
, MONTHLY
, SEMI_MONTHLY
, DAILY
, COMMISSION
, OTHER
, null
pay_amount
double
pay_frequency
DAILY
, WEEKLY
, BIWEEKLY
, SEMI_MONTHLY
, MONTHLY
, CONTRACT
, QUARTERLY
, SEMI_ANNUALLY
, ANNUALLY
, OTHER
, null
payroll_income
account_id
pay_stubs
deductions
breakdown
current_amount
double
description
iso_currency_code
null
if unofficial_currency_code
is non-null.unofficial_currency _code
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_code
s.ytd_amount
double
total
current_amount
double
iso_currency_code
null
if unofficial_currency_code
is non-null.unofficial_currency _code
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_code
s.ytd_amount
double
document_id
document_metadata
name
document_type
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.UNKNOWN
, PAYSTUB
, BANK_STATEMENT
, US_TAX_W2
, US_MILITARY_ERAS
, US_MILITARY_LES
, US_MILITARY_CLES
, GIG
, PLAID_GENERATED_PAYSTUB_PDF
, NONE
download_url
/credit/payroll_income/get
again.status
PROCESSING_COMPLETE
: The document was successfully processed.DOCUMENT_ERROR
: The document could not be processed. Possible causes include: The document was an unacceptable document type such as an offer letter or bank statement, the document image was cropped or blurry, or the document was corrupted.UNKNOWN
or null
: An internal error occurred. If this happens repeatedly, contact support or your Plaid account manager.UNKNOWN
, PROCESSING_COMPLETE
, DOCUMENT_ERROR
, null
page_count
earnings
breakdown
canonical_description
BONUS
, COMMISSION
, OVERTIME
, PAID_TIME_OFF
, REGULAR_PAY
, VACATION
, BASIC_ALLOWANCE_HOUSING
, BASIC_ALLOWANCE_SUBSISTENCE
, OTHER
, ALLOWANCE
, BEREAVEMENT
, HOLIDAY_PAY
, JURY_DUTY
, LEAVE
, LONG_TERM_DISABILITY_PAY
, MILITARY_PAY
, PER_DIEM
, REFERRAL_BONUS
, REIMBURSEMENTS
, RETENTION_BONUS
, RETROACTIVE_PAY
, SEVERANCE_PAY
, SHIFT_DIFFERENTIAL
, SHORT_TERM_DISABILITY_PAY
, SICK_PAY
, SIGNING_BONUS
, TIPS_INCOME
, null
current_amount
double
description
hours
iso_currency_code
null
if unofficial_currency_code
is non-null.rate
double
unofficial_currency _code
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_code
s.ytd_amount
double
total
current_amount
double
hours
iso_currency_code
null
if unofficial_currency_code
is non-null.unofficial_currency _code
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_code
s.ytd_amount
double
employee
name
marital_status
SINGLE
or MARRIED
or NOT LISTED
.SINGLE
, MARRIED
, NOT LISTED
, null
taxpayer_id
net_pay
current_amount
double
description
iso_currency_code
null
if unofficial_currency_code
is non-null.unofficial_currency _code
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_code
s.ytd_amount
double
pay_period_details
pay_amount
double
distribution_breakdown
account_name
bank_name
current_amount
double
iso_currency_code
null
if unofficial_currency_code
is non-null.mask
type
unofficial_currency _code
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_code
s.gross_earnings
double
iso_currency_code
null
if unofficial_currency_code
is non-null.pay_frequency
UNKNOWN
, WEEKLY
, BIWEEKLY
, SEMI_MONTHLY
, MONTHLY
, null
pay_basis
SALARY
, HOURLY
, COMMISSION
start_date
unofficial_currency _code
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_code
s.w2s
document_metadata
name
document_type
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.UNKNOWN
, PAYSTUB
, BANK_STATEMENT
, US_TAX_W2
, US_MILITARY_ERAS
, US_MILITARY_LES
, US_MILITARY_CLES
, GIG
, PLAID_GENERATED_PAYSTUB_PDF
, NONE
download_url
/credit/payroll_income/get
again.status
PROCESSING_COMPLETE
: The document was successfully processed.DOCUMENT_ERROR
: The document could not be processed. Possible causes include: The document was an unacceptable document type such as an offer letter or bank statement, the document image was cropped or blurry, or the document was corrupted.UNKNOWN
or null
: An internal error occurred. If this happens repeatedly, contact support or your Plaid account manager.UNKNOWN
, PROCESSING_COMPLETE
, DOCUMENT_ERROR
, null
page_count
document_id
employee
name
marital_status
SINGLE
or MARRIED
or NOT LISTED
.SINGLE
, MARRIED
, NOT LISTED
, null
taxpayer_id
tax_year
employer_id_number
wages_tips_other_comp
federal_income_tax _withheld
social_security_wages
social_security_tax _withheld
medicare_wages_and _tips
medicare_tax_withheld
social_security_tips
allocated_tips
box_9
dependent_care _benefits
nonqualified_plans
statutory_employee
retirement_plan
third_party_sick_pay
other
state_and_local_wages
state
employer_state_id _number
state_wages_tips
state_income_tax
local_wages_tips
local_income_tax
locality_name
form1099s
document_id
document_metadata
name
document_type
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.UNKNOWN
, PAYSTUB
, BANK_STATEMENT
, US_TAX_W2
, US_MILITARY_ERAS
, US_MILITARY_LES
, US_MILITARY_CLES
, GIG
, PLAID_GENERATED_PAYSTUB_PDF
, NONE
download_url
/credit/payroll_income/get
again.status
PROCESSING_COMPLETE
: The document was successfully processed.DOCUMENT_ERROR
: The document could not be processed. Possible causes include: The document was an unacceptable document type such as an offer letter or bank statement, the document image was cropped or blurry, or the document was corrupted.UNKNOWN
or null
: An internal error occurred. If this happens repeatedly, contact support or your Plaid account manager.UNKNOWN
, PROCESSING_COMPLETE
, DOCUMENT_ERROR
, null
page_count
form_1099_type
FORM_1099_TYPE_UNKNOWN
, FORM_1099_TYPE_MISC
, FORM_1099_TYPE_K
recipient
name
tin
account_number
facta_filing _requirement
CHECKED
, NOT CHECKED
second_tin_exists
CHECKED
, NOT CHECKED
payer
name
tin
telephone_number
filer
name
tin
type
Payment Settlement Entity (PSE)
, Electronic Payment Facilitator (EPF)
, Other Third Party
tax_year
rents
double
royalties
double
other_income
double
federal_income_tax _withheld
double
fishing_boat_proceeds
double
medical_and _healthcare_payments
double
nonemployee _compensation
double
substitute_payments _in_lieu_of_dividends _or_interest
double
payer_made_direct _sales_of_5000_or _more_of_consumer _products_to_buyer
crop_insurance _proceeds
double
excess_golden _parachute_payments
double
gross_proceeds_paid _to_an_attorney
double
section_409a_deferrals
double
section_409a_income
double
state_tax_withheld
double
state_tax_withheld _lower
double
payer_state_number
payer_state_number _lower
state_income
double
state_income_lower
double
transactions_reported
Payment card
, Third party network
pse_name
pse_telephone_number
gross_amount
double
card_not_present _transaction
double
merchant_category_code
number_of_payment _transactions
january_amount
double
february_amount
double
march_amount
double
april_amount
double
may_amount
double
june_amount
double
july_amount
double
august_amount
double
september_amount
double
october_amount
double
november_amount
double
december_amount
double
primary_state
secondary_state
primary_state_id
secondary_state_id
primary_state_income _tax
double
secondary_state _income_tax
double
status
processing_status
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.UNKNOWN
, PROCESSING_COMPLETE
, PROCESSING
, FAILED
, APPROVAL_STATUS_PENDING
updated_at
date-time
error
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
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
error_message
display_message
null
if the error is not related to user action.This may change over time and is not safe for programmatic use.
request_id
causes
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
documentation_url
suggested_action
request_id
1{2 "items": [3 {4 "item_id": "eVBnVMp7zdTJLkRNr33Rs6zr7KNJqBFL9DrE6",5 "institution_id": "ins_92",6 "institution_name": "ADP",7 "accounts": [8 {9 "account_id": "GeooLPBGDEunl54q7N3ZcyD5aLPLEai1nkzM9",10 "rate_of_pay": {11 "pay_amount": 100000,12 "pay_rate": "ANNUAL"13 },14 "pay_frequency": "BIWEEKLY"15 }16 ],17 "payroll_income": [18 {19 "account_id": "GeooLPBGDEunl54q7N3ZcyD5aLPLEai1nkzM9",20 "pay_stubs": [21 {22 "deductions": {23 "breakdown": [24 {25 "current_amount": 123.45,26 "description": "taxes",27 "iso_currency_code": "USD",28 "unofficial_currency_code": null,29 "ytd_amount": 246.930 }31 ],32 "total": {33 "current_amount": 123.45,34 "iso_currency_code": "USD",35 "unofficial_currency_code": null,36 "ytd_amount": 246.937 }38 },39 "document_metadata": {40 "document_type": "PAYSTUB",41 "name": "paystub.pdf",42 "status": "PROCESSING_COMPLETE",43 "download_url": null44 },45 "document_id": "2jkflanbd",46 "earnings": {47 "breakdown": [48 {49 "canonical_description": "REGULAR_PAY",50 "current_amount": 200.22,51 "description": "salary earned",52 "hours": 80,53 "iso_currency_code": "USD",54 "rate": null,55 "unofficial_currency_code": null,56 "ytd_amount": 400.4457 },58 {59 "canonical_description": "BONUS",60 "current_amount": 100,61 "description": "bonus earned",62 "hours": null,63 "iso_currency_code": "USD",64 "rate": null,65 "unofficial_currency_code": null,66 "ytd_amount": 10067 }68 ],69 "total": {70 "current_amount": 300.22,71 "hours": 160,72 "iso_currency_code": "USD",73 "unofficial_currency_code": null,74 "ytd_amount": 500.4475 }76 },77 "employee": {78 "address": {79 "city": "SAN FRANCISCO",80 "country": "US",81 "postal_code": "94133",82 "region": "CA",83 "street": "2140 TAYLOR ST"84 },85 "name": "ANNA CHARLESTON",86 "marital_status": "SINGLE",87 "taxpayer_id": {88 "id_type": "SSN",89 "id_mask": "3333"90 }91 },92 "employer": {93 "name": "PLAID INC",94 "address": {95 "city": "SAN FRANCISCO",96 "country": "US",97 "postal_code": "94111",98 "region": "CA",99 "street": "1098 HARRISON ST"100 }101 },102 "net_pay": {103 "current_amount": 123.34,104 "description": "TOTAL NET PAY",105 "iso_currency_code": "USD",106 "unofficial_currency_code": null,107 "ytd_amount": 253.54108 },109 "pay_period_details": {110 "distribution_breakdown": [111 {112 "account_name": "Big time checking",113 "bank_name": "bank of plaid",114 "current_amount": 176.77,115 "iso_currency_code": "USD",116 "mask": "1223",117 "type": "checking",118 "unofficial_currency_code": null119 }120 ],121 "end_date": "2020-12-15",122 "gross_earnings": 4500,123 "iso_currency_code": "USD",124 "pay_amount": 1490.21,125 "pay_date": "2020-12-15",126 "pay_frequency": "BIWEEKLY",127 "start_date": "2020-12-01",128 "unofficial_currency_code": null129 }130 }131 ],132 "w2s": [133 {134 "allocated_tips": "1000",135 "box_12": [136 {137 "amount": "200",138 "code": "AA"139 }140 ],141 "box_9": "box9",142 "dependent_care_benefits": "1000",143 "document_metadata": {144 "document_type": "US_TAX_W2",145 "download_url": null,146 "name": "w_2.pdf",147 "status": "PROCESSING_COMPLETE"148 },149 "document_id": "1pkflebk4",150 "employee": {151 "address": {152 "city": "San Francisco",153 "country": "US",154 "postal_code": "94103",155 "region": "CA",156 "street": "1234 Grand St"157 },158 "name": "Josie Georgia Harrison",159 "marital_status": "SINGLE",160 "taxpayer_id": {161 "id_type": "SSN",162 "id_mask": "1234"163 }164 },165 "employer": {166 "address": {167 "city": "New York",168 "country": "US",169 "postal_code": "10010",170 "region": "NY",171 "street": "456 Main St"172 },173 "name": "Acme Inc"174 },175 "employer_id_number": "12-1234567",176 "federal_income_tax_withheld": "1000",177 "medicare_tax_withheld": "1000",178 "medicare_wages_and_tips": "1000",179 "nonqualified_plans": "1000",180 "other": "other",181 "retirement_plan": "CHECKED",182 "social_security_tax_withheld": "1000",183 "social_security_tips": "1000",184 "social_security_wages": "1000",185 "state_and_local_wages": [186 {187 "employer_state_id_number": "11111111111AAA",188 "local_income_tax": "200",189 "local_wages_and_tips": "200",190 "locality_name": "local",191 "state": "UT",192 "state_income_tax": "200",193 "state_wages_tips": "200"194 }195 ],196 "statutory_employee": "CHECKED",197 "tax_year": "2020",198 "third_party_sick_pay": "CHECKED",199 "wages_tips_other_comp": "1000"200 }201 ],202 "form1099s": [203 {204 "april_amount": null,205 "august_amount": null,206 "card_not_present_transaction": null,207 "crop_insurance_proceeds": 1000,208 "december_amount": null,209 "document_id": "mvMZ59Z2a5",210 "document_metadata": {211 "document_type": "US_TAX_1099_MISC",212 "download_url": null,213 "name": "form_1099_misc.pdf",214 "status": "PROCESSING_COMPLETE"215 },216 "excess_golden_parachute_payments": 1000,217 "feburary_amount": null,218 "federal_income_tax_withheld": 1000,219 "filer": {220 "address": {221 "city": null,222 "country": null,223 "postal_code": null,224 "region": null,225 "street": null226 },227 "name": null,228 "tin": null,229 "type": null230 },231 "fishing_boat_proceeds": 1000,232 "form_1099_type": "FORM_1099_TYPE_MISC",233 "gross_amount": 1000,234 "gross_proceeds_paid_to_an_attorney": 1000,235 "january_amount": null,236 "july_amount": null,237 "june_amount": null,238 "march_amount": null,239 "may_amount": null,240 "medical_and_healthcare_payments": 1000,241 "merchant_category_code": null,242 "nonemployee_compensation": 1000,243 "november_amount": null,244 "number_of_payment_transactions": null,245 "october_amount": null,246 "other_income": 1000,247 "payer": {248 "address": {249 "city": "SAN FRANCISCO",250 "country": "US",251 "postal_code": "94111",252 "region": "CA",253 "street": "1098 HARRISON ST"254 },255 "name": "PLAID INC",256 "telephone_number": "(123)456-7890",257 "tin": "12-3456789"258 },259 "payer_made_direct_sales_of_500_or_more_of_consumer_products_to_buyer": null,260 "payer_state_number": "CA 12345",261 "payer_state_number_lower": null,262 "primary_state": null,263 "primary_state_id": "CA 12345",264 "primary_state_income_tax": 1000,265 "pse_name": null,266 "pse_telephone_number": null,267 "recipient": {268 "account_number": "45678",269 "address": {270 "city": "SAN FRANCISCO",271 "country": "US",272 "postal_code": "94133",273 "region": "CA",274 "street": "2140 TAYLOR ST"275 },276 "facta_filing_requirement": "CHECKED",277 "name": "Josie Georgia Harrison",278 "second_tin_exists": "NOT CHECKED",279 "tin": "12-3456789"280 },281 "rents": 1000,282 "royalties": 1000,283 "secondary_state": null,284 "secondary_state_id": null,285 "secondary_state_income_tax": null,286 "section_409a_deferrals": 1000,287 "section_409a_income": 1000,288 "september_amount": null,289 "state_income": 1000,290 "state_income_lower": null,291 "state_tax_withheld": 1000,292 "state_tax_withheld_lower": null,293 "substitute_payments_in_lieu_of_dividends_or_interest": null,294 "tax_year": "2022",295 "transactions_reported": null296 }297 ]298 }299 ],300 "status": {301 "processing_status": "PROCESSING_COMPLETE"302 },303 "updated_at": "2022-08-02T21:14:54Z"304 }305 ],306 "request_id": "2pxQ59buGdsHRef"307}
Was this helpful?
/credit/payroll_income/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.
Request fields and example
client_id
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
secret
. The secret
is required and may be provided either in the PLAID-SECRET
header or as part of a request body.user_token
access_tokens
transactions
, providing them in this field will cause these Items to be initialized with (and billed for) the Transactions product.employer
name
address
city
country
postal_code
zip
.region
state
.
Example: "NC"
street
"564 Main Street, APT 15"
tax_id
url
us_military_info
is_active_duty
branch
payroll_institution
name
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};2021try {22 const response = await client.creditPayrollIncomePrecheck(request);23} catch (error) {24 // handle error25}
Response fields and example
request_id
confidence
"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.HIGH
, LOW
, UNKNOWN
1{2 "request_id": "lMjeOeu9X1VUh1F",3 "confidence": "HIGH"4}
Was this helpful?
/credit/payroll_income/risk_signals/get
Retrieve fraud insights for a user's manually uploaded document(s).
/credit/payroll_income/risk_signals/get
can be used as part of the Document Income flow to assess a user-uploaded document for signs of potential fraud or tampering. It returns a risk score for each uploaded document that indicates the likelihood of the document being fraudulent, in addition to details on the individual risk signals contributing to the score. /credit/payroll_income/risk_signals/get
can be called at any time after the INCOME_VERIFICATION_RISK_SIGNALS
webhook has been fired./credit/payroll_income/risk_signals/get
is offered as an add-on to Document Income and is billed separately. To request access to this endpoint, submit a product access request or contact your Plaid account manager.
Request fields and example
client_id
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
secret
. The secret
is required and may be provided either in the PLAID-SECRET
header or as part of a request body.user_token