Collecting Employee Information From Employers

Employees generally provide payroll-related information, such as their personal information or Social Security Number, themselves. There are cases in which an employer is required to provide this information on an employee's behalf. For example, in some states, an employer might be required to report if an employee is a corporate officer or a family member of the owner. Check knows when these employee attributes must be collected from the employer and surfaces them through our API, Console, and Onboard.

This guide describes how to collect this information from employers using the Check API.

Retrieving and updating company-defined attributes

First, use the /employees/<employee_id>/company_defined_attributes endpoint to access the list of employee attributes:

curl -X POST \
 'https://sandbox.checkhq.com/employees/<EMPLOYEE_ID>/company_defined_attributes' \
 -H 'Content-Type: application/json' \
 -H 'Authorization: Bearer <API_KEY>'

If Check determines that the employer must specify that the employee is a corporate officer, the API would respond with the following:

{
   "company_defined_attributes": [
       {
           "name": "corporate_officer",
           "value": null,
           "type": "boolean",
           "label": "Corporate officer status",
           "description": "This employee is an owner or corporate officer of the business",
           "options": null
       }
   ]
}

The response contains a list of company_defined_attributes that must be collected, each containing the following fields:

  • name: A unique identifier for the attribute.
  • value: The assigned value, represented as a string.
  • type: One of string, number, currency, or select, which specifies the type of the value.
  • options: Optional list of selected options. Each option has a human-readable label and value properties. Only populated when the attribute is of type select.
  • label: A human-readable label that can be shown when rendering a form input.
  • description: An optional description that can be used to display additional context when rendering a form input.

Check provides the label and description fields to facilitate the creation of form inputs in your application. For example, you may want to collect this information by showing an extra step to the employer during the employee creation flow.

To set values for the desired attributes, send a PATCH request to the same endpoint with a a list of name and value pairs:

curl -XPOST https://sandbox.checkhq.com/employees/<EMPLOYEE_ID>/company_defined_attributes -d '{
   "company_defined_attributes": [
       {"name": "corporate_officer", "value": "true"}
   ]
}

Onboard status

The state of an employee’s company-defined attribute will affect their onboard status. Depending on the attribute, if a value is not set, the employee’s onboard_status could either be in the blocking or needs_attention state. If the employee’s status is not completed, either set the values through the API as described above, or redirect the employer to Check Onboard to add this information for the affected employees.

To determine if an employee’s onboard_status is not in a completed state due to a company-defined attribute, inspect the employee’s onboard_object and look for company_defined_attributes in either the blocking or remaining steps.


Did this page help you?