>  Switch To Link 5 and API v2 Documentation

Forms

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

Attributes
  • #
    idstring (uuid)

    Unique ID of the form.

  • #
    templatestring (uuid)

    The identifier of the template used.

  • #
    versionstring

    The version of the template used.

  • #
    statusstring (enum)

    Represents the status of the 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](ISO 8601) standard.

  • #
    dataobject

    Contains the information submitted by the user.

    The objects and attributes within data depend on which user experience is enabled.

  • #
    income_sourcestring

    Only for income source forms.

    The value entered by the user when prompted for their employer name. Only available if you have configured this flow in Flows. This field is returned when the user initiated the fallback flow via the Can't find your income source? button.

  • #
    payroll_providerstring

    Only for income source forms.

    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.

  • #
    form_w2 | form_1099 | paystubsobject

    Information for one of these uploaded document types.

  • #
    file_idstring (uuid)

    Unique ID of the file.

  • #
    statusstring

    The status of the file. AVAILABLE when the file can be viewed/downloaded using the URL provided in the url field.

  • #
    urlstring

    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.

  • #
    namestring

    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.

  • #
    sizeinteger

    The size of the file represented in bytes.

  • #
    created_atstring (timestamp)

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

  • #
    metadataobject

    Holds additionally available, often unstructured, information about this data resource.


    When using third party OCR for documents, contains 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 metadata object.

  • #
    ocr_dataobject

    Third party OCR data for the uploaded document, otherwise null if the document was not scanned by OCR.



Example — Uploaded document
1{
2  "id": "017cf26a-3390-a676-97b4-1534f772fe5e",
3  "template": "067cf269-e1d9-42be-4524-e3dc6b46100a",
4  "version": "0",
5  "status": "submitted",
6  "data": {
7    "paystubs": [
8      {
9        "file_id": "017cf26a-45fe-1de2-3fc2-c2e9ffga120e",
10        "status": "available",
11        "url": "www.storage-url.com",
12        "name": "paystub.pdf",
13        "size": 442004,
14        "created_at": "2021-11-05T23:23:43.524531Z",
15        "metadata": null
16      }
17    ]
18  }
19}
Example — Income source form
1{
2  "id": "017cf33a-3390-a676-97b4-1534faa2fe5e",
3  "template": "017cf269-e1d9-42be-4524-e2cc6b46100a",
4  "version": "0",
5  "status": "submitted",
6  "data": {
7    "income_source": "Jim's Hardware",
8    "payroll_provider": "MyXYZ"
9  }
10}

#Retrieve forms by account ID

get/v1/forms
  • Retrieve all forms associated with an account.
  • This request returns an object with a results property that contains an array of all the form objects associated with the provided account ID.
Query parameters
  • #
    accountstring (uuid)
    required

    The identifier of the account associated with the forms to be retrieved.

Example Request
1curl --request GET \
2     --url https://api.argyle.com/v1/forms?{account}={uuid} \
3     --header 'accept: application/json' \
4     --header 'content-type: application/json'
Example Response
1{
2  "id": "01809380-de04-c6ad-10d9-70ee6958ed83",
3  "template": "0180937e-818b-2577-b6f0-81c02117c19c",
4  "version": "0",
5  "status": "submitted",
6  "data": {
7    "employer_name": "Suzy's Cupcakes",
8    "payroll_platform": "I don't know"
9  },
10  "created_at": "2022-05-05T09:15:37.895590Z",
11  "updated_at": "2022-05-05T09:15:39.422112Z"
12}

#Retrieve forms by ID

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

    The identifier of the form to be retrieved.

Example Request
1curl --request GET \
2     --url https://api.argyle.com/v1/forms/{id} \
3     --header 'accept: application/json' \
4     --header 'content-type: application/json'
Example Response
1{
2  "id": "01809380-de04-c6ad-10d9-70ee6958ed83",
3  "template": "0180937e-818b-2577-b6f0-81c02117c19c",
4  "version": "0",
5  "status": "submitted",
6  "data": {
7    "employer_name": "Suzy's Cupcakes",
8    "payroll_platform": "I don't know"
9  },
10  "created_at": "2022-05-05T09:15:37.895590Z",
11  "updated_at": "2022-05-05T09:15:39.422112Z"
12}
Updating Argyle status...
© 2024 Argyle Systems Inc.argyle.com