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
},
...
]
}
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. |
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
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.