>  Switch To Link 5 and API v2 Documentation

Documents

Learn about the /documents endpoint.

The document object contains information from payroll documents that are retrieved and processed by Argyle after a user connects a payroll account. The contents of each specific document can be found in the document object's metadata.


#The document object

Attributes
  • #
    idstring (uuid)

    Unique ID of the document associated with a user's payroll account.

  • #
    accountstring (uuid)

    ID of the payroll account associated with the document.

  • #
    employerstring

    The name of the company or entity that employs the user.

  • #
    document_numberstring

    The identification number on the document.

  • #
    document_typestring (enum)

    Describes the document type.

  • #
    document_type_descriptionstring

    A free-form text describing the document's type—for example, W-2 Form 2019.

  • #
    expiration_datestring (timestamp)

    The expiration date of the document. Timestamps follow the ISO 8601 standard.

  • #
    available_datestring (timestamp)

    Represents the timestamp when the document was made available to the employee.

  • #
    file_urlstring

    If available, file_url contains a direct link to the file. This link is valid for 15 minutes. When it expires, you can call the /documents endpoint again to generate another valid URL.

  • #
    metadataobject

    Metadata holds additional available, often unstructured, information about this data resource.

  • #
    ocr_dataobject
    optional

    • The ocr_data object describes the contents of the document retrieved through a connected payroll account and scanned by Argyle.

    • Use the /forms endpoint for uploaded documents.

    • The object will be null if the document was not scanned and its data was not extracted.

    • More information about fields within the ocr_data object can be found in the dropdowns below.

  • #
    —Properties specific to a particular form_type.

  • #
    form_typestring (enum)

    The specific type of 1099 or W-2 document.

  • #
    omb_nostring

    OMB reference number.

  • #
    yearstring

    Calendar year.

  • #
    formobject

    Information scanned from the payroll document.

  • #
    recipientobject

  • #
    namestring

    Recipient name, as it appears on the form.

  • #
    addressobject

    Recipient address, as it appears on the form.

  • #
    recipient_tinstring

    Recipient's tax identification number.

    Not present in 1099-SSA forms.

  • #
    payerobject

  • #
    namestring

    Payer name, as it appears on the form.

  • #
    addressobject

    Payer address, as it appears on the form.

  • #
    payer_tinstring

    Payer's tax identification number.

    Not present in 1099-SSA forms.

  • #
    warningsarray of objects

    Information on scan quality and missing fields.

  • #
    field_namestring

    Which field encountered the error.

  • #
    messagestring (enum)

    The field_name and warning message.

  • #
    severityfloat (enum)

    The severity of the encountered issue.

  • #
    confidencestring (enum)

    Indicator of how successful the scanning process went.

  • #
    ocr_page_countinteger

    Number of pages scanned.

  • #
    errorstring (enum)
    optional

    An error was encountered during document retrieval.

  • #
    created_atstring (timestamp)

    Time at which the document object was created. Timestamps follow the ISO 8601 standard.

  • #
    updated_atstring (timestamp)

    Time at which the document object was last updated. Timestamps follow the ISO 8601 standard.



