{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://raw.githubusercontent.com/api-evangelist/argyle/refs/heads/main/json-schema/payrolldocument.json",
  "title": "PayrollDocument",
  "type": "object",
  "example": {
    "id": "0176dc14-bb37-402a-7be1-f5261759fae7",
    "account": "0187c66e-e7e5-811c-b006-2232f00f426a",
    "document_number": "ced46eb3-7586-3cd7-2418-8eb9482bc3ec",
    "available_date": "2021-03-14T17:46:25Z",
    "expiration_date": null,
    "employer": "GigAndGo",
    "employment": "42d6531c-520a-26b9-35c3-b7137a6d205a",
    "document_type": "1099",
    "document_type_description": "1099 Form 2020",
    "file_url": "api.argyle.com/partners/v2/payroll-documents/{id}/file",
    "created_at": "2023-03-13T17:46:28.240Z",
    "updated_at": "2023-03-13T17:46:28.240Z",
    "ocr_data": {
      "form_type": "1099-MISC",
      "omb_no": "1545-0115",
      "year": "2020",
      "form": {
        "recipient": {
          "name": "BOB JONES",
          "address": {
            "city": null,
            "country": null,
            "line1": "759 VICTORIA PLAZA",
            "line2": null,
            "postal_code": "10014",
            "state": "NY"
          }
        },
        "recipient_tin": "111-11-1112",
        "payer": {
          "name": "WAREHOUSE SERVICES INC",
          "address": {
            "city": "SEATTLE",
            "country": null,
            "line1": "202 WESTLAKE AVE N (55",
            "line2": null,
            "postal_code": "98109",
            "state": "WA"
          }
        },
        "payer_tin": "11-1111112",
        "account_no": "000110CHIC/NHO",
        "rent_1": null,
        "royalties_2": null,
        "other_inc_3": null,
        "fed_inc_4": null,
        "fishing_5": null,
        "med_care_6": null,
        "comp_7": null,
        "crop_insurance_10": null,
        "golden_parachute_13": null,
        "gross_attorney_14": null,
        "sec_409a_defer_15a": null,
        "sec_409a_inc_15b": null,
        "state_tax_16": null,
        "state_no_17": null,
        "state_inc": null
      },
      "warnings": [
        {
          "field_name": "rent_1",
          "message": "rent_1 value empty/bad format",
          "severity": 0
        },
        {
          "field_name": "royalties_2",
          "message": "royalties_2 value empty/bad format",
          "severity": 0
        },
        {
          "field_name": "other_inc_3",
          "message": "other_inc_3 value empty/bad format",
          "severity": 0
        },
        {
          "field_name": "fed_inc_4",
          "message": "fed_inc_4 value empty/bad format",
          "severity": 0
        },
        {
          "field_name": "fishing_5",
          "message": "fishing_5 value empty/bad format",
          "severity": 0
        },
        {
          "field_name": "med_care_6",
          "message": "med_care_6 value empty/bad format",
          "severity": 0
        },
        {
          "field_name": "comp_7",
          "message": "comp_7 not found",
          "severity": 0
        },
        {
          "field_name": "crop_insurance_10",
          "message": "crop_insurance_10 value empty/bad format",
          "severity": 0
        },
        {
          "field_name": "golden_parachute_13",
          "message": "golden_parachute_13 value empty/bad format",
          "severity": 0
        },
        {
          "field_name": "gross_attorney_14",
          "message": "gross_attorney_14 value empty/bad format",
          "severity": 0
        },
        {
          "field_name": "sec_409a_defer_15a",
          "message": "sec_409a_defer_15a value empty/bad format",
          "severity": 0
        },
        {
          "field_name": "sec_409a_inc_15b",
          "message": "sec_409a_inc_15b not found",
          "severity": 0
        },
        {
          "field_name": "state_tax_16",
          "message": "state_tax_16 value empty/bad format",
          "severity": 0
        },
        {
          "field_name": "state_no_17",
          "message": "state_no_17 value empty/bad format",
          "severity": 0
        },
        {
          "field_name": "state_inc",
          "message": "state_inc value empty/bad format",
          "severity": 0
        }
      ],
      "confidence": "EXACT_MATCH",
      "ocr_page_count": 1
    },
    "metadata": null
  },
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid",
      "description": "Unique ID of the payroll document object.\n\nAlso the `payroll_document` ID value of the [paystub object](/api-reference/paystubs#object).\n"
    },
    "account": {
      "type": "string",
      "format": "uuid",
      "description": "ID of the account where the payroll document was sourced."
    },
    "document_number": {
      "type": "string",
      "description": "Identification number that appears on the payroll document."
    },
    "available_date": {
      "type": "string",
      "format": "date-time",
      "description": "Timestamp ([ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)) when the payroll document was made available to the user on the underlying payroll system."
    },
    "expiration_date": {
      "type": "string",
      "format": "date-time",
      "description": "Timestamp ([ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)) when payroll document (such as a driver's license) expires."
    },
    "employer": {
      "type": "string",
      "description": "Employer name."
    },
    "employment": {
      "type": "string",
      "description": "[Employment](/api-reference/employments) ID. Can be used as a filter when [listing payroll documents](/api-reference/partners-data-sets/list-all-payroll-documents).\n"
    },
    "document_type": {
      "type": "string",
      "description": "The type of payroll document, as returned by the payroll system. The following values are the most common, but document_type is not restricted to these values.",
      "enum": [
        "payout-statement",
        "W-2",
        "W-4",
        "W-9",
        1095,
        "1095-C",
        1099,
        "profile-picture",
        "drivers-license",
        "vehicle-insurance",
        "vehicle-registration",
        "vehicle-inspection",
        "other"
      ]
    },
    "document_type_description": {
      "type": "string",
      "description": "Description of the payroll document type."
    },
    "file_url": {
      "type": "string",
      "description": "URL linking to the original payroll document file.\n\nThis static URL redirects to a download page that requires [Argyle authentication headers](/api-guide/overview#authentication). See the dropdown below for more information.\n\n**Implementation requirements for client-side applications**\n  1. Ensure your HTTP client or library (e.g. Axios, Python requests, etc.) or similar tool is configured to pursue redirects. Most tools support this functionality.\n\n  2. [Basic authentication headers](https://docs.argyle.com/api-guide/overview#authentication) for Argyle must be appended to the file download request.\n"
    },
    "created_at": {
      "type": "string",
      "format": "date-time",
      "description": "Timestamp ([ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)) when the payroll document object was created."
    },
    "updated_at": {
      "type": "string",
      "format": "date-time",
      "description": "Timestamp ([ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)) when a property value of the payroll document object most recently changed."
    },
    "ocr_data": {
      "type": "object",
      "description": "Argyle scans and provides additional information for 1099 and W-2 documents retrieved from connected payroll accounts.\n",
      "properties": {
        "form_type": {
          "type": "string",
          "description": "The specific type of 1099 or W-2 document.\n\n  **W-2 and W-2c**\n    W-2: Wage and Tax Statement\n    W-2c: Corrected Wage and Tax Statement\n\n    - **`control_no_d`**: Identifies the W-2 in the payer's records.  \n    - **`comp_1`**: The amount of wages, tips, and other compensation.  \n    - **`fed_income_tax_2`**: The amount of federal income tax withheld.  \n    - **`ss_wages_3`**: The amount of social security wages.  \n    - **`ss_tax_4`**: The amount of social security tax withheld.  \n    - **`med_wages_5`**: The amount of Medicare wages and tips.  \n    - **`med_tax_6`**: The amount of Medicare tax withheld.  \n    - **`ss_tips_7`**: The amount of social security tips.  \n    - **`tips_8`**: The amount of allocated tips.  \n    - **`verification_9`**: Code used to identify the accuracy of the form's contents for electronic tax returns.  \n    - **`benefits_10`**: The amount of dependent care benefits.  \n    - **`nonqualified_11`**: The amount of contributions made to a non-qualified savings plan.  \n    - **`uncollected_ss_RRTA_12a`**: The amount of uncollected social security or RRTA tax on tips.  \n    - **`uncollected_med_tax_12b`**: The amount of uncollected Medicare tax on tips.  \n    - **`insurance_12c`**: The amount of taxable costs of group-term life insurance over $50,000.  \n    - **`plan_401k_12d`**: The amount of elective deferrals related to contributions to 401-k plans.  \n    - **`other_14`**: Used to report additional tax information.  \n    - **`employers_state_15`**: Lists the states for which the employer withheld the taxes and to which state the employer remitted the taxes, indicated by the employer's state ID number.  \n    - **`state_wages_16`**: The amount of state wages, tips, etc.  \n    - **`state_income_tax_17`**: The amount of state income tax.  \n    - **`local_wages_18`**: The amount of local wages, tips, etc.  \n    - **`local_income_tax_19`**: The amount of local income tax.  \n    - **`locality_name_20`**: The name of the locality where taxes indicated in the `local_income_tax_19` field are paid.  \n\n  **1099-NEC**\n    1099-NEC: Non-Employee Compensation\n\n    - **`account_no`**: A code that is unique to the recipient and the form, for example, a bank account number, employee ID, etc.  \n    - **`comp_1`**: The amount of non-employee compensation.  \n    - **`fed_inc_tax_4`**: The amount of federal income tax withheld.  \n    - **`state_tax_5`**: The amount of state tax withheld.  \n    - **`state_no_6`**: The abbreviated name of the state and the payer's state tax identification number.  \n    - **`state_inc_7`**: The amount of state income.  \n\n  **1099-SSA**\n    1099-SSA: Social Security Benefits\n\n    - **`recipient_name_1`**: The name of the recipient.  \n    - **`benefits_3`**: The amount of benefits paid.  \n    - **`benefits_ssa_4`**: The amount of benefits repaid to the Social Security Administration (SSA).  \n    - **`net_benefits_5`**: The amount of net benefits.  \n    - **`fed_inc_tax_6`**: The amount of voluntary federal income tax withholding.  \n    - **`claim_no`**: The social security number under which a claim is filed or benefits are paid.  \n\n  **1099-MISC**\n    1099-MISC: Miscellaneous Income\n\n    - **`account_no`**: A code that is unique to the recipient and the form, for example, a bank account number, employee ID, etc.  \n    - **`rent_1`**: The amount of rental income.  \n    - **`royalties_2`**: The amount of royalty income.  \n    - **`other_inc_3`**: Other income.  \n    - **`fed_inc_4`**: The amount of federal income tax withheld.  \n    - **`fishing_5`**: The amount of fishing boat proceeds.  \n    - **`med_care_6`**: The amount of medical and health care payment.  \n    - **`comp_7`**: The amount of non-employee compensation.  \n    - **`crop_insurance_10`**: The amount of crop insurance proceeds.  \n    - **`golden_parachute_13`**: The amount of excess golden parachute payments.  \n    - **`gross_attorney_14`**: The amount of gross proceeds paid to an attorney.  \n    - **`sec_409a_defer_15a`**: The amount of section 409A deferrals.  \n    - **`sec_409a_inc_15b`**: The amount of section 409A income.  \n    - **`state_tax_16`**: The amount of state tax withheld.  \n    - **`state_no_17`**: The abbreviated name of the state and the payer's state tax identification number.  \n    - **`state_inc`**: The amount of state income.  \n\n  **1099-INT**\n    1099-INT: Interest Income\n\n    - **`payer_rtn`**: The payer's RTN (Routing and Transit Number).  \n    - **`account_no`**: A code that is unique to the recipient and the form, for example, a bank account number, employee ID, etc.  \n    - **`interest_1`**: The amount of interest income.  \n    - **`withdraw_penalty_2`**: The amount of early withdrawal penalty.  \n    - **`interest_obligations_3`**: The amount of interest earned on U.S. savings bonds or Treasury notes, bills, or bonds.  \n    - **`fed_inc_tax_4`**: The amount of federal income tax withheld.  \n    - **`investment_5`**: The amount of investment expenses.  \n    - **`foreign_tax_6`**: The amount of foreign tax paid.  \n    - **`foreign_possession_7`**: Shows the country or U.S. possession to which the foreign tax was paid.  \n\n  **1099-R**\n    1099-R: Distributions from Pensions and Annuities\n\n    - **`control_no`**: The code that uniquely identifies a particular 1099-R document in the employer's records.  \n    - **`gross_1`**: The amount of gross distribution.  \n    - **`tax_amount_2a`**: The amount of distribution that is taxable.  \n    - **`fed_inc_tax_4`**: The amount of federal income tax withheld.  \n    - **`distribution_code_7`**: A code that identifies the type of distribution received.  \n    - **`distribution_percent_9`**: The percentage of total distribution received.  \n    - **`state_tax_14`**: The amount of state tax withheld.  \n    - **`state_no_15`**: The abbreviated name of the state and the payer's state tax identification number.  \n\n  **1099-G**\n    1099-G: Certain Government Payments\n\n    - **`a_unemployment_comp_1`**: The amount of unemployment compensation.  \n    - **`a_state_inc_tax_2`**: The amount of state or local income tax refunds, credits, or offsets.  \n    - **`a_benefits_this_year_3`**: The amount of benefits repaid for the current year.  \n    - **`a_benefits_prev_year_3`**: The amount of benefits repaid for the previous year.  \n    - **`a_fed_inc_tax_4`**: The amount of federal income tax withheld.  \n    - **`b_unemployment_comp_1`**: The amount of unemployment compensation, paid family leave.  \n    - **`b_state_inc_tax_2`**: The amount of state or local income tax refunds, credits, or offsets.  \n    - **`b_benefits_this_year_3`**: The amount of benefits repaid for the current year.  \n    - **`b_benefits_prev_year_3`**: The amount of benefits repaid for the previous year.  \n    - **`b_fed_inc_tax_4`**: The amount of federal income tax withheld.  \n\n  **1099-K**\n    1099-K: Payment Card and Third Party Network Transactions\n\n    - **`pse_name_phone`**: Payment settlement entity's name and telephone number.  \n    - **`account_no`**: A code that is unique to the recipient and the form, for example, a bank account number, employee ID, etc.  \n    - **`gross_1a`**: Gross amount of payment card/third-party network transactions.  \n    - **`gross_1b`**: The amount of Card Not Present transactions.  \n    - **`category_code_2`**: Merchant category code.  \n    - **`no_transactions_3`**: Number of payment transactions.  \n    - **`fed_inc_tax_4`**: The amount of federal income tax withheld.  \n    - **`january_5a`**: The total reportable payment transactions for this month.  \n    - **`february_5b`**: The total reportable payment transactions for this month.  \n    - **`march_5c`**: The total reportable payment transactions for this month.  \n    - **`april_5d`**: The total reportable payment transactions for this month.  \n    - **`may_5e`**: The total reportable payment transactions for this month.  \n    - **`june_5f`**: The total reportable payment transactions for this month.  \n    - **`july_5g`**: The total reportable payment transactions for this month.  \n    - **`august_5h`**: The total reportable payment transactions for this month.  \n    - **`september_5i`**: The total reportable payment transactions for this month.  \n    - **`october_5j`**: The total reportable payment transactions for this month.  \n    - **`november_5k`**: The total reportable payment transactions for this month.  \n    - **`december_5l`**: The total reportable payment transactions for this month.  \n    - **`state_6`**: State.  \n    - **`state_id_7`**: State identification number.  \n    - **`state_income_8`**: The amount of state income tax withheld.  \n",
          "enum": [
            "W-2",
            "W-2c",
            "1099-NEC",
            "1099-SSA",
            "1099-MISC",
            "1099-INT",
            "1099-R",
            "1099-G",
            "1099-K"
          ]
        },
        "omb_no": {
          "type": "string",
          "description": "OMB reference number."
        },
        "year": {
          "type": "string",
          "description": "Calendar year."
        },
        "form": {
          "type": "object",
          "description": "Information scanned from the payroll document.",
          "properties": {
            "recipient": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string",
                  "description": "Recipient name, as it appears on the form."
                },
                "address": {
                  "type": "object",
                  "description": "Recipient address, as it appears on the form.",
                  "properties": {
                    "city": {
                      "type": "string",
                      "description": "Name of the city, town, district, or similar regional entity."
                    },
                    "country": {
                      "type": "string",
                      "description": "Two-letter country code ([ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) format)."
                    },
                    "line1": {
                      "type": "string",
                      "description": "Address-Line 1, usually street address or P.O. Box information."
                    },
                    "line2": {
                      "type": "string",
                      "description": "Address-Line 2, usually the apartment or unit number."
                    },
                    "postal_code": {
                      "type": "string",
                      "description": "Zip code, or equivalent."
                    },
                    "state": {
                      "type": "string",
                      "description": "State, county, province, region, or equivalent."
                    }
                  }
                }
              }
            },
            "recipient_tin": {
              "type": "string",
              "description": "Recipient's tax identification number."
            },
            "payer": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string",
                  "description": "Payer name, as it appears on the form."
                },
                "address": {
                  "type": "object",
                  "description": "Payer address, as it appears on the form.",
                  "properties": {
                    "city": {
                      "type": "string",
                      "description": "Name of the city, town, district, or similar regional entity."
                    },
                    "country": {
                      "type": "string",
                      "description": "Two-letter country code ([ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) format)."
                    },
                    "line1": {
                      "type": "string",
                      "description": "Address-Line 1, usually street address or P.O. Box information."
                    },
                    "line2": {
                      "type": "string",
                      "description": "Address-Line 2, usually the apartment or unit number."
                    },
                    "postal_code": {
                      "type": "string",
                      "description": "Zip code, or equivalent."
                    },
                    "state": {
                      "type": "string",
                      "description": "State, county, province, region, or equivalent."
                    }
                  }
                }
              }
            },
            "payer_tin": {
              "type": "string",
              "description": "Payer's tax identification number."
            }
          }
        },
        "warnings": {
          "type": "array",
          "description": "Information on scan quality and missing fields.",
          "items": {
            "type": "object",
            "properties": {
              "field_name": {
                "type": "string",
                "description": "Which field encountered the error."
              },
              "message": {
                "type": "string",
                "description": "The `field_name` and warning message.",
                "enum": [
                  "not found",
                  "value empty/bad format",
                  "obfuscated",
                  "obfuscated last two digits given",
                  "obfuscated last four digits given",
                  "field_name had non numeric chars removed, original value: <value>",
                  "field_name invalid - non numeric value, original value: <value>"
                ]
              },
              "severity": {
                "type": "number",
                "format": "float",
                "description": "The severity of the encountered issue.\n\n- `0.0`: The field was found, but its value was unclear or obfuscated.\n- `0.5`: A field or value was not found, but unclear if it needed to be present.\n- `1.0`: A field or value was not found.\n",
                "enum": [
                  0.0,
                  0.5,
                  1.0
                ]
              }
            }
          }
        },
        "confidence": {
          "type": "string",
          "description": "Indicator of how successful the scanning process went.\n\n- **`EXACT_MATCH`**: No errors found.  \n- **`HIGH`**: 1 error was found.  \n- **`MEDIUM`**: 2 errors were found.  \n- **`LOW`**: 3 errors were found.  \n- **`NO_MATCH`**: 4 or more errors were found. This typically indicates the document's `form_type` did not match the scanned document.  \n",
          "enum": [
            "EXACT_MATCH",
            "HIGH",
            "MEDIUM",
            "LOW",
            "NO_MATCH"
          ]
        },
        "ocr_page_count": {
          "type": "integer",
          "description": "Number of pages scanned."
        },
        "error": {
          "type": "string",
          "description": "An error was encountered during document retrieval.\n\n- **`invalid_document`**: The document was empty, cropped, missing required fields, or otherwise incomplete.  \n- **`type_mismatch`**: The document does not match the classified type.  \n- **`unrecognized_document_type`**: The document could not be classified.  \n- **`unsupported_document_type`**: The document type is not supported.  \n- **`unsupported_document_subtype`**: The document sub-type (e.g., 1099-C) is not supported.  \n- **`unknown`**: An unknown issue occurred. The Argyle team will automatically be notified and will investigate.  \n",
          "enum": [
            "invalid_document",
            "type_mismatch",
            "unrecognized_document_type",
            "unsupported_document_type",
            "unsupported_document_subtype",
            "unknown"
          ],
          "nullable": true
        }
      }
    },
    "metadata": {
      "type": "object",
      "description": "Additional, non-categorized information."
    }
  }
}