Custom Employee Onboarding

If you opt not to use Check Onboard for employees you can directly submit all necessary information through our API. After determining the employee's onboarding status, you must complete three steps to configure an employee in our system.

Determine Employee onboard status

To query whether a particular employee is completely onboarded look at the onboard object on the employee resource. This object has a status field, the possible values of which are blocking, needs_attention, and completed. onboard.status will start off with a value of blocking. In order to transition to a status of completed, you must complete the three steps enumerated below. For more information on the onboard object, see the onboard status guide.

📘
Workplaces and onboard status
Adding or removing Workplaces for an employee can change onboard.status, as a different set of forms may be required for that employee, especially if the new workplace is in a different state.

1. Configure Employee payment preferences

We currently support two methods of paying employees: manual and direct deposit. Manual corresponds to an employer handing a paper check to the employee, and direct deposit corresponds to Check depositing money directly into the employee’s bank account. For employees who prefer to be paid manually, you should update their payment_method_preference to manual:

curl -X PATCH \ 
https://sandbox.checkhq.com/employees/{<EMPLOYEE_ID>} \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <API_KEY>' \
  -d '{
    “payment_method_preference”: “manual”,
  }'

In order for an employee’s pay to be sent to their linked bank account, you will need to update their “payment_method_preference” to direct_deposit like so:

curl -X PATCH \
https://sandbox.checkhq.com/employees/{<EMPLOYEE_ID>} \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <API_KEY>' \
  -d '{
      “payment_method_preference”: “direct_deposit”,
  }'

You will also need to link the employee’s bank account. Check exposes an API which allows you to supply us with bank account information that you’ve already collected through another provider, such as Plaid.

You can create Bank Account resources like so:

curl -X POST \
https://api.checkhq.com/bank_accounts \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <API_KEY>' \
  -d '{
      "employee": "<EMPLOYEE_ID>",
      "raw_bank_account": {
          "institution_name": "Chase",
          "subtype": "checking",
          "account_number": "123456789",
          "routing_number": "021000021"
      }
  }'

When a bank account is created for an employee it will show up on the employee object. For example:

{
    "id": "<EMPLOYEE_ID>",
    "first_name": "Tony",
    "last_name": "Stark",
    "bank_accounts": ["<BANK_ACCOUNT_ID>"],
      ...
}

For more information about how Check verifies bank accounts, please see our guide on Bank Account Verification.

2. Provide Employee SSN

In order to file various tax documents we will need an employee’s Social Security Number (SSN). You can set an employee's SSN at time of creation using the write-only ssn parameter like so:

curl -X POST \
https://sandbox.checkhq.com/employees \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <API_KEY>' \
  -d '{
      "first_name": "Bob",
      ...,
      “ssn”: “987654321”,
  }'

You can also modify this value on an existing employee:

curl -X PATCH https://sandbox.checkhq.com/employees/{<EMPLOYEE_ID>} \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <API_KEY>' \
  -d '{
    “ssn”: “987654321”,
  }'

The employee resource will surface information about an employee’s current SSN through the read-only field ssn_last_four in the response body:

{
   "id":"<EMPLOYEE_ID>",
   "first_name":"Bob",
   "last_name":"Smith",
   "ssn_last_four":"4321",
   ...
}

(Note: If an employee cannot obtain an SSN because of their residency status, the “ssn” field can be used to store their Individual Tax Identification Number).

3. Capture Employee withholdings

Employees have a list of necessary forms to complete before we consider them onboarded. The list is determined by their residence address and workplace addresses. You can query the status of an employee’s onboard forms like so:

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

Example response body:

{
    "next": null,
    "previous": null,
    "results": [
        {
            "form": {
                "id": "frm_FBt3oC1x28IrZELkhb21",
                "description": "Federal W-4",
                “type”: “employee_withholding”,
                "link": "https://www.irs.gov/pub/irs-pdf/fw4.pdf",
                "revision_date": "2020-01-01"
            },
            "submitted_at": null,
            “document”: null,
        }
    ]
}

You can use submitted_at to determine whether or not a form is completed. With the relevant form IDs in hand, you can determine which parameters are necessary to submit by querying:

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

Example (abbreviated) response body:

{
    "id": "<FORM_ID>",
    "description": "Federal W-4",
    "link": "https://www.irs.gov/pub/irs-pdf/fw4.pdf",
    "revision_date": "2020-01-01",
    "parameters": [
        {
            "name": "exempt",
            "label": "Do you wish to claim exemption from withholding?",
            "description": "...",
            "type": "select",
            "options": [
                {
                    "label": "No",
                    "value": "no"
                },
                {
                    "label": "Yes",
                    "value": "yes"
                }
            ],
            "required": true,
            "depends_on": null
        },
        ...
    ]
}

With the above parameters in hand, you can then create a submission for the employee like so:

curl -X POST \
https://sandbox.checkhq.com/employees/<EMPLOYEE_ID>/forms/<FORM_ID>/submit \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <API_KEY>' \
  -d '{
    “parameters”: [
        {“name”: “exempt”, “value”: “no”},
        {“name”: “filing_status”, “value”: “M”},
        ...
    ]
  }'

Example response body:

{
    “submitted_at”: “2020-07-29 21:56:45.06366”,
    “parameters”: [
        {“name”: “exempt”, “value”: “no”},
        {“name”: “filing_status”, “value”: “M”},
        ...
    ]
}

Once every form in an employee’s form list has a recorded submission the employee’s withholding forms are considered completely configured.

Determine Employee onboard status

📘Workplaces and onboard status

1. Configure Employee payment preferences

2. Provide Employee SSN

3. Capture Employee withholdings

📘
Workplaces and onboard status