Forms

Learn about the /forms endpoint.

The forms endpoint returns user inputs from two scenarios:

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

The form object contains details about a given form, and the information that has been submitted by the user through that form.

AttributeTypeDescription
idstring uuidUnique ID of the form.
templatestring uuidThe identifier of the template used.
versionintegerThe version of the template used.
statusstringRepresents 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.
dataarray of objectsContains 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_atstring
timestamp
Time at which the form object was created. Timestamps follow the ISO 8601 standard.
updated_atstring
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

The uploaded documents are returned as objects within data:

AttributeTypeDescription
form_w2objectA list of W-2 documents uploaded by the user. Only relevant if you have configured W-2 documents in Link Customizer.
form_1099objectA list of 1099 documents uploaded by the user. Only relevant if you have configured 1099 documents in Link Customizer.
paystubsobjectA 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:

AttributeTypeDescription
file_idstring uuidUnique ID of the file.
statusstringRepresents the status of the file. Possible values:

AVAILABLE: Signifies that the file can be viewed/downloaded using the URL provided in the url field.
urlstringThe 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.
namestringThe 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.
bytesintegerThe size of the file represented in bytes.
created_atstring timestampTime at which the file was created. Timestamps follow the ISO 8601 standard.
metadatastringHolds 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

Documents OCR'd by a third party are returned as ocr_data objects within metadata for these three document types:

AttributeTypeDescription
form_w2.metadata.ocr_dataobject optionalThe 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_dataobject optionalThe 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_dataobject optionalThe 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

The answers that users provide are returned as a data object with these attributes:

AttributeTypeDescription
income_sourcestringThe 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_providerstringThe 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",
                "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"
    },
}