Argyle · Schema
PayrollDocument
Employment DataPayrollIncome VerificationGig EconomyFinancial DataEmployment HistoryEarned Wage AccessDirect Deposit
Properties
| Name | Type | Description |
|---|---|---|
| id | string | Unique ID of the payroll document object. Also the `payroll_document` ID value of the [paystub object](/api-reference/paystubs#object). |
| account | string | ID of the account where the payroll document was sourced. |
| document_number | string | Identification number that appears on the payroll document. |
| available_date | string | 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 | string | Timestamp ([ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)) when payroll document (such as a driver's license) expires. |
| employer | string | Employer name. |
| employment | string | [Employment](/api-reference/employments) ID. Can be used as a filter when [listing payroll documents](/api-reference/partners-data-sets/list-all-payroll-documents). |
| document_type | string | 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. |
| document_type_description | string | Description of the payroll document type. |
| file_url | string | URL linking to the original payroll document file. This static URL redirects to a download page that requires [Argyle authentication headers](/api-guide/overview#authentication). See the dropdown belo |
| created_at | string | Timestamp ([ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)) when the payroll document object was created. |
| updated_at | string | Timestamp ([ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)) when a property value of the payroll document object most recently changed. |
| ocr_data | object | Argyle scans and provides additional information for 1099 and W-2 documents retrieved from connected payroll accounts. |
| metadata | object | Additional, non-categorized information. |
JSON Schema
{
"$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."
}
}
}