Retrieve a user's payroll information

{
  "type": "object",
  "description": "Defines the response body for `/credit/payroll_income/get`.",
  "required": [
    "items",
    "request_id"
  ],
  "properties": {
    "error": {
      "type": "object",
      "description": "We use standard HTTP response codes for success and failure notifications, and our errors are further classified by `error_type`. In general, 200 HTTP codes correspond to success, 40X codes are for developer- or user-related failures, and 50X codes are for Plaid-related issues. An Item with a non-`null` error object will only be part of an API response when calling `/item/get` to view Item status. Otherwise, error fields will be `null` if no error has occurred; if an error has occurred, an error code will be returned instead.",
      "required": [
        "display_message",
        "error_code",
        "error_message",
        "error_type"
      ],
      "properties": {
        "causes": {
          "type": "array",
          "description": "In the Assets product, a request can pertain to more than one Item. If an error is returned for such a request, `causes` will return an array of errors containing a breakdown of these errors on the individual Item level, if any can be identified.\n\n`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.",
          "items": {
            "type": "object"
          }
        },
        "display_message": {
          "type": "string",
          "description": "A user-friendly representation of the error code. `null` if the error is not related to user action.\n\nThis may change over time and is not safe for programmatic use."
        },
        "documentation_url": {
          "type": "string",
          "description": "The URL of a Plaid documentation page with more information about the error"
        },
        "error_code": {
          "type": "string",
          "description": "The particular error code. Safe for programmatic use."
        },
        "error_message": {
          "type": "string",
          "description": "A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use."
        },
        "error_type": {
          "type": "string",
          "description": "A broad categorization of the error. Safe for programmatic use.",
          "enum": [
            "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"
          ]
        },
        "request_id": {
          "type": "string",
          "description": "A unique ID identifying the request, to be used for troubleshooting purposes. This field will be omitted in errors provided by webhooks."
        },
        "status": {
          "type": "number",
          "description": "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."
        },
        "suggested_action": {
          "type": "string",
          "description": "Suggested steps for resolving the error"
        }
      }
    },
    "items": {
      "type": "array",
      "description": "Array of payroll items.",
      "items": {
        "type": "object",
        "description": "An object containing information about the payroll item.",
        "required": [
          "item_id",
          "institution_id",
          "institution_name",
          "payroll_income",
          "status",
          "accounts",
          "updated_at"
        ],
        "properties": {
          "accounts": {
            "type": "array",
            "items": {
              "type": "object",
              "description": "An object containing account level data.",
              "required": [
                "account_id",
                "rate_of_pay",
                "pay_frequency"
              ],
              "properties": {
                "account_id": {
                  "type": "string",
                  "description": "ID of the payroll provider account."
                },
                "pay_frequency": {
                  "type": "string",
                  "description": "The frequency at which an individual is paid."
                },
                "rate_of_pay": {
                  "type": "object",
                  "description": "An object representing the rate at which an individual is paid.",
                  "properties": {
                    "pay_amount": {
                      "type": "number",
                      "format": "double",
                      "description": "The amount at which an employee is paid."
                    },
                    "pay_rate": {
                      "type": "string",
                      "description": "The rate at which an employee is paid."
                    }
                  }
                }
              }
            }
          },
          "institution_id": {
            "type": "string",
            "description": "The unique identifier of the institution associated with the Item."
          },
          "institution_name": {
            "type": "string",
            "description": "The name of the institution associated with the Item."
          },
          "item_id": {
            "type": "string",
            "description": "The `item_id` of the Item associated with this webhook, warning, or error"
          },
          "payroll_income": {
            "type": "array",
            "items": {
              "type": "object",
              "description": "An object representing payroll data.",
              "required": [
                "account_id",
                "pay_stubs",
                "w2s",
                "form1099s"
              ],
              "properties": {
                "account_id": {
                  "type": "string",
                  "description": "ID of the payroll provider account."
                },
                "form1099s": {
                  "type": "array",
                  "description": "Array of tax form 1099s.",
                  "items": {
                    "type": "object",
                    "description": "An object representing an end user's 1099 tax form",
                    "required": [
                      "document_id"
                    ],
                    "properties": {
                      "april_amount": {
                        "type": "number",
                        "format": "double",
                        "description": "Amount reported for April."
                      },
                      "august_amount": {
                        "type": "number",
                        "format": "double",
                        "description": "Amount reported for August."
                      },
                      "card_not_present_transaction": {
                        "type": "number",
                        "format": "double",
                        "description": "Amount in card not present transactions."
                      },
                      "crop_insurance_proceeds": {
                        "type": "number",
                        "format": "double",
                        "description": "Amount of crop insurance proceeds."
                      },
                      "december_amount": {
                        "type": "number",
                        "format": "double",
                        "description": "Amount reported for December."
                      },
                      "document_id": {
                        "type": "string",
                        "description": "An identifier of the document referenced by the document metadata."
                      },
                      "document_metadata": {
                        "type": "object",
                        "description": "Object representing metadata pertaining to the document.",
                        "required": [
                          "name",
                          "document_type",
                          "download_url",
                          "status"
                        ],
                        "properties": {
                          "document_type": {
                            "type": "object",
                            "additionalProperties": true
                          },
                          "download_url": {
                            "type": "object",
                            "additionalProperties": true
                          },
                          "name": {
                            "type": "object",
                            "additionalProperties": true
                          },
                          "status": {
                            "type": "object",
                            "additionalProperties": true
                          }
                        }
                      },
                      "excess_golden_parachute_payments": {
                        "type": "number",
                        "format": "double",
                        "description": "Amount of golden parachute payments made by payer."
                      },
                      "february_amount": {
                        "type": "number",
                        "format": "double",
                        "description": "Amount reported for February."
                      },
                      "federal_income_tax_withheld": {
                        "type": "number",
                        "format": "double",
                        "description": "Amount of federal income tax withheld from payer."
                      },
                      "filer": {
                        "type": "object",
                        "description": "An object representing a filer used by 1099-K tax documents.",
                        "properties": {
                          "address": {
                            "type": "object",
                            "additionalProperties": true
                          },
                          "name": {
                            "type": "object",
                            "additionalProperties": true
                          },
                          "tin": {
                            "type": "object",
                            "additionalProperties": true
                          },
                          "type": {
                            "type": "object",
                            "additionalProperties": true
                          }
                        }
                      },
                      "fishing_boat_proceeds": {
                        "type": "number",
                        "format": "double",
                        "description": "Amount of fishing boat proceeds from payer."
                      },
                      "form_1099_type": {
                        "type": "string",
                        "description": "Form 1099 Type",
                        "enum": [
                          "FORM_1099_TYPE_UNKNOWN",
                          "FORM_1099_TYPE_MISC",
                          "FORM_1099_TYPE_K"
                        ]
                      },
                      "gross_amount": {
                        "type": "number",
                        "format": "double",
                        "description": "Gross amount reported."
                      },
                      "gross_proceeds_paid_to_an_attorney": {
                        "type": "number",
                        "format": "double",
                        "description": "Amount of gross proceeds paid to an attorney by payer."
                      },
                      "january_amount": {
                        "type": "number",
                        "format": "double",
                        "description": "Amount reported for January."
                      },
                      "july_amount": {
                        "type": "number",
                        "format": "double",
                        "description": "Amount reported for July."
                      },
                      "june_amount": {
                        "type": "number",
                        "format": "double",
                        "description": "Amount reported for June."
                      },
                      "march_amount": {
                        "type": "number",
                        "format": "double",
                        "description": "Amount reported for March."
                      },
                      "may_amount": {
                        "type": "number",
                        "format": "double",
                        "description": "Amount reported for May."
                      },
                      "medical_and_healthcare_payments": {
                        "type": "number",
                        "format": "double",
                        "description": "Amount of medical and healthcare payments from payer."
                      },
                      "merchant_category_code": {
                        "type": "string",
                        "description": "Merchant category of filer."
                      },
                      "nonemployee_compensation": {
                        "type": "number",
                        "format": "double",
                        "description": "Amount of nonemployee compensation from payer."
                      },
                      "november_amount": {
                        "type": "number",
                        "format": "double",
                        "description": "Amount reported for November."
                      },
                      "number_of_payment_transactions": {
                        "type": "string",
                        "description": "Number of payment transactions made."
                      },
                      "october_amount": {
                        "type": "number",
                        "format": "double",
                        "description": "Amount reported for October."
                      },
                      "other_income": {
                        "type": "number",
                        "format": "double",
                        "description": "Amount in other income by payer."
                      },
                      "payer": {
                        "type": "object",
                        "description": "An object representing a payer used by 1099-MISC tax documents.",
                        "properties": {
                          "address": {
                            "type": "object",
                            "additionalProperties": true
                          },
                          "name": {
                            "type": "object",
                            "additionalProperties": true
                          },
                          "telephone_number": {
                            "type": "object",
                            "additionalProperties": true
                          },
                          "tin": {
                            "type": "object",
                            "additionalProperties": true
                          }
                        }
                      },
                      "payer_made_direct_sales_of_5000_or_more_of_consumer_products_to_buyer": {
                        "type": "string",
                        "description": "Whether or not payer made direct sales over $5000 of consumer products."
                      },
                      "payer_state_number": {
                        "type": "string",
                        "description": "Primary state ID."
                      },
                      "payer_state_number_lower": {
                        "type": "string",
                        "description": "Secondary state ID."
                      },
                      "primary_state": {
                        "type": "string",
                        "description": "Primary state of business."
                      },
                      "primary_state_id": {
                        "type": "string",
                        "description": "Primary state ID."
                      },
                      "primary_state_income_tax": {
                        "type": "number",
                        "format": "double",
                        "description": "State income tax reported for primary state."
                      },
                      "pse_name": {
                        "type": "string",
                        "description": "Name of the PSE (Payment Settlement Entity)."
                      },
                      "pse_telephone_number": {
                        "type": "string",
                        "description": "Formatted (XXX) XXX-XXXX. Phone number of the PSE (Payment Settlement Entity)."
                      },
                      "recipient": {
                        "type": "object",
                        "description": "An object representing a recipient used in both 1099-K and 1099-MISC tax documents.",
                        "properties": {
                          "account_number": {
                            "type": "object",
                            "additionalProperties": true
                          },
                          "address": {
                            "type": "object",
                            "additionalProperties": true
                          },
                          "facta_filing_requirement": {
                            "type": "object",
                            "additionalProperties": true
                          },
                          "name": {
                            "type": "object",
                            "additionalProperties": true
                          },
                          "second_tin_exists": {
                            "type": "object",
                            "additionalProperties": true
                          },
                          "tin": {
                            "type": "object",
                            "additionalProperties": true
                          }
                        }
                      },
                      "rents": {
                        "type": "number",
                        "format": "double",
                        "description": "Amount in rent by payer."
                      },
                      "royalties": {
                        "type": "number",
                        "format": "double",
                        "description": "Amount in royalties by payer."
                      },
                      "secondary_state": {
                        "type": "string",
                        "description": "Secondary state of business."
                      },
                      "secondary_state_id": {
                        "type": "string",
                        "description": "Secondary state ID."
                      },
                      "secondary_state_income_tax": {
                        "type": "number",
                        "format": "double",
                        "description": "State income tax reported for secondary state."
                      },
                      "section_409a_deferrals": {
                        "type": "number",
                        "format": "double",
                        "description": "Amount of 409A deferrals earned by payer."
                      },
                      "section_409a_income": {
                        "type": "number",
                        "format": "double",
                        "description": "Amount of 409A income earned by payer."
                      },
                      "september_amount": {
                        "type": "number",
                        "format": "double",
                        "description": "Amount reported for September."
                      },
                      "state_income": {
                        "type": "number",
                        "format": "double",
                        "description": "State income reported for primary state."
                      },
                      "state_income_lower": {
                        "type": "number",
                        "format": "double",
                        "description": "State income reported for secondary state."
                      },
                      "state_tax_withheld": {
                        "type": "number",
                        "format": "double",
                        "description": "Amount of state tax withheld of payer for primary state."
                      },
                      "state_tax_withheld_lower": {
                        "type": "number",
                        "format": "double",
                        "description": "Amount of state tax withheld of payer for secondary state."
                      },
                      "substitute_payments_in_lieu_of_dividends_or_interest": {
                        "type": "number",
                        "format": "double",
                        "description": "Amount of substitute payments made by payer."
                      },
                      "tax_year": {
                        "type": "string",
                        "description": "Tax year of the tax form."
                      },
                      "transactions_reported": {
                        "type": "string",
                        "description": "One of the values will be provided Payment card Third party network"
                      }
                    }
                  }
                },
                "pay_stubs": {
                  "type": "array",
                  "description": "Array of pay stubs for the user.",
                  "items": {
                    "type": "object",
                    "description": "An object representing an end user's pay stub.",
                    "required": [
                      "deductions",
                      "document_id",
                      "document_metadata",
                      "earnings",
                      "employee",
                      "employer",
                      "net_pay",
                      "pay_period_details"
                    ],
                    "properties": {
                      "deductions": {
                        "type": "object",
                        "description": "An object with the deduction information found on a pay stub.",
                        "required": [
                          "breakdown",
                          "total"
                        ],
                        "properties": {
                          "breakdown": {
                            "type": "object",
                            "additionalProperties": true
                          },
                          "total": {
                            "type": "object",
                            "additionalProperties": true
                          }
                        }
                      },
                      "document_id": {
                        "type": "string",
                        "description": "An identifier of the document referenced by the document metadata."
                      },
                      "document_metadata": {
                        "type": "object",
                        "description": "Object representing metadata pertaining to the document.",
                        "required": [
                          "name",
                          "document_type",
                          "download_url",
                          "status"
                        ],
                        "properties": {
                          "document_type": {
                            "type": "object",
                            "additionalProperties": true
                          },
                          "download_url": {
                            "type": "object",
                            "additionalProperties": true
                          },
                          "name": {
                            "type": "object",
                            "additionalProperties": true
                          },
                          "status": {
                            "type": "object",
                            "additionalProperties": true
                          }
                        }
                      },
                      "earnings": {
                        "type": "object",
                        "description": "An object representing both a breakdown of earnings on a pay stub and the total earnings.",
                        "required": [
                          "breakdown",
                          "total"
                        ],
                        "properties": {
                          "breakdown": {
                            "type": "object",
                            "additionalProperties": true
                          },
                          "total": {
                            "type": "object",
                            "additionalProperties": true
                          }
                        }
                      },
                      "employee": {
                        "type": "object",
                        "description": "Data about the employee.",
                        "required": [
                          "name",
                          "address",
                          "marital_status",
                          "taxpayer_id"
                        ],
                        "properties": {
                          "address": {
                            "type": "object",
                            "additionalProperties": true
                          },
                          "marital_status": {
                            "type": "object",
                            "additionalProperties": true
                          },
                          "name": {
                            "type": "object",
                            "additionalProperties": true
                          },
                          "taxpayer_id": {
                            "type": "object",
                            "additionalProperties": true
                          }
                        }
                      },
                      "employer": {
                        "type": "object",
                        "description": "Information about the employer on the pay stub.",
                        "required": [
                          "address",
                          "name"
                        ],
                        "properties": {
                          "address": {
                            "type": "object",
                            "additionalProperties": true
                          },
                          "name": {
                            "type": "object",
                            "additionalProperties": true
                          }
                        }
                      },
                      "net_pay": {
                        "type": "object",
                        "description": "An object representing information about the net pay amount on the pay stub.",
                        "required": [
                          "current_amount",
                          "description",
                          "iso_currency_code",
                          "unofficial_currency_code",
                          "ytd_amount"
                        ],
                        "properties": {
                          "current_amount": {
                            "type": "object",
                            "additionalProperties": true
                          },
                          "description": {
                            "type": "object",
                            "additionalProperties": true
                          },
                          "iso_currency_code": {
                            "type": "object",
                            "additionalProperties": true
                          },
                          "unofficial_currency_code": {
                            "type": "object",
                            "additionalProperties": true
                          },
                          "ytd_amount": {
                            "type": "object",
                            "additionalProperties": true
                          }
                        }
                      },
                      "pay_period_details": {
                        "type": "object",
                        "description": "Details about the pay period.",
                        "required": [
                          "pay_amount",
                          "distribution_breakdown",
                          "end_date",
                          "gross_earnings",
                          "iso_currency_code",
                          "pay_date",
                          "pay_frequency",
                          "start_date",
                          "unofficial_currency_code"
                        ],
                        "properties": {
                          "distribution_breakdown": {
                            "type": "object",
                            "additionalProperties": true
                          },
                          "end_date": {
                            "type": "object",
                            "additionalProperties": true
                          },
                          "gross_earnings": {
                            "type": "object",
                            "additionalProperties": true
                          },
                          "iso_currency_code": {
                            "type": "object",
                            "additionalProperties": true
                          },
                          "pay_amount": {
                            "type": "object",
                            "additionalProperties": true
                          },
                          "pay_basis": {
                            "type": "object",
                            "additionalProperties": true
                          },
                          "pay_date": {
                            "type": "object",
                            "additionalProperties": true
                          },
                          "pay_frequency": {
                            "type": "object",
                            "additionalProperties": true
                          },
                          "start_date": {
                            "type": "object",
                            "additionalProperties": true
                          },
                          "unofficial_currency_code": {
                            "type": "object",
                            "additionalProperties": true
                          }
                        }
                      }
                    }
                  }
                },
                "w2s": {
                  "type": "array",
                  "description": "Array of tax form W-2s.",
                  "items": {
                    "type": "object",
                    "description": "W2 is an object that represents income data taken from a W2 tax document.",
                    "required": [
                      "document_metadata",
                      "document_id",
                      "employer",
                      "employee",
                      "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",
                      "box_12",
                      "statutory_employee",
                      "retirement_plan",
                      "third_party_sick_pay",
                      "other",
                      "state_and_local_wages"
                    ],
                    "properties": {
                      "allocated_tips": {
                        "type": "string",
                        "description": "Allocated tips."
                      },
                      "box_12": {
                        "type": "array",
                        "items": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "box_9": {
                        "type": "string",
                        "description": "Contents from box 9 on the W2."
                      },
                      "dependent_care_benefits": {
                        "type": "string",
                        "description": "Dependent care benefits."
                      },
                      "document_id": {
                        "type": "string",
                        "description": "An identifier of the document referenced by the document metadata."
                      },
                      "document_metadata": {
                        "type": "object",
                        "description": "Object representing metadata pertaining to the document.",
                        "required": [
                          "name",
                          "document_type",
                          "download_url",
                          "status"
                        ],
                        "properties": {
                          "document_type": {
                            "type": "object",
                            "additionalProperties": true
                          },
                          "download_url": {
                            "type": "object",
                            "additionalProperties": true
                          },
                          "name": {
                            "type": "object",
                            "additionalProperties": true
                          },
                          "status": {
                            "type": "object",
                            "additionalProperties": true
                          }
                        }
                      },
                      "employee": {
                        "type": "object",
                        "description": "Data about the employee.",
                        "required": [
                          "name",
                          "address",
                          "marital_status",
                          "taxpayer_id"
                        ],
                        "properties": {
                          "address": {
                            "type": "object",
                            "additionalProperties": true
                          },
                          "marital_status": {
                            "type": "object",
                            "additionalProperties": true
                          },
                          "name": {
                            "type": "object",
                            "additionalProperties": true
                          },
                          "taxpayer_id": {
                            "type": "object",
                            "additionalProperties": true
                          }
                        }
                      },
                      "employer": {
                        "type": "object",
                        "description": "Information about the employer on the pay stub.",
                        "required": [
                          "address",
                          "name"
                        ],
                        "properties": {
                          "address": {
                            "type": "object",
                            "additionalProperties": true
                          },
                          "name": {
                            "type": "object",
                            "additionalProperties": true
                          }
                        }
                      },
                      "employer_id_number": {
                        "type": "string",
                        "description": "An employee identification number or EIN."
                      },
                      "federal_income_tax_withheld": {
                        "type": "string",
                        "description": "Federal income tax withheld for the tax year."
                      },
                      "medicare_tax_withheld": {
                        "type": "string",
                        "description": "Medicare tax withheld for the tax year."
                      },
                      "medicare_wages_and_tips": {
                        "type": "string",
                        "description": "Wages and tips from medicare."
                      },
                      "nonqualified_plans": {
                        "type": "string",
                        "description": "Nonqualified plans."
                      },
                      "other": {
                        "type": "string",
                        "description": "Other."
                      },
                      "retirement_plan": {
                        "type": "string",
                        "description": "Retirement plan."
                      },
                      "social_security_tax_withheld": {
                        "type": "string",
                        "description": "Social security tax withheld for the tax year."
                      },
                      "social_security_tips": {
                        "type": "string",
                        "description": "Tips from social security."
                      },
                      "social_security_wages": {
                        "type": "string",
                        "description": "Wages from social security."
                      },
                      "state_and_local_wages": {
                        "type": "array",
                        "items": {
                          "type": "object",
                          "additionalProperties": true
                        }
                      },
                      "statutory_employee": {
                        "type": "string",
                        "description": "Statutory employee."
                      },
                      "tax_year": {
                        "type": "string",
                        "description": "The tax year of the W2 document."
                      },
                      "third_party_sick_pay": {
                        "type": "string",
                        "description": "Third party sick pay."
                      },
                      "wages_tips_other_comp": {
                        "type": "string",
                        "description": "Wages from tips and other compensation."
                      }
                    }
                  }
                }
              }
            }
          },
          "status": {
            "type": "object",
            "description": "Details about the status of the payroll item.",
            "properties": {
              "processing_status": {
                "type": "string",
                "description": "Denotes the processing status for the verification.\n\n`UNKNOWN`: The processing status could not be determined.\n\n`PROCESSING_COMPLETE`: The processing has completed and the user has approved for sharing. The data is available to be retrieved.\n\n`PROCESSING`: The verification is still processing. The data is not available yet.\n\n`FAILED`: The processing failed to complete successfully.\n\n`APPROVAL_STATUS_PENDING`: The processing has completed but the user has not yet approved the sharing of the data."
              }
            }
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "description": "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."
          }
        }
      }
    },
    "request_id": {
      "type": "string",
      "description": "A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive."
    }
  }
}