Example
1{
2  "id": "110a6cd9-2cd5-3a8e-b8db-3fae4e96b58a",
3  "account": "e0c16ace-0628-25da-8928-5dffd7a7b1d1",
4  "employer": "walmart",
5  "created_at": "2020-11-18T12:27:30.478199Z",
6  "updated_at": "2020-11-29T08:33:41.525392Z",
7  "document_number": "T1234567",
8  "document_type": "W-2",
9  "document_type_description": "W-2 Form 2019",
10  "expiration_date": "null",
11  "available_date": "2020-02-15T00:00:00Z",
12  "file_url": "https://argyle-api-prod-uploads.storage.googleapis.com/e0c16ace-0628-25da-8928-5dffd7a7b1d1-20200016",
13  "metadata": {}
14}
Example — with OCR data
1{
2  "id": "110a6cd9-2cd5-3a8e-b8db-3fae4e96b58a",
3  "account": "e0c16ace-0628-25da-8928-5dffd7a7b1d1",
4  "employer": "walmart",
5  "created_at": "2020-11-18T12:27:30.478199Z",
6  "updated_at": "2020-11-29T08:33:41.525392Z",
7  "document_number": "T1234567",
8  "document_type": "W-2",
9  "document_type_description": "W-2 Form 2019",
10  "expiration_date": "null",
11  "available_date": "2020-02-15T00:00:00Z",
12  "file_url": "https://argyle-api-prod-uploads.storage.googleapis.com/e0c16ace-0628-25da-8928-5dffd7a7b1d1-20200016",
13  "metadata": {
14    "ocr_data": {
15      "form_type": "W-2",
16      "omb_no": null,
17      "year": "2019",
18      "form": {
19        "recipient": {
20          "name": "John Smith",
21          "address": {
22            "city": "Norton",
23            "country": null,
24            "line1": "4 Jackson St",
25            "line2": null,
26            "postal_code": "75211",
27            "state": "MA"
28          }
29        },
30        "recipient_tin": "123-12-1234",
31        "payer": {
32          "name": "EAST COAST ASSEMBLERS INC",
33          "address": {
34            "city": "Lake Worth",
35            "country": null,
36            "line1": "6586 Hypolouxo Road",
37            "line2": "Suite 145",
38            "postal_code": "33467",
39            "state": "FL"
40          }
41        },
42        "payer_tin": "20-0388460",
43        "control_no_d": "86O78 6805",
44        "comp_1": "1540.83",
45        "fed_income_tax_2": "147.41",
46        "ss_wages_3": "1540.83",
47        "ss_tax_4": "95.53",
48        "med_wages_5": "1540.83",
49        "med_tax_6": "22.34",
50        "ss_tips_7": null,
51        "tips_8": null,
52        "verification_9": null,
53        "benefits_10": null,
54        "nonqualified_11": null,
55        "uncollected_ss_RRTA_12a": null,
56        "uncollected_med_tax_12b": null,
57        "insurance_12c": null,
58        "plan_401k_12d": null,
59        "other_14": null,
60        "employers_state_15": null,
61        "state_wages_16": null,
62        "state_income_tax_17": null,
63        "local_wages_18": "N/A",
64        "local_income_tax_19": "N/A",
65        "locality_name_20": "N/A"
66      },
67      "warnings": [
68        {
69          "field_name": "ss_tips_7",
70          "message": "ss_tips_7 value empty/bad format",
71          "severity": 0
72        },
73        {
74          "field_name": "tips_8",
75          "message": "tips_8 value empty/bad format",
76          "severity": 0
77        },
78        {
79          "field_name": "benefits_10",
80          "message": "benefits_10 value empty/bad format",
81          "severity": 0
82        },
83        {
84          "field_name": "nonqualified_11",
85          "message": "nonqualified_11 value empty/bad format",
86          "severity": 0
87        },
88        {
89          "field_name": "uncollected_ss_RRTA_12a",
90          "message": "uncollected_ss_RRTA_12a value empty/bad format",
91          "severity": 0
92        },
93        {
94          "field_name": "uncollected_med_tax_12b",
95          "message": "uncollected_med_tax_12b value empty/bad format",
96          "severity": 0
97        },
98        {
99          "field_name": "insurance_12c",
100          "message": "insurance_12c value empty/bad format",
101          "severity": 0
102        },
103        {
104          "field_name": "plan_401k_12d",
105          "message": "plan_401k_12d value empty/bad format",
106          "severity": 0
107        },
108        {
109          "field_name": "employers_state_15",
110          "message": "employers_state_15 not found",
111          "severity": 0
112        },
113        {
114          "field_name": "state_wages_16",
115          "message": "state_wages_16 not found",
116          "severity": 0
117        },
118        {
119          "field_name": "state_income_tax_17",
120          "message": "state_income_tax_17 not found",
121          "severity": 0
122        },
123        {
124          "field_name": "other_14",
125          "message": "other_14 value empty/bad format",
126          "severity": 0
127        },
128        {
129          "field_name": "verification_9",
130          "message": "verification_9 value empty/bad format",
131          "severity": 0
132        },
133        {
134          "field_name": "omb_no",
135          "message": "omb_no not found",
136          "severity": 1
137        }
138      ],
139      "confidence": "HIGH",
140      "ocr_page_count": 1
141    }
142  }
143}

#Retrieve a document

get/v1/documents/{id}
  • Retrieve a document with the supplied ID.
  • This request returns a document object if you provided a valid identifier.
Path parameters
  • #
    idstring (uuid)
    required

    The identifier of the document to be retrieved.

Example Request
1curl --request GET \
2     --url https://api.argyle.com/v1/documents/{id} \
3     --header 'accept: application/json' \
4     --header 'content-type: application/json'
Example Response
1{
2  "id": "0180519e-71f0-14ed-72d6-e31cfc8ef22a",
3  "account": "0180519e-64f5-0107-603a-a460f85c2c50",
4  "document_number": "aa9d80be-dade-4b04-8017-665806691cc0",
5  "document_type": "1099",
6  "document_type_description": "1099 Form 2020",
7  "expiration_date": null,
8  "file_url": "www.documents-upload-holder.com",
9  "employer": "amazin",
10  "available_date": "2020-01-31T00:00:00Z",
11  "metadata": {},
12  "created_at": "2022-04-22T14:13:00.017106Z",
13  "updated_at": "2022-04-22T14:13:10.326250Z"
14}

