Contact Zeal or request a demo to create a Zeal Partner Account.

Start off account configuration by:

1. Confirming which domain you want the components to be hosted on (i.e. payroll.[your-domain].com). Contact Zeal to set this up in your DNS.

2. Setting your base URL (link that companies and employees should be redirected to after onboarding or logout).

3. Uploading your favicon and logo.

4. Zeal will create a test company account under your Partner account so you can start testing the Zeal Payroll API integration for a company. You will be able to access the company account from your Super Admin dashboard.

You will find your partnerID and two different API Keys in the API page of your Partner Account. Let's start off by using the Test Key for now. Learn more about how to use your API Keys here.

In this guide, we'll be going through the following steps

1. Create Company
2. Onboard Company
3. Create Employee
4. Onboard Employee
5. Create an Employee Check

Create Company

The first thing we will do is Create a Company (also referred to as Employer) within Zeal. We will do so by using the Zeal Create Company API endpoint

📘

Company Creation API

Send basic information needed to create a Company

curl --request POST \
     --url https://api.joinpuzzl.com/companies \
     --header 'Accept: application/json' \
     --header 'Authorization: Bearer 37913ljj' \
     --header 'Content-Type: application/json' \
     --data '
{
     "partnerID": "ab8734eacdcd7692a",
     "first_name": "Richard",
     "last_name": "Hendricks",
     "email": "[email protected]",
     "business_name": "Pied Piper",
     "business_ein": "073647583",
     "business_address": "1 Market St.",
     "business_city": "San Francisco",
     "business_state": "CA",
     "business_zip": "94110",
     "business_phone": "3322232341",
     "use_bank_verification": true
}
'

Onboard Company

Zeal represents employers that you want to run payroll for as "Companies". A company must first be onboarded before you can run payroll for them. The Company Onboarding Flow is fully white-labeled and hosted on your own domain. Use one of the following methods to access a company onboarding link (this link is specific to you):

📘

Company Onboard Flow

Zeal collects basic business information and necessary paperwork.

Super Admin Dashboard
Navigate to the Home page of your Super Admin Dashboard and copy the onboarding link. Set Bank Verification to Yes.

2. Zeal API: Get Company Onboarding Link
   Zeal returns the company onboarding link.

curl --location --requests GET 'https://api.joinpuzzl.com/companies/onboard?partnerID=<PARTNER_ID>'
  --header 'Authorization: Bearer <YOUR API KEY>'

Open the link in a new tab, and fill in the information on each step to complete Company Onboarding.

👍

Webhook

Zeal sends you a webhook with this company’s information (including companyID) after the company onboarding flow is completed successfully.

Create Work Location

Before creating your first employee, you must create a work location that will be assigned to the employee during creation or can be updated to apply to existing employees. A Work Location is the location which the employee will be taxed for

To create a work location, you can either use Zeal's super-admin dashboard or Zeal's API.

Super-Admin Dashboard:

Navigate to the employer dashboard for the company you would like to create employees for, on the left-hand menu navigate to the work locations tab. Within this dashboard you can easily create a work location using the top-right button

This will prompt you to create a new location by entering a taxable address using a form. You'll also be able to assign a name as well as an ID for internal use to your work location as well.

Zeal's API

Before creating a work location via API, a taxable location must be resolved using the Resolve Taxable Location request. In this request you will enter the employee to created's work address and in turn you will receive a corresponding taxableLocationID

This is an example of a request response with a taxableLocationID:

{
  "success": true,
  "data": {
    "taxableLocationID": "609ffdf81a5f9c4c10b0c443",
    "street1": "1 Ferry Building",
    "street2": "",
    "city": "San Francisco",
    "state": "CA",
    "zip": "94111",
    "is_suitable_for_taxation": true,
    "is_po_box": false,
    "is_state_mismatch": false,
    "is_armed_forces_address": false,
    "is_foreign_address": false,
    "is_deliverable": true
  }
}

