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",
  "jurisdiction_name": "District of Columbia",
  "parameters": [
    {
      "name": "first_name",
      "label": "First name",
      "description": null,
      "type": "string",
      "options": null,
      "required": true,
      "depends_on": null
    },
    ...
  ]
}
AttributeDescription
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.
jurisdiction_name
string
Nullable string value. The full name of the jurisdiction that is associated with the specific form. The possible values ranges from "Federal" to any U.S. jurisdiction.

Form field validations

TypeAccepted formatsRules
SSN- #########
- ###-##-####
- Does not start with 9, 666, or 000.
- Does not end in 0000.
- The middle digits (third and fourth) are not 00.
- Does not consist of repeated digits (i.e. 000…).
- Only contains numeric characters (with the exception of format characters).
- Is not made up of ascending or descending number sequences like "12345..." or "98765...".
Phone number- ##########- Area Code: first number must be (2-9), second number must be (0-8), and last can be (0-9)
- Central Code: first number must be (2-9), last two digits can be (0-9)
- Line Numbers: Four digits (0-9)
Date- YYYY-MM-DD- Dates in the future are not accepted.
- Date of birth fields are always in the past.
- Date of signatures is on the current date of form submission.

🚧

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.