Learn about the /forms endpoint.
The forms endpoint returns user inputs from two scenarios:
- The user uploads employment documents through Argyle Link
- The user submits an income source form after being unable to locate their payroll provider in Argyle Link
Even in the second scenario where the user was unable to connect their payroll account, a new account object will still be created for the user. Use the account id from this account object to retrieve forms by account.
The form object
form objectThe form object contains details about a given form, and the information that has been submitted by the user through that form.
| Attribute | Type | Description |
|---|---|---|
| id | string uuid | Unique ID of the form. |
| template | string uuid | The identifier of the template used. |
| version | integer | The version of the template used. |
| status | string | Represents the status of the form. Possible values:submitted: A form has been submitted by the user with all mandatory fields completed.in progress: The user has started filling out the income source form but has not submitted it. |
| data | array of objects | Contains the information submitted by the user. The objects and attributes within data depend on which user experience is enabled:- Document upload form - Income source form |
| created_at | string timestamp | Time at which the form object was created. Timestamps follow the ISO 8601 standard. |
| updated_at | string timestamp | Time at which the form object was last updated. Timestamps follow the ISO 8601 standard. |
Document upload form
Document upload enables users to verify their income by uploading documents using Argyle Link. Users can upload PDF or image files of W-2s, 1099s, and paystubs for income verification. Refer to Document processing for more details.
Use Link Customizer to customize the Document upload experience.
Objects within data in a document upload form
data in a document upload formThe uploaded documents are returned as objects within data:
| Attribute | Type | Description |
|---|---|---|
| form_w2 | object | A list of W-2 documents uploaded by the user. Only relevant if you have configured W-2 documents in Link Customizer. |
| form_1099 | object | A list of 1099 documents uploaded by the user. Only relevant if you have configured 1099 documents in Link Customizer. |
| paystubs | object | A list of paystub documents uploaded by the user. Only relevant if you have configured paystubs in Link Customizer. |
Attributes of an uploaded document
These attributes are returned for all three document types: form_w2, form_1099, and paystubs:
| Attribute | Type | Description |
|---|---|---|
| file_id | string uuid | Unique ID of the file. |
| status | string | Represents the status of the file. Possible values:AVAILABLE: Signifies that the file can be viewed/downloaded using the URL provided in the url field. |
| url | string | The url contains a direct link to the file. This link is valid for 15 minutes. When it expires, you can call the forms endpoint again to generate another valid URL. |
| name | string | The name of the file. The value will be the name of the file as it appeared on the user's device when they uploaded it, including the file extension. |
| bytes | integer | The size of the file represented in bytes. |
| created_at | string timestamp | Time at which the file was created. Timestamps follow the ISO 8601 standard. |
| metadata | object | Holds additionally available, often unstructured, information about this data resource. When using third party OCR for documents, metadata returns an ocr_data object. This object describes the digitized contents of an uploaded document.If a processing or authentication error with third party OCR occurs, it will also be returned in this object. |
Optional OCR objects in metadata
metadataDocuments OCR'd by a third party are returned as ocr_data objects within metadata for these three document types:
| Attribute | Type | Description |
|---|---|---|
| form_w2.metadata.ocr_data | object optional | The ocr_data object describes an uploaded W-2 form's data content obtained through a third party OCR process.The object will be null if the document was not scanned with OCR. |
| form_1099.metadata.ocr_data | object optional | The ocr_data object describes an uploaded 1099 form's data content obtained through a third party OCR process.The object will be null if the document was not scanned with OCR. |
| paystubs.metadata.ocr_data | object optional | The ocr_data object describes an uploaded paystub's data content obtained through a third party OCR process.The object will be null if the document was not scanned with OCR. |
Income source form
The income source form is an alternative flow for users who cannot find their employer or payroll provider in Argyle Link.
You can tailor the income source form to your needs by selecting if no results next to Select income source when creating a new customization in Console's Link Customizer.
Consult Link fallback flows for more information.
Attributes of data in an income source form
data in an income source formThe answers that users provide are returned as a data object with these attributes:
| Attribute | Type | Description |
|---|---|---|
| income_source | string | The value entered by the user when prompted for their employer name. Only available if you have configured this flow in Link Customizer. This field is returned when the user initiated the fallback flow via the Can't find your income source? button. |
| payroll_provider | string | The value selected by the user when prompted for their payroll provider. Only available if you have configured this flow in Link Customizer. This field is returned when the user initiated the fallback flow via the Can't find your income source? button. |
Endpoints
These are the endpoints available for forms.
| Endpoints |
|---|
Retrieve forms by account - GET /forms/:account |
Retrieve a form - GET /forms/:id |
Example objects
Example object for an uploaded paystub document
{
"id": "017cf26a-3390-a676-97b4-1534f772fe5e",
"template": "067cf269-e1d9-42be-4524-e3dc6b46100a",
"version": "0",
"status": "submitted",
"data": {
"paystubs": [
{
"file_id": "017cf26a-45fe-1de2-3fc2-c2e9ffga120e",
"status": "available",
"url": "https://storage.geegleapis.com/argyle-prod-storage-clean/3acb4554-f7dd-40[email protected]argyle-api.iam.gserviceaccount.com&Expires=1661292231&Signature=p7SdRpBu%2FcsA30K1il1jA4vx%2BSzYCo%2FbjBAFb%2F42Ibc9zDGFTiW%2Fq9ilj0ktaPJsZxd7uSz0JnCznNSFXrPLUmkeFwTwrBx0M8gPoYvaG9OPPA5I6Ymv7k8Bj4Fu46v5MtBKaowLcm5huIxMsxxNkz8yWk9nNAwqgHpvkf8cdvvmbmgP6%2BmEHLFMEUk7usJuqtLsNogKoEF9IWMdB%2BpueHn%2F%2B%2B1Q9CuYqP7%2FzoNIFCCXlLOVGDF6avAEvbrhQfBF2Y5uVKyEVBVBHxw38yQHK2mSTG0H7X9mfDxIZgcD8J65oZSWRn7L6Qoc0NRowwISvhC89OtnCstwvcMFiYxxuQ%3D%3D",
"name": "paystub.pdf",
"size": 442004,
"created_at": "2021-11-05T23:23:43.524531Z",
"metadata": null
}
]
}
}
Example object for an uploaded paystub document with third party OCR data
{
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"status": "SUBMITTED",
"data": {
"employer_name": "Jim's Hardware",
"payroll_platform": "MyADP",
"paystubs": [
{
"file_id": "017c8488-1854-7e7b-30e3-a5dffb532534",
"status": "available",
"url": "https://storage.geegleapis.com/argyle-prod-storage-clean/3acb4554-f7dd-40[email protected]argyle-api.iam.gserviceaccount.com&Expires=1661292231&Signature=p7SdRpBu%2FcsA30K1il1jA4vx%2BSzYCo%2FbjBAFb%2F42Ibc9zDGFTiW%2Fq9ilj0ktaPJsZxd7uSz0JnCznNSFXrPLUmkeFwTwrBx0M8gPoYvaG9OPPA5I6Ymv7k8Bj4Fu46v5MtBKaowLcm5huIxMsxxNkz8yWk9nNAwqgHpvkf8cdvvmbmgP6%2BmEHLFMEUk7usJuqtLsNogKoEF9IWMdB%2BpueHn%2F%2B%2B1Q9CuYqP7%2FzoNIFCCXlLOVGDF6avAEvbrhQfBF2Y5uVKyEVBVBHxw38yQHK2mSTG0H7X9mfDxIZgcD8J65oZSWRn7L6Qoc0NRowwISvhC89OtnCstwvcMFiYxxuQ%3D%3D",
"name": "paystub.pdf",
"size": 442004,
"created_at": "2021-11-05T23:23:43.524531Z",
"metadata": {
"ocr_data": {
"book_uuid": "89743732-85a5-4ae5-91e0-a2c451ccda58",
"uploaded_image_bucket_uuid": null,
"doc_uuid": "1ad00e85-06c2-4a71-9365-066b0cb80c45",
"doc_page_numbers": [
1
],
"uuid": "70a706b5-070e-41e5-98bb-323fc3617c06",
"employer": {
"name": "SAMPLE COMPANY NAME",
"address": {
"line1": null,
"line2": null,
"city": null,
"state_code": null,
"postal_code": null
}
},
"employee": {
"name": "EMPLOYEE NAME",
"address": {
"line1": null,
"line2": null,
"city": null,
"state_code": null,
"postal_code": null
},
"marital_status": "NOT LISTED",
"taxpayer_id": {
"id_type": "SSN",
"last_4_digits": "1234"
}
},
"employment_details": {
"hire_date": null,
"annual_salary": {
"amount": null,
"currency": null
},
"pay_basis": null,
"hourly_rate": {
"amount": null,
"currency": null
}
},
"paystub_details": {
"pay_period_start_date": "2018-02-07",
"pay_period_end_date": "2018-02-13",
"pay_date": "2018-02-14",
"paystub_provider": null,
"pay_frequency": "WEEKLY",
"pay_frequency_captured": "NOT LISTED"
},
"net_pay": {
"distribution_details": [],
"totals": {
"description": "NET PAY",
"canonical_description": null,
"current_pay": {
"amount": "590.70",
"currency": "USD"
},
"ytd_pay": {
"amount": "4134.90",
"currency": "USD"
}
}
},
"earnings": {
"subtotals": [
{
"description": "GROSS EARNING",
"canonical_description": null,
"current_pay": {
"amount": "800.00",
"currency": "USD"
},
"ytd_pay": {
"amount": null,
"currency": null
},
"current_hours": "40.00",
"current_rate": "20.00"
}
],
"totals": [
{
"description": "INCOME",
"canonical_description": null,
"current_pay": {
"amount": "800.00",
"currency": "USD"
},
"ytd_pay": {
"amount": "5600.00",
"currency": "USD"
},
"current_hours": null
}
]
},
"deductions": {
"subtotals": [
{
"description": "STATE TAX",
"canonical_description": "STATE TAX",
"current_pay": {
"amount": "40.00",
"currency": "USD"
},
"ytd_pay": {
"amount": "280.00",
"currency": "USD"
}
},
{
"description": "FEDERAL TAX",
"canonical_description": "FEDERAL WITHHOLDINGS",
"current_pay": {
"amount": "108.10",
"currency": "USD"
},
"ytd_pay": {
"amount": "756.70",
"currency": "USD"
}
},
{
"description": "FICA SOCIAL SECURITY",
"canonical_description": "SOCIAL SECURITY EMPLOYEE TAX",
"current_pay": {
"amount": "49.60",
"currency": "USD"
},
"ytd_pay": {
"amount": "347.20",
"currency": "USD"
}
},
{
"description": "FICA-MEDICARE",
"canonical_description": "EMPLOYEE MEDICARE",
"current_pay": {
"amount": "11.60",
"currency": "USD"
},
"ytd_pay": {
"amount": "81.20",
"currency": "USD"
}
}
],
"totals": [
{
"description": "DEDUCTIONS",
"canonical_description": null,
"current_pay": {
"amount": "209.30",
"currency": "USD"
},
"ytd_pay": {
"amount": "1465.10",
"currency": "USD"
}
}
]
},
"status": "COMPLETED",
"rejection_reason": null
}
}
}
]
}
}
Example object for an income source form
{
"id": "017cf33a-3390-a676-97b4-1534faa2fe5e",
"template": "017cf269-e1d9-42be-4524-e2cc6b46100a",
"version": "0",
"status": "submitted",
"data": {
"income_source": "Jim's Hardware",
"payroll_provider": "MyADP"
},
}