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/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/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 |
/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_webhook | Manually fire an Income webhook (Sandbox only) |
Webhooks | |
---|---|
INCOME_VERIFICATION | Webhook 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.
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
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
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 did not grant 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/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
status
earnings
breakdown
canonical_description
BONUS
, COMMISSION
, OVERTIME
, PAID_TIME_OFF
, REGULAR_PAY
, VACATION
, BASIC_ALLOWANCE_HOUSING
, BASIC_ALLOWANCE_SUBSISTENCE
, OTHER
, 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
.SINGLE
, MARRIED
, 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
status
document_id
employee
name
marital_status
SINGLE
or MARRIED
.SINGLE
, MARRIED
, 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
status
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/employment/get
Retrieve a summary of an individual's employment information
/credit/employment/get
returns a list of items with employment information from a user's payroll provider that was verified by an end user.
Request fields and example
client_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: CreditEmploymentGetRequest = {2 user_token: 'user-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d',3};45try {6 const response = await client.creditEmploymentGet(request);7} catch (error) {8 // handle error9}
Response fields and example
items
item_id
item_id
of the Item associated with this webhook, warning, or erroremployments
account_id
status
ACTIVE
, INACTIVE
, null
start_date
date
end_date
date
title
platform_ids
employee_id
payroll_id
position_id
employee_type
"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.FULL_TIME
, PART_TIME
, CONTRACTOR
, TEMPORARY
, OTHER
, null
last_paystub_date
date
request_id
1{2 "items": [3 {4 "item_id": "eVBnVMp7zdTJLkRNr33Rs6zr7KNJqBFL9DrE6",5 "employments": [6 {7 "account_id": "GeooLPBGDEunl54q7N3ZcyD5aLPLEai1nkzM9",8 "status": "ACTIVE",9 "start_date": "2020-01-01",10 "end_date": null,11 "employer": {12 "name": "Plaid Inc"13 },14 "title": "Software Engineer",15 "platform_ids": {16 "employee_id": "1234567",17 "position_id": "8888",18 "payroll_id": "1234567"19 },20 "employee_type": "FULL_TIME",21 "last_paystub_date": "2022-01-15"22 }23 ]24 }25 ],26 "request_id": "LhQf0THi8SH1yJm"27}
Was this helpful?
/credit/sessions/get
Retrieve Link sessions for your user
This endpoint can be used for your end users after they complete the Link flow. This endpoint returns a list of Link sessions that your user completed, where each session includes the results from the Link flow.
These results include details about the Item that was created and some product related metadata (showing, for example, whether the user finished the bank income verification step).
Request fields and example
client_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: CreditSessionsGetRequest = {2 user_token: 'user-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d',3};45try {6 const response = await client.creditSessionsGet(request);7} catch (error) {8 // handle error9}
Response fields and example
sessions
link_session_id
link_session_id
returned in the onSuccess/onExit callbacks.session_start_time
date-time
results
item_add_results
public_token
item_id
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
bank_income_results
status
APPROVED
: User has approved and verified their incomeNO_DEPOSITS_FOUND
: We attempted, but were unable to find any income in the connected account.USER_REPORTED_NO_INCOME
: The user explicitly indicated that they don't receive income in the connected account.APPROVED
, NO_DEPOSITS_FOUND
, USER_REPORTED_NO_INCOME
item_id
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
bank_employment _results
status
APPROVED
: User has approved and verified their employment.NO_EMPLOYMENTS_FOUND
: We attempted, but were unable to find any employment in the connected account.EMPLOYER_NOT_LISTED
: The user explicitly indicated that they did not see their current or previous employer in the list of employer names found.APPROVED
, NO_EMPLOYERS_FOUND
, EMPLOYER_NOT_LISTED
item_id
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
payroll_income_results
num_paystubs_retrieved
num_w2s_retrieved
institution_id
institution_name
document_income _results
num_paystubs_uploaded
num_w2s_uploaded
errors
error_type
error_code
error_message
display_message
null
if the error is not related to user action.request_id
1{2 "request_id": "Aim3b",3 "sessions": [4 {5 "link_session_id": "356dbb28-7f98-44d1-8e6d-0cec580f3171",6 "results": {7 "item_add_results": [8 {9 "public_token": "public-sandbox-5c224a01-8314-4491-a06f-39e193d5cddc",10 "item_id": "M5eVJqLnv3tbzdngLDp9FL5OlDNxlNhlE55op",11 "institution_id": "ins_56"12 }13 ],14 "bank_income_results": [15 {16 "status": "APPROVED",17 "item_id": "M5eVJqLnv3tbzdngLDp9FL5OlDNxlNhlE55op",18 "institution_id": "ins_56"19 }20 ]21 },22 "session_start_time": "2022-09-30T23:40:30.946225Z"23 },24 {25 "link_session_id": "f742cae8-31e4-49cc-a621-6cafbdb26fb9",26 "results": {27 "payroll_income_results": [28 {29 "num_paystubs_retrieved": 2,30 "num_w2s_retrieved": 1,31 "institution_id": "ins_92"32 }33 ]34 },35 "session_start_time": "2022-09-26T23:40:30.946225Z"36 }37 ]38}
Was this helpful?
/user/create
Create user
This endpoint should be called for each of your end users before they begin a Plaid income flow. This provides you a single token to access all income data associated with the user. You should only create one per end user.
If you call the endpoint multiple times with the same client_user_id
, the first creation call will succeed and the rest will fail with an error message indicating that the user has been created for the given client_user_id
.
Ensure that you store the user_token
along with your user's identifier in your database, as it is not possible to retrieve a previously created user_token
.
Request fields and example
client_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.client_user_id
client_user_id
.128
1
1const request: UserCreateRequest = {2 client_user_id: 'c0e2c4ee-b763-4af5-cfe9-46a46bce883d'3};45try {6 const response = await client.userCreate(request);7} catch (error) {8 // handle error9}
Response fields and example
user_token
user_id
user_id
of the User associated with this webhook, warning, or error.request_id
1{2 "user_token": "user-sandbox-b0e2c4ee-a763-4df5-bfe9-46a46bce993d",3 "user_id": "wz666MBjYWTp2PDzzggYhM6oWWmBb",4 "request_id": "Aim3b"5}
Was this helpful?
/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.
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
first_name
last_name
email_address
home_address
city
region
"NC"
street
"564 Main Street, APT 15"
postal_code
country
employer
name
address
city
country
postal_code
zip
.region
state
.
Example: "NC"
street
"564 Main Street, APT 15"
tax_id
url
payroll_institution
name
transactions_access _token
transactions_access _tokens
transactions
, providing them in this field will cause these Items to be initialized with (and billed for) the Transactions product.us_military_info
is_active_duty
branch