openapi: 3.0.0 info: title: Payroll Documents API version: 1.0.0 description: > Retrieve metadata and PDF's of paystubs, tax forms, and other payroll documents. security: - basicAuth: [] paths: /v2/payroll-documents/{id}: get: summary: Retrieve a payroll document description: Retrieves a payroll document object. parameters: - in: path name: id schema: type: string format: uuid required: true description: ID of the payroll document object to be retrieved. responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/PayrollDocument' example: id: 0183b2c1-02e5-a5e5-38f2-ecd51a5cf3d6 account: 0187c66e-e7e5-811c-b006-2232f00f426a document_number: ced46eb3-7586-3cd7-2418-8eb9482bc3ec available_date: '2019-03-14T17:46:25Z' expiration_date: '2027-03-12T17:46:25Z' employer: GigAndGo employment: 42d6531c-520a-26b9-35c3-b7137a6d205a document_type: drivers-licence document_type_description: Driver's license file_url: api.argyle.com/v2/payroll-documents/{id}/file created_at: '2023-03-13T17:46:28.240Z' updated_at: '2023-03-13T17:46:28.240Z' ocr_data: {} metadata: {} /v2/payroll-documents: get: summary: List all payroll documents description: Returns a paginated list of all payroll document objects. parameters: - in: query name: account schema: type: string format: uuid description: Filter by account ID. - in: query name: user schema: type: string format: uuid description: Filter by user ID. - in: query name: employment schema: type: string format: uuid description: Filter by employment ID. - in: query name: from_available_date schema: type: string format: date-time description: > Filter for payroll documents with an `available_date` on or after this timestamp ([ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)). - in: query name: to_available_date schema: type: string format: date-time description: > Filter for payroll documents with an `available_date` on or before this timestamp ([ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)). - in: query name: limit schema: type: integer description: > Number of payroll document objects returned [per page](/api-guide/overview#pagination). Default: 10. Maximum: 200. - in: query name: cursor schema: type: string description: >- The URL returned in `next` or `previous` used to retrieve another [page](/api-guide/overview#pagination) of results. responses: '200': description: '' content: application/json: schema: type: object properties: next: type: string format: uri nullable: true description: URL for the next page of results, if available. previous: type: string format: uri nullable: true description: URL for the previous page of results, if available. results: type: array items: $ref: '#/components/schemas/PayrollDocument' example: next: >- https://api-sandbox.argyle.com/v2/payroll-documents?cursor=ZXhhbXBsZV9jdXJzb3I previous: null results: - id: 0186dc02-05b6-b83f-c366-b39a267e1570 account: 0185a8b8-60eb-80ca-7482-5f24504573f7 document_number: null available_date: '2020-05-13T17:25:59Z' expiration_date: null employer: Whole Goods employment: 0186a27d-e5c6-735a-a359-6315b34d544c document_type: payout-statement document_type_description: null file_url: api.argyle.com/v2/payroll-documents/{id}/file created_at: '2023-03-13T17:27:01.501Z' updated_at: '2023-03-13T17:27:01.501Z' ocr_data: {} metadata: {} - id: 0176dc14-bb37-402a-7be1-f5261759fae7 account: 0187c66e-e7e5-811c-b006-2232f00f426a document_number: ced46eb3-7586-3cd7-2418-8eb9482bc3ec available_date: '2019-03-14T17:46:25Z' expiration_date: '2027-03-12T17:46:25Z' employer: GigAndGo employment: 42d6531c-520a-26b9-35c3-b7137a6d205a document_type: drivers-licence document_type_description: Driver's license file_url: api.argyle.com/v2/payroll-documents/{id}/file created_at: '2023-03-13T17:46:28.240Z' updated_at: '2023-03-13T17:46:28.240Z' ocr_data: {} metadata: {} components: securitySchemes: basicAuth: type: http scheme: basic description: Username = api_key_id, Password = api_key_secret schemas: 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/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. Also the `payroll_document` ID value of the [paystub object](/api-reference/paystubs#object). 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/payroll-documents#list). 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. This static URL redirects to a download page that requires [Argyle authentication headers](/api-guide/overview#authentication). See the dropdown below for more information. **Implementation requirements for client-side applications** 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. 2. [Basic authentication headers](https://docs.argyle.com/api-guide/overview#authentication) for Argyle must be appended to the file download request. 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. properties: form_type: type: string description: | The specific type of 1099 or W-2 document. **W-2 and W-2c** W-2: Wage and Tax Statement W-2c: Corrected Wage and Tax Statement - **`control_no_d`**: Identifies the W-2 in the payer's records. - **`comp_1`**: The amount of wages, tips, and other compensation. - **`fed_income_tax_2`**: The amount of federal income tax withheld. - **`ss_wages_3`**: The amount of social security wages. - **`ss_tax_4`**: The amount of social security tax withheld. - **`med_wages_5`**: The amount of Medicare wages and tips. - **`med_tax_6`**: The amount of Medicare tax withheld. - **`ss_tips_7`**: The amount of social security tips. - **`tips_8`**: The amount of allocated tips. - **`verification_9`**: Code used to identify the accuracy of the form's contents for electronic tax returns. - **`benefits_10`**: The amount of dependent care benefits. - **`nonqualified_11`**: The amount of contributions made to a non-qualified savings plan. - **`uncollected_ss_RRTA_12a`**: The amount of uncollected social security or RRTA tax on tips. - **`uncollected_med_tax_12b`**: The amount of uncollected Medicare tax on tips. - **`insurance_12c`**: The amount of taxable costs of group-term life insurance over $50,000. - **`plan_401k_12d`**: The amount of elective deferrals related to contributions to 401-k plans. - **`other_14`**: Used to report additional tax information. - **`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. - **`state_wages_16`**: The amount of state wages, tips, etc. - **`state_income_tax_17`**: The amount of state income tax. - **`local_wages_18`**: The amount of local wages, tips, etc. - **`local_income_tax_19`**: The amount of local income tax. - **`locality_name_20`**: The name of the locality where taxes indicated in the `local_income_tax_19` field are paid. **1099-NEC** 1099-NEC: Non-Employee Compensation - **`account_no`**: A code that is unique to the recipient and the form, for example, a bank account number, employee ID, etc. - **`comp_1`**: The amount of non-employee compensation. - **`fed_inc_tax_4`**: The amount of federal income tax withheld. - **`state_tax_5`**: The amount of state tax withheld. - **`state_no_6`**: The abbreviated name of the state and the payer's state tax identification number. - **`state_inc_7`**: The amount of state income. **1099-SSA** 1099-SSA: Social Security Benefits - **`recipient_name_1`**: The name of the recipient. - **`benefits_3`**: The amount of benefits paid. - **`benefits_ssa_4`**: The amount of benefits repaid to the Social Security Administration (SSA). - **`net_benefits_5`**: The amount of net benefits. - **`fed_inc_tax_6`**: The amount of voluntary federal income tax withholding. - **`claim_no`**: The social security number under which a claim is filed or benefits are paid. **1099-MISC** 1099-MISC: Miscellaneous Income - **`account_no`**: A code that is unique to the recipient and the form, for example, a bank account number, employee ID, etc. - **`rent_1`**: The amount of rental income. - **`royalties_2`**: The amount of royalty income. - **`other_inc_3`**: Other income. - **`fed_inc_4`**: The amount of federal income tax withheld. - **`fishing_5`**: The amount of fishing boat proceeds. - **`med_care_6`**: The amount of medical and health care payment. - **`comp_7`**: The amount of non-employee compensation. - **`crop_insurance_10`**: The amount of crop insurance proceeds. - **`golden_parachute_13`**: The amount of excess golden parachute payments. - **`gross_attorney_14`**: The amount of gross proceeds paid to an attorney. - **`sec_409a_defer_15a`**: The amount of section 409A deferrals. - **`sec_409a_inc_15b`**: The amount of section 409A income. - **`state_tax_16`**: The amount of state tax withheld. - **`state_no_17`**: The abbreviated name of the state and the payer's state tax identification number. - **`state_inc`**: The amount of state income. **1099-INT** 1099-INT: Interest Income - **`payer_rtn`**: The payer's RTN (Routing and Transit Number). - **`account_no`**: A code that is unique to the recipient and the form, for example, a bank account number, employee ID, etc. - **`interest_1`**: The amount of interest income. - **`withdraw_penalty_2`**: The amount of early withdrawal penalty. - **`interest_obligations_3`**: The amount of interest earned on U.S. savings bonds or Treasury notes, bills, or bonds. - **`fed_inc_tax_4`**: The amount of federal income tax withheld. - **`investment_5`**: The amount of investment expenses. - **`foreign_tax_6`**: The amount of foreign tax paid. - **`foreign_possession_7`**: Shows the country or U.S. possession to which the foreign tax was paid. **1099-R** 1099-R: Distributions from Pensions and Annuities - **`control_no`**: The code that uniquely identifies a particular 1099-R document in the employer's records. - **`gross_1`**: The amount of gross distribution. - **`tax_amount_2a`**: The amount of distribution that is taxable. - **`fed_inc_tax_4`**: The amount of federal income tax withheld. - **`distribution_code_7`**: A code that identifies the type of distribution received. - **`distribution_percent_9`**: The percentage of total distribution received. - **`state_tax_14`**: The amount of state tax withheld. - **`state_no_15`**: The abbreviated name of the state and the payer's state tax identification number. **1099-G** 1099-G: Certain Government Payments - **`a_unemployment_comp_1`**: The amount of unemployment compensation. - **`a_state_inc_tax_2`**: The amount of state or local income tax refunds, credits, or offsets. - **`a_benefits_this_year_3`**: The amount of benefits repaid for the current year. - **`a_benefits_prev_year_3`**: The amount of benefits repaid for the previous year. - **`a_fed_inc_tax_4`**: The amount of federal income tax withheld. - **`b_unemployment_comp_1`**: The amount of unemployment compensation, paid family leave. - **`b_state_inc_tax_2`**: The amount of state or local income tax refunds, credits, or offsets. - **`b_benefits_this_year_3`**: The amount of benefits repaid for the current year. - **`b_benefits_prev_year_3`**: The amount of benefits repaid for the previous year. - **`b_fed_inc_tax_4`**: The amount of federal income tax withheld. **1099-K** 1099-K: Payment Card and Third Party Network Transactions - **`pse_name_phone`**: Payment settlement entity's name and telephone number. - **`account_no`**: A code that is unique to the recipient and the form, for example, a bank account number, employee ID, etc. - **`gross_1a`**: Gross amount of payment card/third-party network transactions. - **`gross_1b`**: The amount of Card Not Present transactions. - **`category_code_2`**: Merchant category code. - **`no_transactions_3`**: Number of payment transactions. - **`fed_inc_tax_4`**: The amount of federal income tax withheld. - **`january_5a`**: The total reportable payment transactions for this month. - **`february_5b`**: The total reportable payment transactions for this month. - **`march_5c`**: The total reportable payment transactions for this month. - **`april_5d`**: The total reportable payment transactions for this month. - **`may_5e`**: The total reportable payment transactions for this month. - **`june_5f`**: The total reportable payment transactions for this month. - **`july_5g`**: The total reportable payment transactions for this month. - **`august_5h`**: The total reportable payment transactions for this month. - **`september_5i`**: The total reportable payment transactions for this month. - **`october_5j`**: The total reportable payment transactions for this month. - **`november_5k`**: The total reportable payment transactions for this month. - **`december_5l`**: The total reportable payment transactions for this month. - **`state_6`**: State. - **`state_id_7`**: State identification number. - **`state_income_8`**: The amount of state income tax withheld. 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: - >- field_name invalid - non numeric value, original value: severity: type: number format: float description: > The severity of the encountered issue. - `0.0`: The field was found, but its value was unclear or obfuscated. - `0.5`: A field or value was not found, but unclear if it needed to be present. - `1.0`: A field or value was not found. enum: - 0 - 0.5 - 1 confidence: type: string description: > Indicator of how successful the scanning process went. - **`EXACT_MATCH`**: No errors found. - **`HIGH`**: 1 error was found. - **`MEDIUM`**: 2 errors were found. - **`LOW`**: 3 errors were found. - **`NO_MATCH`**: 4 or more errors were found. This typically indicates the document's `form_type` did not match the scanned document. 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. - **`invalid_document`**: The document was empty, cropped, missing required fields, or otherwise incomplete. - **`type_mismatch`**: The document does not match the classified type. - **`unrecognized_document_type`**: The document could not be classified. - **`unsupported_document_type`**: The document type is not supported. - **`unsupported_document_subtype`**: The document sub-type (e.g., 1099-C) is not supported. - **`unknown`**: An unknown issue occurred. The Argyle team will automatically be notified and will investigate. 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.