action plaid_credit_payroll_income_get {
  label: "Retrieve a user's payroll information"
  description: "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."
  provider: plaid
  method: POST
  path: "/credit/payroll_income/get"
  encoding: json
  input: {
    type: "object"
    description: "CreditPayrollIncomeGetRequest defines the request schema for `/credit/payroll_income/get`."
    properties: {
      client_id: {
        type: "string"
        description: "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: {
        type: "string"
        description: "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: {
        type: "string"
        description: "The user token associated with the User data is being requested for."
      }
    }
  }
  output: {
    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"
                          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"
                          additionalProperties: true
                        }
                        employee: {
                          type: "object"
                          additionalProperties: true
                        }
                        employer: {
                          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."
      }
    }
  }
}