---
updatedAt: 2026-06-18T18:55:55.000Z
agentTools:
  projectIndex: https://docs.checkhq.com/llms.txt
---

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

```json Sample form object
{
  "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
    },
    ...
  ]
}
```

<Table align={["left","left"]}>
  <thead>
    <tr>
      <th>
        Attribute
      </th>

      <th>
        Description
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        `id`  
        _string_
      </td>

      <td>
        Unique identifier for the form.
      </td>
    </tr>

    <tr>
      <td>
        `description`  
        _string_
      </td>

      <td>
        Optional description, eligible to show next to the UI field for additional context.
      </td>
    </tr>

    <tr>
      <td>
        `link`  
        _string_
      </td>

      <td>
        The link to the referenced form. Usually a link to an official government website hosting the form.
      </td>
    </tr>

    <tr>
      <td>
        `revision_date`  
        _YYYY-MM-DD_
      </td>

      <td>
        The date the form was revised.
      </td>
    </tr>

    <tr>
      <td>
        `parameters`  
        _array of objects_
      </td>

      <td>
        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.
      </td>
    </tr>

    <tr>
      <td>
        `name`  
        _string_
      </td>

      <td>
        Unique identifier for the parameter on the form.
      </td>
    </tr>

    <tr>
      <td>
        `label`  
        _string_
      </td>

      <td>
        Human-readable label, eligible to show in a UI label.
      </td>
    </tr>

    <tr>
      <td>
        `description`  
        _string_
      </td>

      <td>
        Optional description, eligible to show next to the UI field for additional context.
      </td>
    </tr>

    <tr>
      <td>
        `type`  
        _string_
      </td>

      <td>
        One of `string`, `number`, `currency`, `percent`, `boolean`, or `select`. This type information can be used to do basic validation. See [Types of form parameters](types-of-form-parameters) for complete descriptions.
      </td>
    </tr>

    <tr>
      <td>
        `options`  
        _list of strings_
      </td>

      <td>
        Optional list of select options, with `value` and human-readable `label` properties. Only populated if parameter `type` is `select`.
      </td>
    </tr>

    <tr>
      <td>
        `required`  
        _boolean_
      </td>

      <td>
        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.
      </td>
    </tr>

    <tr>
      <td>
        `depends_on`  
        _object_
      </td>

      <td>
        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.
      </td>
    </tr>

    <tr>
      <td>
        `jurisdiction_name`  
        _string_
      </td>

      <td>
        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.
      </td>
    </tr>
  </tbody>
</Table>

## Form field validations

<Table align={["left","left","left"]}>
  <thead>
    <tr>
      <th>
        Type
      </th>

      <th>
        Accepted formats
      </th>

      <th>
        Rules
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        SSN
      </td>

      <td>
        * `#########`  
        * `###-##-####`
      </td>

      <td>
        * 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...".
      </td>
    </tr>

    <tr>
      <td>
        Phone number
      </td>

      <td>
        * `##########`
      </td>

      <td>
        * 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)
      </td>
    </tr>

    <tr>
      <td>
        Date
      </td>

      <td>
        * `YYYY-MM-DD`
      </td>

      <td>
        * 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.
      </td>
    </tr>
  </tbody>
</Table>

> 🚧 Note
>
> Employee withholdings are normally configured when employees go through [Check Onboard](https://docs.checkhq.com/docs/check-onboard). Use the Employee Forms API only if you're building a custom integration for employee onboarding.
>
> Consult the [Custom Employee Onboarding Guide](https://docs.checkhq.com/docs/employee-onboarding-api#3-employee-withholdings-api) for more information.