Working with Employment Forms

The Onboarding Forms API is designed to help onboard employees for employment. At a basic level, it provides mechanisms to know which forms apply to an employee's state at a given date, and to render any one of those forms. You can use the information returned in the form list and detail responses to inform the UI and copy presented to the user.

🚧

Worksheets

We strongly recommend you link to the official form in the UI, so employees can review worksheets and intermediate fields. The parameters Check surfaces are the "final" parameters filled out by the employee for the employer to use when withholding taxes. Check does not surface worksheet parameters.

List available forms

GET /forms will return all the current revisions of forms that Check supports. It accepts the following query parameters to optionally filter the results or return alternative results:

• state: filter for forms that apply to the provided state. Must be a two-digit state abbreviation. Typically, this will be the two federal forms (I-9 and W-4), and the state withholding form.

• lang: prefer returning forms in the provided ISO 639-1 language code. Fall back to English forms if preferred language form does not exist.

Example list response

{
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "frm_ntKOaUm6qIJabIBmqLXU",
      "description": "Federal I-9",
      "link": "https://www.uscis.gov/system/files_force/files/form/i-9-paper-version.pdf",
      "revision_date": "2019-10-21"
    },
    {
      "id": "frm_FBt3oC1x28IrZELkhb21",
      "description": "Federal W-4",
      "link": "https://www.irs.gov/pub/irs-pdf/fw4.pdf",
      "revision_date": "2020-01-01"
    },
    {
      "id": "frm_j7NxXAhh4ZlAsJ6tbP1A",
      "description": "California DE-4",
      "link": "https://www.edd.ca.gov/pdf_pub_ctr/de4.pdf",
      "revision_date": "2020-02-01"
    },
    ...
  ]
}

Retrieve a specific form

GET /forms/:form_id will fetch a single form, as well as its parameters.

📘

We recommend caching this response for 24 hours if fetching many forms, as each form is unlikely to change within that period of time.

Each form detail contains a parameters list, each representing a form field eligible to show to an onboarding employee. Each parameter has the following attributes:

• name: Unique identifier for the parameter on the form.
• label: Human-readable label, eligible to show in a UI label.
• description: Optional description, eligible to show next to the UI field for additional context.
• type: One of string, number, currency, or select. This type information can be used to do basic validation.
• options: Optional list of select options, with value and human-readable label properties. Only populated if parameter type is select.
• depends_on: 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.
• required: 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.

🚧

Check does not validate any logic communicated by depends_on or required. These are purely client-side hints for structuring and validating UI fields in a logical way that matches the underlying form. For example, you can hide or show, or enable/disable dependent fields.

Example detail response

{
  "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
    },
    ...
    {
      "name": "ssn",
      "label": "Social Security number",
      "description": null,
      "type": "string",
      "options": null,
      "required": true,
      "depends_on": null
    },
    ...
    {
      "name": "additional_amount",
      "label": "Additional amount",
      "description": "Add a whole dollar amount if any, you would like deducted from your paycheck for D.C Income Tax each pay period.",
      "type": "currency",
      "options": null,
      "required": false,
      "depends_on": null
    },
    {
      "name": "exempt",
      "label": "Exempt",
      "description": "Before claiming exemption from withholding, read form and, if qualified, choose 'Yes'.",
      "type": "select",
      "options": [
        {
          "label": "No",
          "value": "no"
        },
        {
          "label": "Yes",
          "value": "yes"
        }
      ],
      "required": false,
      "depends_on": null
    },
    {
      "name": "domicile_is_other_state",
      "label": "My domicile is a state other than the District of Columbia",
      "description": "Fill in the state in which you reside if it is not the District of Columbia.",
      "type": "select",
      "options": [
        {
          "label": "No",
          "value": "no"
        },
        {
          "label": "Yes",
          "value": "yes"
        }
      ],
      "required": true,
      "depends_on": {
        "name": "exempt",
        "value_matches": "yes"
      }
    },
    ...
  ]
}

Render a form

POST /forms/:form_id/render accepts a JSON object with a list of parameters, each containing a name and value. The endpoint returns either a PDF binary file or base-64 encoded PDF in JSON, based on the Accept header being application/pdf or application/json. There is no validation done past basic type validation (e.g. string, number, currency, select) on value. Any parameters not provided will not be rendered in the rendered PDF. Check does not store these rendered forms.

Example render request body

{
  "parameters": [
    {
      "name": "first_name",
      "value": "Tony"
    }
  ]
}