Running Payroll

Learn how to run payroll with Zeal

The three most important concepts to running payroll successfully at Zeal are Shifts, Employee Checks and Employer Checks. A Shift is smaller building block of an Employee Check that consists of one to a few earning components (hourly wage, bonus, PTO etc.) An Employee Check represents when and how to pay a W2 employee. As with the vast majority of components in Zeal, Employee Checks can be created, updated, and/or deleted on the dashboard and/or API. The other important concept to understand for running payroll is the Employer Check. Employer Checks are aggregated Employee Checks with the same check date.


What is in a Shift?


A Shift embodies completed work by the employee and consists of multiple earning components that describe the type of work performed. Zeal uses the Shifts of an Employee Check to calculate the check's gross pay.

The major parts of the shift include:

  1. shiftID: The unique identifier for this shift
  2. status: The status of the shift
  3. employeeCheckID: The ID of the employee check that this shift is associated with

Every Shift also requires at least 1 earning component. Zeal supports all types of earning components from hourly and overtime to PTO and commodity. See how Zeal models a Shift and it's earning components in the API in the Shift Object doc.

Reach out to Zeal if you'd like help in mapping your existing earning components to Zeal's current offering.


What is in an Employee Check?


See how Zeal models an Employee Check in the API here.

The major parts of the check include:

  1. employeeCheckID: The unique identifier for this check.
  2. status: The status of the check (pending, pre-processed, processed).
  3. employeeID: The ID of the employee that this check is for.
  4. reportingPeriodID: Zeal's Reporting Period ID. A Reporting Period, also known as pay period, describes the span of time that the work was completed (or the dates the check payment is covering). Query Zeal's system for the correct Reporting Period ID to attach to the employee check. Learn more here.
  5. check_date: The date that the employee should receive this check. By default, if you give an invalid check date (check date falls on a weekend or holiday) Zeal will automatically roll forward the check date to the next feasible date. Read more in the API Reference.
  6. approval_required: By default set to false, this field dictates whether manual approval is required for this check or not. Zeal typically automatically processes the check the day before the check date. However, IF approval is required and the check is not approved by time of processing, Zeal will NOT process the check.
  7. disbursement: This field dictates the method of payment for this check. Zeal currently offers two disbursement methods: direct deposit and download check.
  8. gross_pay: Total pay before taxes and deductions are withheld.
  9. net_pay: Total pay after taxes and deductions are withheld (this field only applies for processed checks).
  10. taxes: List all employee and employer taxes (this field only applies for processed checks).
  11. total_employer_taxes: Sum of all taxes owed by the employer (this field only applies for processed checks).
  12. total_employee_taxes: Sum of all taxes withheld from the gross pay for the employee (this field only applies for processed checks).
  13. shifts: List of all shifts. See below for more information about a shift.

What is in an Employer Check?


Two days before a check date, all Employee Checks created by an employer with the same check date will get grouped into an Employer Check automatically. Employer Checks can be viewed in the History section of the white-label and by calling the GET /employerCheck or /employerChecks endpoints. See how Zeal models an Employer Check in the API here.

The major parts of the Employer Check include:

  1. employerCheckID: The unique identifier for this check.
  2. companyID: ID of company who this employer check is being processed for.
  3. status: The status of the check (pending, pre-processed, processed).
  4. reporting_periods: A list of reporting periods contained within this check. Remember, an Employer Check is made up of many employee checks with the same check date, but this does not necessarily mean they have the same reporting period.
  5. totals: This is an array of the different attributes of the Employer Check. See more about the totals object here.
  6. employee_checks: A list of all the Employee Checks included in the object.

Create an Employee Check


  1. Super Admin Dashboard
  1. Create Employee Check
curl --location --requests POST 'https://api.joinpuzzl.com/employeeCheck'
 --header 'Content-Type: application/json'
 --header 'Authorization: Bearer <YOUR API KEY>'
 --data-raw '{
   "companyID": "1b5n28nrideucd24",
   "employeeID": "3f8a4ae74047215b5b218463",
   "reportingPeriodID": "5f8f4ae71044215a6b608464",
   "check_date": "2020-01-07",
   "shifts": [
      {
         "time": "2020-04-15T14:00:00Z",
         "hourly": {
               "hours": 8,
               "wage": 25
         },
         "overtime": {
               "hours": 2
         },
         "reimbursement": {
               "amount": 8
         }
      }
   ]
}'

See Employee Checks


You can monitor employee checks through the dashboard and API

  1. Super Admin Dashboard
  1. Retrieve Employee Checks by Employee
curl --location --requests GET 'https://api.joinpuzzl.com/employeeCheck?companyID={companyID}&employeeID={employeeID}'
 --header 'Authorization: Bearer <YOUR API KEY>'

See Employer Checks


You can monitor employee checks through the dashboard and API.

  1. History tab of the Employer dashboard

2. Retrieve Employer Check by ID

curl --request GET \
     --url https://api.joinpuzzl.com/employerCheck \
     --header 'Accept: application/json' \
     --header 'Authorization: Bearer 123456789'

Did this page help you?