Retrieve a user's payroll information
POST /credit/payroll_income/get
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.
Request Body
Required
CreditPayrollIncomeGetRequest defines the request schema for /credit/payroll_income/get.
Parameters
client_id
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
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
The user token associated with the User data is being requested for.
options
An optional object for
/credit/payroll_income/get request options.
item_ids
An array of
item_ids whose payroll information is returned. Each item_id should uniquely identify a payroll income item. If this field is not provided, all item_ids associated with the user_token will returned in the response.
Response
Defines the response body for /credit/payroll_income/get.
Response Properties
items
Array of payroll items.
item_id
The
item_id of the Item associated with this webhook, warning, or error
institution_id
The unique identifier of the institution associated with the Item.
institution_name
The name of the institution associated with the Item.
accounts
account_id
ID of the payroll provider account.
rate_of_pay
An object representing the rate at which an individual is paid.
pay_rate
The rate at which an employee is paid.
pay_amount
The amount at which an employee is paid.
pay_frequency
The frequency at which an individual is paid.
payroll_income
account_id
ID of the payroll provider account.
pay_stubs
Array of pay stubs for the user.
deductions
An object with the deduction information found on a pay stub.
breakdown
total
An object representing the total deductions for the pay period
document_id
An identifier of the document referenced by the document metadata.
document_metadata
Object representing metadata pertaining to the document.
name
The name of the document.
document_type
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 Statement (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.
download_url
Signed URL to retrieve the document(s). The payload will be a .zip file containing the document(s).
For Payroll Income, the file type of the documents will always be PDF, and the documents may not be available, in which case the field will be
null. If you would like Plaid to generate a PDF if the original is not available, contact your Account Manager. Example generated pay stub.
For Document Income, this field will not be null, and the file type of the underlying document(s) will be the original file type uploaded by the user. For more details on available file types, see the Document Income documentation.
This download URL can only be used once and expires after two minutes. To generate a new download URL, call /credit/payroll_income/get again.
status
The processing status of the document.
PROCESSING_COMPLETE: The document was successfully processed.
DOCUMENT_ERROR: The document could not be processed. Possible causes include: The document was an unacceptable document type such as an offer letter or bank statement, the document image was cropped or blurry, or the document was corrupted.
UNKNOWN or null: An internal error occurred. If this happens repeatedly, contact support or your Plaid account manager.
page_count
The number of pages of the uploaded document (if available).
error_message
The reason why a failure occurred during document processing (if available).
earnings
An object representing both a breakdown of earnings on a pay stub and the total earnings.
breakdown
total
An object representing both the current pay period and year to date amount for an earning category.
employee
Data about the employee.
address
Address on the pay stub.
name
The name of the employee.
marital_status
Marital status of the employee - either
SINGLE or MARRIED or NOT LISTED.
taxpayer_id
Taxpayer ID of the individual receiving the paystub.
employer
Information about the employer on the pay stub.
address
Address on the pay stub.
name
The name of the employer on the pay stub.
net_pay
An object representing information about the net pay amount on the pay stub.
current_amount
Raw amount of the net pay for the pay period.
description
Description of the net pay.
iso_currency_code
The ISO-4217 currency code of the net pay. Always
null if unofficial_currency_code is non-null.
unofficial_currency_code
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
The year-to-date amount of the net pay.
pay_period_details
Details about the pay period.
pay_amount
The amount of the paycheck.
distribution_breakdown
end_date
The date on which the pay period ended, in ISO 8601 format (“yyyy-mm-dd”).
gross_earnings
Total earnings before tax/deductions.
iso_currency_code
The ISO-4217 currency code of the net pay. Always
null if unofficial_currency_code is non-null.
pay_date
The date on which the pay stub was issued, in ISO 8601 format (“yyyy-mm-dd”).
pay_frequency
The frequency at which an individual is paid.
pay_basis
The explicit pay basis on the paystub (if present).
start_date
The date on which the pay period started, in ISO 8601 format (“yyyy-mm-dd”).
unofficial_currency_code
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
Array of tax form W-2s.
document_metadata
Object representing metadata pertaining to the document.
name
The name of the document.
document_type
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 Statement (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.
download_url
Signed URL to retrieve the document(s). The payload will be a .zip file containing the document(s).
For Payroll Income, the file type of the documents will always be PDF, and the documents may not be available, in which case the field will be
null. If you would like Plaid to generate a PDF if the original is not available, contact your Account Manager. Example generated pay stub.
For Document Income, this field will not be null, and the file type of the underlying document(s) will be the original file type uploaded by the user. For more details on available file types, see the Document Income documentation.
This download URL can only be used once and expires after two minutes. To generate a new download URL, call /credit/payroll_income/get again.
status
The processing status of the document.
PROCESSING_COMPLETE: The document was successfully processed.
DOCUMENT_ERROR: The document could not be processed. Possible causes include: The document was an unacceptable document type such as an offer letter or bank statement, the document image was cropped or blurry, or the document was corrupted.
UNKNOWN or null: An internal error occurred. If this happens repeatedly, contact support or your Plaid account manager.
page_count
The number of pages of the uploaded document (if available).
error_message
The reason why a failure occurred during document processing (if available).
document_id
An identifier of the document referenced by the document metadata.
employer
Information about the employer on the pay stub.
address
Address on the pay stub.
name
The name of the employer on the pay stub.
employee
Data about the employee.
address
Address on the pay stub.
name
The name of the employee.
marital_status
Marital status of the employee - either
SINGLE or MARRIED or NOT LISTED.
taxpayer_id
Taxpayer ID of the individual receiving the paystub.
tax_year
The tax year of the W2 document.
employer_id_number
An employee identification number or EIN.
wages_tips_other_comp
Wages from tips and other compensation.
federal_income_tax_withheld
Federal income tax withheld for the tax year.
social_security_wages
Wages from social security.
social_security_tax_withheld
Social security tax withheld for the tax year.
medicare_wages_and_tips
Wages and tips from medicare.
medicare_tax_withheld
Medicare tax withheld for the tax year.
social_security_tips
Tips from social security.
allocated_tips
Allocated tips.
box_9
Contents from box 9 on the W2.
dependent_care_benefits
Dependent care benefits.
nonqualified_plans
Nonqualified plans.
box_12
code
W2 Box 12 code.
amount
W2 Box 12 amount.
statutory_employee
Statutory employee.
retirement_plan
Retirement plan.
third_party_sick_pay
Third party sick pay.
other
Other.
state_and_local_wages
state
State associated with the wage.
employer_state_id_number
State identification number of the employer.
state_wages_tips
Wages and tips from the specified state.
state_income_tax
Income tax from the specified state.
local_wages_tips
Wages and tips from the locality.
local_income_tax
Income tax from the locality.
locality_name
Name of the locality.
form1099s
Array of tax form 1099s.
document_id
An identifier of the document referenced by the document metadata.
document_metadata
Object representing metadata pertaining to the document.
name
The name of the document.
document_type
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 Statement (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.
download_url
Signed URL to retrieve the document(s). The payload will be a .zip file containing the document(s).
For Payroll Income, the file type of the documents will always be PDF, and the documents may not be available, in which case the field will be
null. If you would like Plaid to generate a PDF if the original is not available, contact your Account Manager. Example generated pay stub.
For Document Income, this field will not be null, and the file type of the underlying document(s) will be the original file type uploaded by the user. For more details on available file types, see the Document Income documentation.
This download URL can only be used once and expires after two minutes. To generate a new download URL, call /credit/payroll_income/get again.
status
The processing status of the document.
PROCESSING_COMPLETE: The document was successfully processed.
DOCUMENT_ERROR: The document could not be processed. Possible causes include: The document was an unacceptable document type such as an offer letter or bank statement, the document image was cropped or blurry, or the document was corrupted.
UNKNOWN or null: An internal error occurred. If this happens repeatedly, contact support or your Plaid account manager.
page_count
The number of pages of the uploaded document (if available).
error_message
The reason why a failure occurred during document processing (if available).
form_1099_type
Form 1099 Type
recipient
An object representing a recipient used in both 1099-K and 1099-MISC tax documents.
address
Address on the pay stub.
name
Name of recipient.
tin
Tax identification number of recipient.
account_number
Account number number of recipient.
facta_filing_requirement
Checked if FACTA is a filing requirement.
second_tin_exists
Checked if 2nd TIN exists.
payer
An object representing a payer used by 1099-MISC tax documents.
address
Address on the pay stub.
name
Name of payer.
tin
Tax identification number of payer.
telephone_number
Telephone number of payer.
filer
An object representing a filer used by 1099-K tax documents.
address
Address on the pay stub.
name
Name of filer.
tin
Tax identification number of filer.
type
One of the following values will be provided: Payment Settlement Entity (PSE), Electronic Payment Facilitator (EPF), Other Third Party
tax_year
Tax year of the tax form.
rents
Amount in rent by payer.
royalties
Amount in royalties by payer.
other_income
Amount in other income by payer.
federal_income_tax_withheld
Amount of federal income tax withheld from payer.
fishing_boat_proceeds
Amount of fishing boat proceeds from payer.
medical_and_healthcare_payments
Amount of medical and healthcare payments from payer.
nonemployee_compensation
Amount of nonemployee compensation from payer.
substitute_payments_in_lieu_of_dividends_or_interest
Amount of substitute payments made by payer.
payer_made_direct_sales_of_5000_or_more_of_consumer_products_to_buyer
Whether or not payer made direct sales over $5000 of consumer products.
crop_insurance_proceeds
Amount of crop insurance proceeds.
excess_golden_parachute_payments
Amount of golden parachute payments made by payer.
gross_proceeds_paid_to_an_attorney
Amount of gross proceeds paid to an attorney by payer.
section_409a_deferrals
Amount of 409A deferrals earned by payer.
section_409a_income
Amount of 409A income earned by payer.
state_tax_withheld
Amount of state tax withheld of payer for primary state.
state_tax_withheld_lower
Amount of state tax withheld of payer for secondary state.
payer_state_number
Primary state ID.
payer_state_number_lower
Secondary state ID.
state_income
State income reported for primary state.
state_income_lower
State income reported for secondary state.
transactions_reported
One of the values will be provided Payment card Third party network
pse_name
Name of the PSE (Payment Settlement Entity).
pse_telephone_number
Formatted (XXX) XXX-XXXX. Phone number of the PSE (Payment Settlement Entity).
gross_amount
Gross amount reported.
card_not_present_transaction
Amount in card not present transactions.
merchant_category_code
Merchant category of filer.
number_of_payment_transactions
Number of payment transactions made.
january_amount
Amount reported for January.
february_amount
Amount reported for February.
march_amount
Amount reported for March.
april_amount
Amount reported for April.
may_amount
Amount reported for May.
june_amount
Amount reported for June.
july_amount
Amount reported for July.
august_amount
Amount reported for August.
september_amount
Amount reported for September.
october_amount
Amount reported for October.
november_amount
Amount reported for November.
december_amount
Amount reported for December.
primary_state
Primary state of business.
secondary_state
Secondary state of business.
primary_state_id
Primary state ID.
secondary_state_id
Secondary state ID.
primary_state_income_tax
State income tax reported for primary state.
secondary_state_income_tax
State income tax reported for secondary state.
status
Details about the status of the payroll item.
processing_status
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.
updated_at
Timestamp in ISO 8601 format (YYYY-MM-DDTHH:mm:ssZ) indicating the last time that the Item was updated.
error
Errors are identified by
error_code and categorized by error_type. Use these in preference to HTTP status codes to identify and handle specific errors. HTTP status codes are set and provide the broadest categorization of errors: 4xx codes are for developer- or user-related errors, and 5xx codes are for Plaid-related errors, and the status will be 2xx in non-error cases. 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
A broad categorization of the error. Safe for programmatic use.
error_code
The particular error code. Safe for programmatic use.
error_code_reason
The specific reason for the error code. Currently, reasons are only supported OAuth-based item errors;
null will be returned otherwise. Safe for programmatic use.
Possible values:
OAUTH_INVALID_TOKEN: The user’s OAuth connection to this institution has been invalidated.
OAUTH_CONSENT_EXPIRED: The user’s access consent for this OAuth connection to this institution has expired.
OAUTH_USER_REVOKED: The user’s OAuth connection to this institution is invalid because the user revoked their connection.
error_message
A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use.
display_message
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
A unique ID identifying the request, to be used for troubleshooting purposes. This field will be omitted in errors provided by webhooks.
causes
In this 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 be provided for the error_type ASSET_REPORT_ERROR or CHECK_REPORT_ERROR. causes will also not be populated inside an error nested within a warning object.
status
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
The URL of a Plaid documentation page with more information about the error
suggested_action
Suggested steps for resolving the error
request_id
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.