#List documents

get/v1/documents
  • List all documents.
  • This request returns an object with a results property that contains an array of up to limit document objects.
Query parameters
  • #
    accountstring (uuid)
    optional

    Return only documents for the account with the provided ID.

  • #
    userstring (uuid)
    optional

    Return only documents for the user with the provided ID.

  • #
    document_typestring (enum)
    optional

    Return only documents of the specified document_type.

  • #
    from_available_datestring (timestamp)
    optional

    Return only documents with available_date on or after the provided timestamp. Timestamps with dates conforming to the ISO 8601 standard are accepted.

  • #
    to_available_datestring (timestamp)
    optional

    Return only documents with available_date on or before the provided timestamp. Timestamps with dates conforming to the ISO 8601 standard are accepted.

  • #
    limitinteger
    optional

    The number of document objects to be returned. The default is 10. Max value is 200.

Example Request
1curl --request GET \
2     --url https://api.argyle.com/v1/documents?limit=2 \
3     --header 'accept: application/json' \
4     --header 'content-type: application/json'
Example Response
1[
2  {
3    "id": "0180519e-71f0-14ed-72d6-e31cfc8ef22a",
4    "account": "0180519e-64f5-0107-603a-a460f85c2c50",
5    "document_number": "aa9d80be-dade-4b04-8017-665806691cc0",
6    "document_type": "1099",
7    "document_type_description": "1099 Form 2020",
8    "expiration_date": null,
9    "file_url": "https://storage.googleapis.com/argyle-prod-storage-clean/scanner/sandbox/1099-misc-sarah.pdf?GoogleAccessId=argyle-storage-service-prod@argyle-api.iam.gserviceaccount.com&Expires=1650646843&Signature=ZdwjkQBuBfa17X62oYvLO5%2Bda%2F6oAPpHSWQLST1knNRBEoqONPfz0ErtDa2yQs9AclIcF9bu3JMrRLWw%2FWNTULtZo8P83G%2FkMFAW9dj1Xi8Y8eFLxhnp19OaNUpGwaSoZHij2Keu5KX7appE9iutfdLM30cGBvN992XHcSmh94bwXs0iPuWeWMlNZcDHL1q3tKZoLIdb8clxhU0c3q%2B3SBzdacwhMPem5%2FM7sLRLP5JxaCPu70n95FLU2rA7c72VefvOHvZyaUP%2BuJKU2oI%2FKNUfuO3wGocbCe6sQ2qNDJF0iHsJ%2Fepz%2FJ0sBSNMSX9u4yz8wWGuD2EnFWVKe5z%2FdA%3D%3D",
10    "employer": "amazin",
11    "available_date": "2020-01-31T00:00:00Z",
12    "metadata": {},
13    "created_at": "2022-04-22T14:13:00.017106Z",
14    "updated_at": "2022-04-22T14:13:10.326250Z"
15  },
16  {
17    "id": "0180519e-719d-2d39-ac17-e3750b386932",
18    "account": "0180519e-64f5-0107-603a-a460f85c2c50",
19    "document_number": "ef856a8a-f2a0-4804-a6fa-f36e89bfdf02",
20    "document_type": "W-2",
21    "document_type_description": "W-2 Form 2021",
22    "expiration_date": null,
23    "file_url": "https://storage.googleapis.com/argyle-prod-storage-clean/scanner/sandbox/w2-sarah.pdf?GoogleAccessId=argyle-storage-service-prod@argyle-api.iam.gserviceaccount.com&Expires=1650646843&Signature=qhCDnSd1CeTg70sOHOjWSEXaMoalNWCptEyRlN6KN4wBbtjwoxSKiMrmrqPq6zDs5WjtQhBckrtnejhL1YGKHK5KhC8uJT6DMuZuYypubaegXk2QBGL0CNR%2BgPAWGoGtn9O6ckwYmNrcdLHlCcgifByF19GQKJuxPHFSsNn%2BDmnOahxrH%2BJd2Nzf8%2Bq%2FZ1ajXf7B3xDbt7RGlPSTdhL1iQwErO1TXzE1l4r%2B1WP2oi%2BWgXSDR1eX5ZI99mf5ZdSz70gXMJbwntbcHIekUD69DrDhbX7KzVpRsYVkyzdqIFIl78vgGtFBRZLGQNFMj9m8aiIRAeq0bla2VernoCQZlA%3D%3D",
24    "employer": "amazon",
25    "available_date": "2021-01-31T00:00:00Z",
26    "metadata": {},
27    "created_at": "2022-04-22T14:12:59.933542Z",
28    "updated_at": "2022-04-22T14:13:10.331485Z"
29  }
30]
Updating Argyle status...
© 2024 Argyle Systems Inc.argyle.com