--- title: "Retrieve a user's payroll information" method: POST path: "/credit/payroll_income/get" tags: ["plaid"] --- # 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 - CreditPayrollIncomeGetRequest — CreditPayrollIncomeGetRequest defines the request schema for `/credit/payroll_income/get`. - `client_id` string — Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. - `secret` string — Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. - `user_token` string — The user token associated with the user for which data is being requested. This field is used only by customers with pre-existing integrations that already use the `user_token` field. All other customers should use the `user_id` instead. For more details, see [New User APIs](https://plaid.com/docs/api/users/user-apis). - `user_id` string — A unique user identifier, created by `/user/create`. Integrations that began using `/user/create` after December 10, 2025 use this field to identify a user instead of the `user_token`. For more details, see [New User APIs](https://plaid.com/docs/api/users/user-apis). - `options` CreditPayrollIncomeGetRequestOptions — An optional object for `/credit/payroll_income/get` request options. - `item_ids` string[] — An array of `item_id`s whose payroll information is returned. Each `item_id` should uniquely identify a payroll income item. If this field is not provided, all `item_id`s associated with the `user_token` will be returned in the response. ## Response `200` OK - CreditPayrollIncomeGetResponse — Defines the response body for `/credit/payroll_income/get`. - `items` PayrollItem[], required — Array of payroll items. - `item_id` string, required — The `item_id` of the Item associated with this webhook, warning, or error - `institution_id` string, required — The unique identifier of the institution associated with the Item. - `institution_name` string, required — The name of the institution associated with the Item. - `accounts` PayrollIncomeAccountData[], required - `account_id` string, nullable, required — ID of the payroll provider account. - `rate_of_pay` PayrollIncomeRateOfPay, required — An object representing the rate at which an individual is paid. - `pay_rate` string, nullable — The rate at which an employee is paid. - `pay_amount` number, double, nullable — The amount at which an employee is paid. - `pay_frequency` string, nullable, required — The frequency at which an individual is paid. - `payroll_income` PayrollIncomeObject[], required - `account_id` string, nullable, required — ID of the payroll provider account. - `pay_stubs` CreditPayStub[], required — Array of pay stubs for the user. - `deductions` CreditPayStubDeductions, required — An object with the deduction information found on a pay stub. - `breakdown` PayStubDeductionsBreakdown[], required - `current_amount` number, double, nullable, required — Raw amount of the deduction - `description` string, nullable, required — Description of the deduction line item - `iso_currency_code` string, nullable, required — The ISO-4217 currency code of the line item. Always `null` if `unofficial_currency_code` is non-null. - `unofficial_currency_code` string, nullable, required — The unofficial currency code associated with the line item. Always `null` if `iso_currency_code` is non-`null`. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. See the [currency code schema](https://plaid.com/docs/api/accounts#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. - `ytd_amount` number, double, nullable, required — The year-to-date amount of the deduction - `total` PayStubDeductionsTotal, required — An object representing the total deductions for the pay period - `current_amount` number, double, nullable, required — Raw amount of the deduction - `iso_currency_code` string, nullable, required — The ISO-4217 currency code of the line item. Always `null` if `unofficial_currency_code` is non-null. - `unofficial_currency_code` string, nullable, required — The unofficial currency code associated with the line item. Always `null` if `iso_currency_code` is non-`null`. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. See the [currency code schema](https://plaid.com/docs/api/accounts#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. - `ytd_amount` number, double, nullable, required — The year-to-date total amount of the deductions - `document_id` string, nullable, required — An identifier of the document referenced by the document metadata. - `document_metadata` CreditDocumentMetadata, required — Object representing metadata pertaining to the document. - `name` string, required — The name of the document. - `document_type` string, nullable, required — 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_TAX_1099_MISC`: A 1099-MISC tax form reporting miscellaneous income. `US_TAX_1099_K`: A 1099-K tax form reporting payment card and third-party network transactions. `US_STUDENT_I20`: A Certificate of Eligibility for Nonimmigrant Student Status (Form I-20) issued by a US school. `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` string, nullable, required — 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](https://plaid.com/documents/plaid-generated-mock-paystub.pdf). 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](https://plaid.com/docs/income/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` string, nullable, required — 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` integer, nullable — The number of pages of the uploaded document (if available). - `error_message` string, nullable — The reason why a failure occurred during document processing (if available). - `earnings` CreditPayStubEarnings, required — An object representing both a breakdown of earnings on a pay stub and the total earnings. - `breakdown` PayStubEarningsBreakdown[], required - `canonical_description` string, nullable, required — Commonly used term to describe the earning line item. - `current_amount` number, double, nullable, required — Raw amount of the earning line item. - `description` string, nullable, required — Description of the earning line item. - `hours` number, nullable, required — Number of hours applicable for this earning. - `iso_currency_code` string, nullable, required — The ISO-4217 currency code of the line item. Always `null` if `unofficial_currency_code` is non-null. - `rate` number, double, nullable, required — Hourly rate applicable for this earning. - `unofficial_currency_code` string, nullable, required — The unofficial currency code associated with the line item. Always `null` if `iso_currency_code` is non-`null`. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. See the [currency code schema](https://plaid.com/docs/api/accounts#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. - `ytd_amount` number, double, nullable, required — The year-to-date amount of the line item. - `total` PayStubEarningsTotal, required — An object representing both the current pay period and year to date amount for an earning category. - `current_amount` number, double, nullable, required — Total amount of the earnings for this pay period. - `hours` number, nullable, required — Total number of hours worked for this pay period. - `iso_currency_code` string, nullable, required — The ISO-4217 currency code of the line item. Always `null` if `unofficial_currency_code` is non-null. - `unofficial_currency_code` string, nullable, required — The unofficial currency code associated with the line item. Always `null` if `iso_currency_code` is non-`null`. Unofficial currency codes are used for currencies that do not have official ISO currency codes, such as cryptocurrencies and the currencies of certain countries. See the [currency code schema](https://plaid.com/docs/api/accounts#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. - `ytd_amount` number, double, nullable, required — The total year-to-date amount of the earnings. - `employee` CreditPayStubEmployee, required — Data about the employee. - `address` CreditPayStubAddress, required — Address on the pay stub. - `city` string, nullable, required — The full city name. - `country` string, nullable, required — The ISO 3166-1 alpha-2 country code. - `postal_code` string, nullable, required — The postal code of the address. - `region` string, nullable, required — The region or state. Example: `"NC"` - `street` string, nullable, required — The full street address. - `name` string, nullable, required — The name of the employee. - `marital_status` string, nullable, required — Marital status of the employee - one of `SINGLE`, `MARRIED`, or `NOT LISTED`. - `taxpayer_id` PayStubTaxpayerID, required — Taxpayer ID of the individual receiving the paystub. - `id_type` string, nullable, required — Type of ID, e.g. 'SSN'. - `id_mask` string, nullable, required — ID mask; i.e. last 4 digits of the taxpayer ID. - `employer` CreditPayStubEmployer, required — Information about the employer on the pay stub. - `address` CreditPayStubAddress, required — Address on the pay stub. - `city` string, nullable, required — The full city name. - `country` string, nullable, required — The ISO 3166-1 alpha-2 country code. - `postal_code` string, nullable, required — The postal code of the address. - `region` string, nullable, required — The region or state. Example: `"NC"` - `street` string, nullable, required — The full street address. - `name` string, nullable, required — The name of the employer on the pay stub. - `net_pay` CreditPayStubNetPay, required — An object representing information about the net pay amount on the pay stub. - `current_amount` number, double, nullable, required — Raw amount of the net pay for the pay period. - `description` string, nullable, required — Description of the net pay. - `iso_currency_code` string, nullable, required — The ISO-4217 currency code of the net pay. Always `null` if `unofficial_currency_code` is non-null. - `unofficial_currency_code` string, nullable, required — 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](https://plaid.com/docs/api/accounts#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. - `ytd_amount` number, double, nullable, required — The year-to-date amount of the net pay. - `pay_period_details` PayStubPayPeriodDetails, required — Details about the pay period. - `pay_amount` number, double, nullable, required — The amount of the paycheck. - `distribution_breakdown` PayStubDistributionBreakdown[], required - `account_name` string, nullable, required — Name of the account for the given distribution. - `bank_name` string, nullable, required — The name of the bank that the payment is being deposited to. - `current_amount` number, double, nullable, required — The amount distributed to this account. - `iso_currency_code` string, nullable, required — The ISO-4217 currency code of the net pay. Always `null` if `unofficial_currency_code` is non-null. - `mask` string, nullable, required — The last 2-4 alphanumeric characters of an account's official account number. - `type` string, nullable, required — Type of the account that the paystub was sent to (e.g. 'checking'). - `unofficial_currency_code` string, nullable, required — 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](https://plaid.com/docs/api/accounts#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. - `end_date` string, date, nullable, required — The date on which the pay period ended, in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format ("yyyy-mm-dd"). - `gross_earnings` number, double, nullable, required — Total earnings before tax/deductions. - `iso_currency_code` string, nullable, required — The ISO-4217 currency code of the net pay. Always `null` if `unofficial_currency_code` is non-null. - `pay_date` string, date, nullable, required — The date on which the pay stub was issued, in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format ("yyyy-mm-dd"). - `pay_frequency` string, nullable, required — The frequency at which an individual is paid. - `pay_basis` 'SALARY' | 'HOURLY' | 'COMMISSION' — The explicit pay basis on the paystub (if present). - `start_date` string, date, nullable, required — The date on which the pay period started, in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format ("yyyy-mm-dd"). - `unofficial_currency_code` string, nullable, required — 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](https://plaid.com/docs/api/accounts#currency-code-schema) for a full listing of supported `unofficial_currency_code`s. - `w2s` CreditW2[], required — Array of tax form W-2s. - `document_metadata` CreditDocumentMetadata, required — Object representing metadata pertaining to the document. - `name` string, required — The name of the document. - `document_type` string, nullable, required — 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_TAX_1099_MISC`: A 1099-MISC tax form reporting miscellaneous income. `US_TAX_1099_K`: A 1099-K tax form reporting payment card and third-party network transactions. `US_STUDENT_I20`: A Certificate of Eligibility for Nonimmigrant Student Status (Form I-20) issued by a US school. `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` string, nullable, required — 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](https://plaid.com/documents/plaid-generated-mock-paystub.pdf). 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](https://plaid.com/docs/income/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` string, nullable, required — 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` integer, nullable — The number of pages of the uploaded document (if available). - `error_message` string, nullable — The reason why a failure occurred during document processing (if available). - `document_id` string, required — An identifier of the document referenced by the document metadata. - `employer` CreditPayStubEmployer, required — Information about the employer on the pay stub. - `address` CreditPayStubAddress, required — Address on the pay stub. - `city` string, nullable, required — The full city name. - `country` string, nullable, required — The ISO 3166-1 alpha-2 country code. - `postal_code` string, nullable, required — The postal code of the address. - `region` string, nullable, required — The region or state. Example: `"NC"` - `street` string, nullable, required — The full street address. - `name` string, nullable, required — The name of the employer on the pay stub. - `employee` CreditPayStubEmployee, required — Data about the employee. - `address` CreditPayStubAddress, required — Address on the pay stub. - `city` string, nullable, required — The full city name. - `country` string, nullable, required — The ISO 3166-1 alpha-2 country code. - `postal_code` string, nullable, required — The postal code of the address. - `region` string, nullable, required — The region or state. Example: `"NC"` - `street` string, nullable, required — The full street address. - `name` string, nullable, required — The name of the employee. - `marital_status` string, nullable, required — Marital status of the employee - one of `SINGLE`, `MARRIED`, or `NOT LISTED`. - `taxpayer_id` PayStubTaxpayerID, required — Taxpayer ID of the individual receiving the paystub. - `id_type` string, nullable, required — Type of ID, e.g. 'SSN'. - `id_mask` string, nullable, required — ID mask; i.e. last 4 digits of the taxpayer ID. - `tax_year` string, nullable, required — The tax year of the W2 document. - `employer_id_number` string, nullable, required — An employer identification number or EIN. - `wages_tips_other_comp` string, nullable, required — Wages from tips and other compensation. - `federal_income_tax_withheld` string, nullable, required — Federal income tax withheld for the tax year. - `social_security_wages` string, nullable, required — Wages from Social Security. - `social_security_tax_withheld` string, nullable, required — Social Security tax withheld for the tax year. - `medicare_wages_and_tips` string, nullable, required — Wages and tips from medicare. - `medicare_tax_withheld` string, nullable, required — Medicare tax withheld for the tax year. - `social_security_tips` string, nullable, required — Tips from Social Security. - `allocated_tips` string, nullable, required — Allocated tips. - `box_9` string, nullable, required — Contents from box 9 on the W2. - `dependent_care_benefits` string, nullable, required — Dependent care benefits. - `nonqualified_plans` string, nullable, required — Nonqualified plans. - `box_12` W2Box12[], required - `code` string, nullable — W2 Box 12 code. - `amount` string, nullable — W2 Box 12 amount. - `statutory_employee` string, nullable, required — Statutory employee. - `retirement_plan` string, nullable, required — Retirement plan. - `third_party_sick_pay` string, nullable, required — Third party sick pay. - `other` string, nullable, required — Other. - `state_and_local_wages` W2StateAndLocalWages[], required - `state` string, nullable — State associated with the wage. - `employer_state_id_number` string, nullable — State identification number of the employer. - `state_wages_tips` string, nullable — Wages and tips from the specified state. - `state_income_tax` string, nullable — Income tax from the specified state. - `local_wages_tips` string, nullable — Wages and tips from the locality. - `local_income_tax` string, nullable — Income tax from the locality. - `locality_name` string, nullable — Name of the locality. - `form1099s` Credit1099[], required — Array of tax form 1099s. - `document_id` string, nullable, required — An identifier of the document referenced by the document metadata. - `document_metadata` CreditDocumentMetadata — Object representing metadata pertaining to the document. - `name` string, required — The name of the document. - `document_type` string, nullable, required — 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_TAX_1099_MISC`: A 1099-MISC tax form reporting miscellaneous income. `US_TAX_1099_K`: A 1099-K tax form reporting payment card and third-party network transactions. `US_STUDENT_I20`: A Certificate of Eligibility for Nonimmigrant Student Status (Form I-20) issued by a US school. `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` string, nullable, required — 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](https://plaid.com/documents/plaid-generated-mock-paystub.pdf). 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](https://plaid.com/docs/income/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` string, nullable, required — 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` integer, nullable — The number of pages of the uploaded document (if available). - `error_message` string, nullable — The reason why a failure occurred during document processing (if available). - `form_1099_type` 'FORM_1099_TYPE_UNKNOWN' | 'FORM_1099_TYPE_MISC' | 'FORM_1099_TYPE_K' — Form 1099 Type - `recipient` Credit1099Recipient — An object representing a recipient used in both 1099-K and 1099-MISC tax documents. - `address` CreditPayStubAddress — Address on the pay stub. - `city` string, nullable, required — The full city name. - `country` string, nullable, required — The ISO 3166-1 alpha-2 country code. - `postal_code` string, nullable, required — The postal code of the address. - `region` string, nullable, required — The region or state. Example: `"NC"` - `street` string, nullable, required — The full street address. - `name` string, nullable — Name of recipient. - `tin` string, nullable — Tax identification number of recipient. - `account_number` string, nullable — Account number of recipient. - `facta_filing_requirement` string, nullable — Checked if FATCA is a filing requirement. - `second_tin_exists` string, nullable — Checked if 2nd TIN exists. - `payer` Credit1099Payer — An object representing a payer used by 1099-MISC tax documents. - `address` CreditPayStubAddress — Address on the pay stub. - `city` string, nullable, required — The full city name. - `country` string, nullable, required — The ISO 3166-1 alpha-2 country code. - `postal_code` string, nullable, required — The postal code of the address. - `region` string, nullable, required — The region or state. Example: `"NC"` - `street` string, nullable, required — The full street address. - `name` string, nullable — Name of payer. - `tin` string, nullable — Tax identification number of payer. - `telephone_number` string, nullable — Telephone number of payer. - `filer` Credit1099Filer — An object representing a filer used by 1099-K tax documents. - `address` CreditPayStubAddress — Address on the pay stub. - `city` string, nullable, required — The full city name. - `country` string, nullable, required — The ISO 3166-1 alpha-2 country code. - `postal_code` string, nullable, required — The postal code of the address. - `region` string, nullable, required — The region or state. Example: `"NC"` - `street` string, nullable, required — The full street address. - `name` string, nullable — Name of filer. - `tin` string, nullable — Tax identification number of filer. - `type` string, nullable — One of the following values will be provided: Payment Settlement Entity (PSE), Electronic Payment Facilitator (EPF), Other Third Party - `tax_year` string, nullable — Tax year of the tax form. - `rents` number, double, nullable — Amount in rent by payer. - `royalties` number, double, nullable — Amount in royalties by payer. - `other_income` number, double, nullable — Amount in other income by payer. - `federal_income_tax_withheld` number, double, nullable — Amount of federal income tax withheld from payer. - `fishing_boat_proceeds` number, double, nullable — Amount of fishing boat proceeds from payer. - `medical_and_healthcare_payments` number, double, nullable — Amount of medical and healthcare payments from payer. - `nonemployee_compensation` number, double, nullable — Amount of nonemployee compensation from payer. - `substitute_payments_in_lieu_of_dividends_or_interest` number, double, nullable — Amount of substitute payments made by payer. - `payer_made_direct_sales_of_5000_or_more_of_consumer_products_to_buyer` string, nullable — Whether or not payer made direct sales over $5000 of consumer products. - `crop_insurance_proceeds` number, double, nullable — Amount of crop insurance proceeds. - `excess_golden_parachute_payments` number, double, nullable — Amount of golden parachute payments made by payer. - `gross_proceeds_paid_to_an_attorney` number, double, nullable — Amount of gross proceeds paid to an attorney by payer. - `section_409a_deferrals` number, double, nullable — Amount of 409A deferrals earned by payer. - `section_409a_income` number, double, nullable — Amount of 409A income earned by payer. - `state_tax_withheld` number, double, nullable — Amount of state tax withheld of payer for primary state. - `state_tax_withheld_lower` number, double, nullable — Amount of state tax withheld of payer for secondary state. - `payer_state_number` string, nullable — Primary state ID. - `payer_state_number_lower` string, nullable — Secondary state ID. - `state_income` number, double, nullable — State income reported for primary state. - `state_income_lower` number, double, nullable — State income reported for secondary state. - `transactions_reported` string, nullable — One of the values will be provided Payment card Third party network - `pse_name` string, nullable — Name of the PSE (Payment Settlement Entity). - `pse_telephone_number` string, nullable — Formatted (XXX) XXX-XXXX. Phone number of the PSE (Payment Settlement Entity). - `gross_amount` number, double, nullable — Gross amount reported. - `card_not_present_transaction` number, double, nullable — Amount in card not present transactions. - `merchant_category_code` string, nullable — Merchant category of filer. - `number_of_payment_transactions` string, nullable — Number of payment transactions made. - `january_amount` number, double, nullable — Amount reported for January. - `february_amount` number, double, nullable — Amount reported for February. - `march_amount` number, double, nullable — Amount reported for March. - `april_amount` number, double, nullable — Amount reported for April. - `may_amount` number, double, nullable — Amount reported for May. - `june_amount` number, double, nullable — Amount reported for June. - `july_amount` number, double, nullable — Amount reported for July. - `august_amount` number, double, nullable — Amount reported for August. - `september_amount` number, double, nullable — Amount reported for September. - `october_amount` number, double, nullable — Amount reported for October. - `november_amount` number, double, nullable — Amount reported for November. - `december_amount` number, double, nullable — Amount reported for December. - `primary_state` string, nullable — Primary state of business. - `secondary_state` string, nullable — Secondary state of business. - `primary_state_id` string, nullable — Primary state ID. - `secondary_state_id` string, nullable — Secondary state ID. - `primary_state_income_tax` number, double, nullable — State income tax reported for primary state. - `secondary_state_income_tax` number, double, nullable — State income tax reported for secondary state. - `i20s` CreditI20[], required — Array of Form I-20 US immigration student documents. - `document_id` string, nullable — An identifier of the document referenced by the document metadata. - `document_metadata` CreditDocumentMetadata — Object representing metadata pertaining to the document. - `name` string, required — The name of the document. - `document_type` string, nullable, required — 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_TAX_1099_MISC`: A 1099-MISC tax form reporting miscellaneous income. `US_TAX_1099_K`: A 1099-K tax form reporting payment card and third-party network transactions. `US_STUDENT_I20`: A Certificate of Eligibility for Nonimmigrant Student Status (Form I-20) issued by a US school. `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` string, nullable, required — 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](https://plaid.com/documents/plaid-generated-mock-paystub.pdf). 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](https://plaid.com/docs/income/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` string, nullable, required — 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` integer, nullable — The number of pages of the uploaded document (if available). - `error_message` string, nullable — The reason why a failure occurred during document processing (if available). - `student` CreditI20Student — An object representing the student named on a Form I-20. - `given_name` string, nullable — Given name of the student. - `surname_primary_name` string, nullable — Surname or primary name of the student. - `passport_name` string, nullable — Name of the student as it appears on their passport. - `preferred_name` string, nullable — Preferred name of the student. - `school_name` string, nullable — Name of the school issuing the Form I-20. - `program_start_date` string, date, nullable — Start date of the program in ISO 8601 format (YYYY-MM-DD). - `program_end_date` string, date, nullable — End date of the program in ISO 8601 format (YYYY-MM-DD). - `personal_funds` number, double, nullable — Amount of the student's personal funds. - `on_campus_employment` number, double, nullable — Amount of funds from on-campus employment. - `funds_from_this_school` number, double, nullable — Amount of funds provided by the issuing school. - `students_funding_total` number, double, nullable — Total amount of funds available to the student. - `funds_from_another_source` number, double, nullable — Amount of funds from another source. - `estimated_average_costs_total` number, double, nullable — Estimated total average costs for the program period. - `estimated_average_living_expenses` number, double, nullable — Estimated average living expenses. - `students_funding_period_months` integer, nullable — Number of months the student's funding covers. - `estimated_average_costs_period_months` integer, nullable — Number of months the estimated average costs cover. - `status` PayrollItemStatus, nullable, required — Details about the status of the payroll item. - `processing_status` string, nullable — 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` string, date-time, nullable, required — Timestamp in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format (YYYY-MM-DDTHH:mm:ssZ) indicating the last time that the Item was updated. - `error` PlaidError, nullable — 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` 'INVALID_REQUEST' | 'INVALID_RESULT' | 'INVALID_INPUT' | 'INSTITUTION_ERROR' | 'RATE_LIMIT_EXCEEDED' | 'API_ERROR' | 'ITEM_ERROR' | 'ASSET_REPORT_ERROR' | 'BASE_REPORT_ERROR' | 'RECAPTCHA_ERROR' | 'OAUTH_ERROR' | 'PAYMENT_ERROR' | 'BANK_TRANSFER_ERROR' | 'INCOME_VERIFICATION_ERROR' | 'MICRODEPOSITS_ERROR' | 'SANDBOX_ERROR' | 'PARTNER_ERROR' | 'SIGNAL_ERROR' | 'TRANSACTIONS_ERROR' | 'TRANSACTION_ERROR' | 'TRANSFER_ERROR' | 'CHECK_REPORT_ERROR' | 'CONSUMER_REPORT_ERROR' | 'USER_ERROR' | 'IDEMPOTENCY_ERROR' | 'ASSETS_ERROR' | 'CRA_MONITORING_ERROR' | 'CREDIT_PROFILE_REPORT_ERROR' | 'ENCOMPASS_ERROR' | 'ENRICH_ERROR' | 'FRAUD_INSIGHTS_ERROR' | 'FREDDIE_MAC_ERROR' | 'LINK_DELIVERY_ERROR' | 'PROFILE_ERROR' | 'RECURRING_TRANSACTIONS_ERROR' | 'STATEMENTS_ERROR' | 'TRANSFER_RECURRING_ERROR' | 'TRANSFER_REFUND_ERROR', required — A broad categorization of the error. Safe for programmatic use. - `error_code` string, required — The particular error code. Safe for programmatic use. - `error_code_reason` string, nullable — The specific reason for the error code. Currently, reasons are only supported for 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` string, required — A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use. - `display_message` string, nullable, required — A user-friendly representation of the error code. `null` if the error is not related to user action. This may change over time and is not safe for programmatic use. - `request_id` string — A unique ID identifying the request, to be used for troubleshooting purposes. This field will be omitted in errors provided by webhooks. - `causes` unknown[] — 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. - unknown - `status` integer, nullable — The HTTP status code associated with the error. This will only be returned in the response body when the error information is provided via a webhook. - `documentation_url` string — The URL of a Plaid documentation page with more information about the error - `suggested_action` string, nullable — Suggested steps for resolving the error - `required_account_subtypes` string[] — A list of the account subtypes that were requested via the `account_filters` parameter in `/link/token/create`. Currently only populated for `NO_ACCOUNTS` errors from Items with `investments_auth` as an enabled product. - `provided_account_subtypes` string[] — A list of the account subtypes that were extracted but did not match the requested subtypes via the `account_filters` parameter in `/link/token/create`. Currently only populated for `NO_ACCOUNTS` errors from Items with `investments_auth` as an enabled product. - `request_id` string, required — A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. ## Other responses - `default` — Error response --- [API](https://skmtc.net/plaid/apis/the-plaid-api.md) · [All operations](https://skmtc.net/plaid/apis/the-plaid-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/plaid/the-plaid-api/versions/64c4514ea59b/schema)