The form object

Represents a tax form for collecting information for an employee's withholdings.

Each form detail contains a parameters list, each representing a form field eligible to show to an onboarding employee.

{
  "id": "frm_VjOW9Qq93M7UGxi6eocg",
  "description": "District of Columbia D-4",
  "link": "https://www.exim.gov/sites/default/files/newsreleases/DCStateTaxForm-1.pdf",
  "revision_date": "2010-12-01",
  "parameters": [
    {
      "name": "first_name",
      "label": "First name",
      "description": null,
      "type": "string",
      "options": null,
      "required": true,
      "depends_on": null
    },
    ...
  ]
}

Attribute

Description

id
string

Unique identifier for the form.

description
string

Optional description, eligible to show next to the UI field for additional context.

link
string

The link to the referenced form. Usually a link to an official government website hosting the form.

revision_date
YYYY-MM-DD

The date the form was revised.

parameters
array of objects

An array of name-value pair objects, which represent fields on the form eligible to present to onboarding employees. Possible objects include:
name, label, description, type, options, depends_on, and required.

name
string

Unique identifier for the parameter on the form.

label
string

Human-readable label, eligible to show in a UI label.

description
string

Optional description, eligible to show next to the UI field for additional context.

type
string

One of string, number, currency, or select. This type information can be used to do basic validation.

options
list of strings

Optional list of select options, with value and human-readable label properties. Only populated if parameter type is select.

required
boolean

Boolean value, indicating whether a parameter should be considered "required" when validating form input client-side. If the parameter has a value for depends_on, it should only be considered "required" if its dependency condition is met.

depends_on
object

Optional object, indicating whether the parameter "depends" on another parameter's value matching a particular pattern. name is the identifier of the other parameter, and value_matches is a simple regex pattern that the other parameter must match.

🚧

Note

Employee withholdings are normally configured when employees go through Check Onboard. Use the Employee Forms API only if you're building a custom integration for employee onboarding.

Consult the Custom Employee Onboarding Guide for more information.