Quickstart Guide
Use Zeal's pre-built, white labeled components as well as our embedded API to hit the ground running with a comprehensive payroll product.
Contact Zeal or request a demo to create a Zeal Partner Account.
Start off account configuration by:
-
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.
-
Setting your base URL (link that companies and employees should be redirected to after onboarding or logout).
-
Uploading your favicon and logo.
-
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
- Create Company
- Onboard Company
- Create Employee
- Onboard Employee
- 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.


- 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.
Updated 13 days ago