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.

Form field validations

Type

Accepted formats

Rules

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.