Employee Onboarding

💬
Note
Before you onboard an employee, you should define where they will be working. Follow the Work Locations Guide to do so.

Onboarding W-2 Employees is an important step for any payroll offering. There are a lot of factors that determine an employee’s taxable status which is necessary to pay them correctly. As such, there are a few steps involved with onboarding an employee.

In this guide

How to get an employee's Work Location
How to create an Employee
How to set employee tax parameters
How to add an employee's Bank Account
How to update an employee's onboarded status
How to onboard an employee using the white-label components

API

Get the employee's Work Location

Call Get Work Locations and find the Work Location for this employee. Store the workLocationID.

🔔
Note
Remember to replace the placeholders such as {{testApiKey}} in the code samples below.

curl --request GET \
     --url https://api.zeal.com/workLocations \
     --header 'Accept: application/json' \
     --header 'Authorization: Bearer {{testApiKey}}'

Create an Employee

Call Create Employee with the employee data along with the companyID and workLocationID.

curl --request POST \
     --url https://api.zeal.com/employees \
     --header 'Accept: application/json' \
     --header 'Authorization: Bearer {{testApiKey}}' \
     --header 'Content-Type: application/json' \
     --data-raw '
{
     "new_employees": [
          {
               "overtime_rate": 1.5,
               "double_time_rate": 2,
               "autopilot": {
                    "autopilot_on": false
               },
               "is_943": false,
               "is_scheduleH": false,
               "email": "[email protected]",
               "first_name": "Richard",
               "last_name": "Hendricks",
               "title": "CEO",
               "default_pay_schedule": "semimonthly",
               "default_wage": 50,
               "workLocationID": "{{workLocationID}}",
               "start_date": "2022-01-01",
               "dob": "1985-05-25",
               "ssn": "123456789",
               "phone_number": "1234567890",
               "address": "1 Market St.",
               "city": "San Francisco",
               "state": "CA",
               "zip": "94110"
          }
     ],
     "companyID": "{{companyID}}"
}
'

Store the employeeID or IDs from the employee objects returned.

Set employee tax parameters

Call Get Employee Tax Parameter Definitions to get a codified version of the tax forms an employee needs to fill base on their taxable status (i.e. jurisdictions).

curl --request POST \
     --url https://api.zeal.com/employees/getTaxParameterDefinitions \
     --header 'Accept: application/json' \
     --header 'Authorization: Bearer {{testApiKey}}' \
     --header 'Content-Type: application/json' \
     --data '
{
     "jurisdictions": [
          "US",
          "CA"
     ]
}
'

Use the Tax Parameter Definitions Object returned to dynamically create the form fields that the employee will need to fill.

//
// For Example:
// Use the code below to generate a form field with the label 'Filing Status'.
// The options of the field should be: 
// 'Single or Married filing separately',
// 'Married filing jointly,
// 'Head of Household'
// When the form is submitted, the field values should be tranlated to:
//	 'S',
//   'M',
//	 'H'
// These values will be submitted under the code 'FILINGSTATUS' to the 'Set Employee Tax Parameters'
// endpoint as shown in the next step.
//

{
  "success": true,
  "data": {
    "US": [
      {
        "code": "FILINGSTATUS",
        "label": "Filing Status",
        "effectiveDate": "2020-01-01T00:00:00.000Z",
        "type": "options",
        "options": [
          {
            "code": "S",
            "name": "Single or Married filing separately",
            "effectiveDate": 2020
          },
          {
            "code": "M",
            "name": "Married filing jointly",
            "effectiveDate": 2020
          },
          {
            "code": "H",
            "name": "Head of Household",
            "effectiveDate": 2020
          }
        ],
        "defaults": [
          {
            "effectiveDate": 2020,
            "code": "S"
          }
        ]
      },
// ...
}

Call Set Employee Tax Parameters to submit the data gathered from the employee.

curl --request POST \
     --url https://api.zeal.com/employees/setTaxParameters \
     --header 'Accept: application/json' \
     --header 'Authorization: Bearer {{testApiKey}}' \
     --header 'Content-Type: application/json' \
     --data '
{
     "employeeID": "{{employeeID}}",
     "companyID": "{{companyID}}",
     "federalParameters": [
          {
               "code": "FILINGSTATUS",
               "jurisdiction": "US",
               "value": "H"
          }
     ],
     "stateParameters": [
          {
               "code": "FILINGSTATUS",
               "jurisdiction": "CA",
               "value": "H"
          },
          {
               "code": "REGULAR_ALLOWANCES",
               "jurisdiction": "CA",
               "value": "1"
          },
          {
               "code": "SUTA_CA_EXEMPT",
               "jurisdiction": "CA",
               "value": "NO_REPORTING"
          }
     ]
}
'

Add a Bank Account (optional)

📝
Note
This step is optional. If an employee is onboarded without bank account details they will still be able to receive employee checks by any disbursement method other than direct_deposit.

To add a bank account for the employee call Create Bank Account to create the employee bank account.

curl --request POST \
     --url https://api.zeal.com/bankaccount \
     --header 'Accept: application/json' \
     --header 'Authorization: Bearer {{testApiKey}}' \
     --header 'Content-Type: application/json' \
     --data '
{
     "companyID": "{companyID}",
     "id": "{{employeeID}}",
     "institution_name": "Chase",
     "account_number": "123456789",
     "routing_number": "267084131",
     "type": "checking"
}
'

Update an employee's onboarded status

Call Set Onboarded Status to True to mark the employee status as onboarded.

curl --request POST \
     --url https://api.zeal.com/employees/setOnboardedStatusToTrue \
     --header 'Accept: application/json' \
     --header 'Authorization: Bearer {{testApiKey}}' \
     --header 'Content-Type: application/json' \
     --data '
{
     "employeeID": "{{employeeID}}",
     "companyID": "{{companyID}}"
}
'

Now that the employee's status is updated, they are considered onboarded.

White-Label

Access the Employer Dashboard

Navigate to your Partner Dashboard and ensure that Test Mode is enabled. Then, click on a Company to access the Employer Dashboard as an Admin.

Zeal Partner Dashboard in Test Mode

View a Work Location

Navigate to the Work Location page and ensure you have the location that the employee will be working at.

Create an Employee

Next, navigate to the People page and click Add New Employee.

Fill the employee information and select the proper Work Location from the dropdown, then click Add Employee.

Complete the onboarding flow

Back on the People page, find the Employee and click Copy onboarding link then Send link to employee's email.

Copy Onboarding Link

🪄
Tip
The link can also be accessed programmatically by calling Generate Employee Onboarding Link.

When the employee navigates to the page, they see the white-label component on your domain with your logo.

The employee completes the onboarding flow and they receive a congratulations message showing that they've been onboarded.

📝
Note
When the Employee Onboarding flow is completed successfully through the white-label, Zeal sends the Employee information to the webhook URL you've set for the Employee Onboarding Event.

Recap

To onboard an employee, personal information, work location, and tax parameters need to be submitted.
Bank account details don't need to be submitted, but the employee can't be paid by direct deposit without them.
Employers can create Work Locations and Employees from the Employer Dashboard
Employees can complete onboarding through the Employee Onboarding component