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
- #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_dataobjectoptional
- 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.
- The
- #—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.
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}
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
- Retrieve a document with the supplied ID.
- This request returns a document object if you provided a valid identifier.
- #idstring (uuid)required
The identifier of the document to be retrieved.
1curl --request GET \
2 --url https://api.argyle.com/v1/documents/{id} \
3 --header 'accept: application/json' \
4 --header 'content-type: application/json'
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
- List all documents.
- This request returns an object with a
results
property that contains an array of up tolimit
document objects.
- #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.
- #limitintegeroptional
The number of document objects to be returned. The default is 10. Max value is 200.
1curl --request GET \
2 --url https://api.argyle.com/v1/documents?limit=2 \
3 --header 'accept: application/json' \
4 --header 'content-type: application/json'
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]