Forms

Learn about the /forms endpoint.

Argyle introduced forms to surface questions and prompts to users and capture their inputs in various scenarios such as:

  • A user is unable to locate their income source in Argyle Link
  • A user fails to log in to their income source in Argyle Link

In either of these situations, users will be given the option to fill out an Argyle form. Forms may include free-text fields, drop-down selections or document upload prompts. The Link Customizer can be used to configure certain aspects of the Argyle forms to better meet your needs and your customers' expectations.

Though the user is unable to connect when they are submitting a form, a special account linked to a form Link item is created. You can find a user's form submission with this account ID.

As the form framework evolves, additional field types and enhanced levels of customization will be made available.

Document upload

If the document upload flow is enabled in the Link Customizer, the uploaded documents will be returned as a form object with the data fields described below. Refer to the Document Upload guide for more details.

Attributes


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: Signifies that a form has been submitted by the user with all mandatory fields completed.


data.employer_name string

The value entered by the user when prompted for their employer name. Only available if you have configured this form in Link Customizer. This field will be present if the user initiated the document upload flow via the Can't find your income source? button.


data.payroll_platform string

The value selected by the user when prompted for their payroll platform. Only available if you have configured this form in Link Customizer. This field will be present if the user initiated the document upload flow via the Can't find your income source? button.


data.paystubs array of objects

A list of paystub documents uploaded by the user. Only relevant if you have configured paystubs in Link Customizer.


data.form_1099 array of objects

A list of 1099 documents uploaded by the user. Only relevant if you have configured 1099 documents in Link Customizer.


data.form_w2 array of objects

A list of W-2 documents uploaded by the user. Only relevant if you have configured W-2 documents in Link Customizer.


📘

These fields are listed in the array of objects for all three document types: data.paystubs, data.form_1099, and data.form_w2:

.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 timestamp

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


.metadata string

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


📘

metadata.ocr_data objects returned by the OCR for Documents feature are only available for form_1099 and form_w2 document types:

data.form_1099.metadata.ocr_data object optional

The ocr_data object describes the contents of a 1099 form retrieved through the OCR process.

The object will be null if the document was not scanned with OCR.


data.form_w2.metadata.ocr_data object optional

The ocr_data object describes the contents of a W-2 form retrieved through the OCR process.

The object will be null if the document was not scanned with OCR.


ocr_data example object for 1099-NEC form
{
   "form_type":"1099-NEC",
   "omb_no":"1545-0116",
   "year":"2020",
   "form":{
      "recipient":{
         "name":"John Smith",
         "address":{
            "city":"Norton",
            "country":null,
            "line1":"4321 S. Jackson St Apt 987C",
            "line2":null,
            "postal_code":"45678",
            "state":"MA"
         }
      },
      "recipient_tin":"***-**-0193",
      "payer":{
         "name":"Peak Performance Publishing LLC",
         "address":{
            "city":"Ambler",
            "country":null,
            "line1":"118 Mary Ambler Way",
            "line2":null,
            "postal_code":"19002",
            "state":"PA"
         }
      },
      "payer_tin":"46-5237939",
      "account_no":"zeno000046945",
      "comp_1":"22796.50",
      "fed_inc_tax_4":"0.00",
      "state_tax_5":null,
      "state_no_6":null,
      "state_inc_7":null
   },
   "warnings":[
      {
         "field_name":"state_inc_7",
         "message":"state_inc_7 value empty/bad format",
         "severity":0.0
      }
   ],
   "confidence":"EXACT_MATCH",
   "ocr_page_count":1
}


Endpoints

Endpoints

Retrieve forms by account - GET /forms/:account

Retrieve a form - GET /forms/:id

Example object

{
   "id":"3fa85f64-5717-4562-b3fc-2c963f66afa6",
   "template": "0180937e-818b-2577-b6f0-81c02117c19c",
   "version": "0",
   "status":"submitted",
   "data":{
      "employer_name":"Jim's Hardware",
      "payroll_platform":"MyADP",
      "paystubs":[
         {
            "file_id":"017c8488-1854-7e7b-30e3-a5dffb532534",
            "status":"available",
            "url":"https://argyle-api-prod-uploads.storage.googleapis.com/e0c16ace-0628-25da-8928-5dffd7a7b1d1-20200016",
            "name":"paystub.pdf",
            "size":4096,
            "created_at":"2021-10-15T15:18:04.121210Z",
            "metadata":null
         }
      ],
      "form_1099":[
         {
            "file_id":"017c8488-1854-7e7b-30e3-a5dffb532534",
            "status":"available",
            "url":"https://argyle-api-prod-uploads.storage.googleapis.com/110a6cd9-2cd5-3a8e-b8db-3fae4e96b58a-20200016",
            "name":"1099.pdf",
            "size":4096,
            "created_at":"2021-10-15T15:18:04.121210Z",
            "metadata":null
         }
      ],
      "form_w2":[
         {
            "file_id":"017c8488-1854-7e7b-30e3-a5dffb532534",
            "status":"available",
            "url":"https://argyle-api-prod-uploads.storage.googleapis.com/7c21d391-a7df-4ad5-b7d3-d2d7a6b3e740-20200016",
            "name":"w2.pdf",
            "size":4096,
            "created_at":"2021-10-15T15:18:04.121210Z",
            "metadata":null
         }
      ]
   }
}

Income source form

You can provide an alternative flow for users who cannot find their income source or payroll provider in Argyle Link.

Use Link Customizer to enable the Form experience. If the user cannot find their income source on Link’s Search screen, they can select the Can’t find your income source? button and search among the payroll providers covered by Argyle to access their accounts. If the user cannot find their payroll provider, Link prompts them to enter their income source and payroll provider details.

Consult Link fallback flows for more information.

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

Attributes


data.employer_name string

The value entered by the user when prompted for their employer name. This field will be present if the user initiated the document upload flow via the Can't find your income source? button.


data.payroll_platform string

The value selected by the user when prompted for their payroll platform. This field will be present if the user initiated the document upload flow via the Can't find your income source? button.


Example

{
   "id":"3fa85f64-5717-4562-b3fc-2c963f66afa6",
   "status":"submitted",
   "data":{
      "employer_name":"Jim's Hardware",
      "payroll_platform":"MyADP",
   }
}