Employee Onboarding

❗️

Prerequisite

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.

  1. Work Location
  2. Create an Employee
  3. Set Tax Parameters
  4. Add a Bank Account
  5. Update Onboarded Status


API

Work Location

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

🚧

Code Samples

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 Employee

  1. 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}}"
}
'
  1. Store the employeeID or IDs from the employee objects returned.

Set Tax Parameters

  1. 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"
     ]
}
'
  1. 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.
#
##############
# Response Example:
{
  "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"
          }
        ]
      },
# ...
}
  1. 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"
          }
     ]
}
'

Bank Account

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 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}}"
}
'

Congratulations
You've onboarded your first employee!



White-Label

  1. Navigate to your Super Admin Dashboard and ensure that Test Mode is enabled.
  2. Click on a Company to access the Employer Dashboard as a Super Admin.
28672867

Work Location

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

28722872

Create an Employee

  1. Next, navigate to the People page and click Add New Employee.
28742874
  1. Fill the employee information and select the proper Work Location from the dropdown, then click Add Employee.
28722872

Complete the Onboarding Flow

  1. Back on the People page, find the Employee and click the arrow icon to email the onboarding link directly to the employee or click the copy icon to copy it to your clipboard.
28722872

📘

Get Employee Onboarding Link

The link can also be accessed programmatically by calling Get Employee Onboarding Link.

  1. When the employee navigates to the page, they see the white-label component on your domain with your logo.
22442244
  1. The employee completes the onboarding flow and they receive a congratulations message.

👍

Employee Onboarding Event

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.

Congratulations
You've onboarded your first employee!


What’s Next

Now that we've onboarded our first employee, the next step is to pay them.

Did this page help you?