Zeal University

Employee Onboarding

Suggest Edits

💬

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.

  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.

🔔

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 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.
//

{
  "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 Partner Dashboard and ensure that Test Mode is enabled.
  2. Click on a Company to access the Employer Dashboard as an Admin.

Zeal Partner Dashboard in Test Mode

Work Location

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

Create an Employee

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

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

Complete the Onboarding Flow

  1. 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.

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

Employee Onboarding

  1. The employee completes the onboarding flow and they receive a congratulations message.

📝

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.

Congratulations
You've onboarded your first employee!

Updated about 1 month ago

What’s Next

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