After receiving your taxableLocationID, you'd then utilize it as a body parameter to create a Work Location using the following Create Work Location request. Using your taxableLocationID, companyID, and the optional name as well as work_site_id params you will receive a response such as this example:

{
  "success": true,
  "data": {
    "companyID": "1234567890",
    "workLocationID": "573hfjd39854fh32",
    "taxableLocationID": "609ffdf81a5f9c4c10b0c443",
    "name": "SF Office",
    "work_site_id": "SF"
  }
}

From the request's response you'll be able to isolate the workLocationID which will be used in the following step to create your first employee(s)

Create Employee

Super-Admin Dashboard

To add an employee via the dashboard you can start by navigating to the People tab with the following flow
Super Admin Dashboard > Click into Company > People tab

Here, you can click the Add New Employee button and you'll be presented with a form to fill with the employee's information. You will then have the choice of copying the employee's onboarding link or having it sent directly to their respective email.

Zeal's API
You can use Zeal's API to create employees using the Create Employee request. You will need to use the previously resolved workLocationID as a parameter. The following is an example of a create employee request:

curl --request POST \
     --url https://api.joinpuzzl.com/employees \
     --header 'Accept: application/json' \
     --header 'Authorization: Bearer null' \
     --header 'Content-Type: application/json' \
     --data '
{
     "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": "Erlich",
               "last_name": "Bachman",
               "title": "Brand Ambassador",
               "default_pay_schedule": "daily",
               "default_wage": 100,
               "workLocationID": "531fece70b6d0b5d29c9f352",
               "start_date": "2022-05-10",
               "dob": "1998-12-05",
               "ssn": "222-22-2222",
               "phone_number": "9243057932",
               "address": "1 Ferry Building",
               "city": "San Francisco",
               "state": "CA",
               "zip": "94105"
          }
     ],
     "companyID": "1b5n28nrideucd24"
}

Onboard Employee

Now that you’ve created your employee(s), you can now onboard them!

Super-Admin Dashboard

Access the employee onboarding link through the dashboard, in the People Tab. Here you can copy the onboarding link directly to the your clipboard

Zeal's API
You can utilize the following endpoints to either get an onboarding link or send an onboarding link to the employee's email address. Use the Employee Onboarding Link request to receive the employee onboarding link as a response:

curl --request POST \
     --url https://api.joinpuzzl.com/employees/onboard \
     --header 'Accept: application/json' \
     --header 'Authorization: Bearer 37913ljj' \
     --header 'Content-Type: application/json' \
     --data '
{
     "profile": false,
     "employee_acct": false,
     "i9_form": false,
     "id_scan": false
}
'

Use the Send Employee Onboarding Link request to send an employee onboarding link to the employee address:

{
     "employees": [
          {
               "profile": false,
               "employee_acct": false,
               "i9_form": false,
               "employeeID": "624b2874ecd1720025415fc1"
          }
     ],
     "companyID": "24c5b29f07924840b119c34c1358940c"
}

Create Check

The final step is to create an actual check for the employee. This can also be done, both with the white label and the API.

Super-Admin Dashboard

Super Admin Dashboard > Select a Company > Pay > Pending tab

Zeal's API
Use the Create Employee Check request to create an employee check via the API:

curl --request POST \
     --url https://api.joinpuzzl.com/employeeCheck \
     --header 'Accept: application/json' \
     --header 'Authorization: Bearer 92e4043469d84c488cce8a050361cff2' \
     --header 'Content-Type: application/json' \
     --data '
{
     "companyID": "1b5n28nrideucd24",
     "employeeID": "1234567890",
     "reportingPeriodID": "974675839",
     "check_date": "2022-03-21",
     "approval_required": false,
     "disbursement": {
          "method": "direct_deposit"
     },
     "shifts": [
          {
               "time": "string",
               "hourly": {
                    "hours": 3,
                    "wage": 56.3
               }
          }
     ]
}
'

For additional flow such as Contractor Onboarding or Running Payroll please follow our other comprehensive guides. Feel free to reach out to our team with any questions related to support or integration.