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 GET \
 '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,
           "effective_start": null,
           "effective_start_required": false,
           "default_value": false,
           
       }
   ]
}

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

name: (string) A unique identifier for the attribute.
value: (string, nullable) The assigned value for the attribute.
type: (string) One of string, number, currency, percent, boolean, or select, which specifies the type of the value.
options: (list, nullable) Optional list of selected options. Each option has human-readable label and value properties. Only populated when the attribute is of type select or boolean.
label: (string, nullable) A human-readable label that can be shown when rendering a form input.
description: (string, nullable) An optional description that can be used to display additional context when rendering a form input.
effective_start: (string, nullable) The effective start date of the assigned value in YYYY-MM-DD format.
effective_start_required: (boolean) Whether or not the company-defined attribute value must be submitted with an explicit effective date.
default_value: (string, nullable) The default value used for the attribute for informational purposes. The default_value for an attribute with a non-empty options list will always correspond to the value of one of those options. Note: The API does not automatically populate the attribute with this value.

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,value and optionally effective_start objects. In the case that no effective_start is defined, if the attribute has not yet been initialized it will be set to 1900-01-01, otherwise by default it will be set to the current date:

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

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.