Regular Payroll Run through API

This guide will explain how to take advantage of Zeal's Regular Payroll Run functionality through the API.

In this guide

How to set up a company's payroll settings
How to get the upcoming date of the next regular payroll run according to company payroll settings
Create employee checks with given information

Set up Company Payroll Settings

Call Update Company Information with the payroll_firstCheckDate, payroll_schedule, and payroll_firstPayPeriodID. This will return with the company object.

curl --request PATCH \
     --url https://api.zeal.com/companies \
     --header 'Authorization: Bearer {{testApiKey}}' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
      {
          "companyID": "{{companyID}}",
          "payroll_firstCheckDate": "2024-08-30",
          "payroll_schedule": "weekly",
          "payroll_firstPayPeriodID": "6580ce4a3808d60023b4e412"
      }
'

This will return JSON with the updated Company Object.

{
    "status": 200,
    "success": true,
    "data": {
        "companyID": "{{companyID}}",
        "first_name": "Richard",
        "last_name": "Hendricks",
        "email": "[email protected]",
        "business_name": "Pied Piper",
        "business_address": "1 Market St.",
        "business_city": "San Francisco",
        "business_state": "CA",
        "business_zip": "94110",
        "business_phone": "2025550151",
        "mail_address": "1 Market St.",
        "mail_city": "San Francisco",
        "mail_state": "CA",
        "mail_zip": "94110",
        "ssn": "22-333-4444",
        "ownership_percentage": 25,
        "dob": "01/01/1990",
        "legal_structure": "ccorp",
        "job_title": "CEO",
        "address": "1 Ferry Building",
        "city": "San francisco",
        "state": "CA",
        "zip": "94105",
        "payroll_firstCheckDate": "2024-08-30",
        "payroll_schedule": "weekly",
        "payroll_firstPayPeriodID": "6580ce4a3808d60023b4e412"
  }
}

(Optional) Set up Employee with Regular payroll settings

This is optional because these settings are used in the Zeal UI when generating payroll runs. If you use the API to create employee checks, you do not need these fields.

Set the following fields on an Employee:

Set is_salary = true
Set salary field on the Employee
- Reminder: the salary field is required IF is_salary=true

You can set is_regular = true if you’d like this worker to show up automatically in your on-cycle payroll runs in the Zeal UI as well.

Get upcoming Regular Payroll Run date

At any time, you can call the “Get Upcoming Regular Payroll” endpoint to get the upcoming “regularly” scheduled check date and associated reporting period information.

curl --request GET \
     --url https://api.zeal.com/payroll/regular?companyID={{companyID}} \
     --header 'Accept: application/json' \
     --header 'Authorization: Bearer {{testApiKey}}' \
     --header 'Content-Type: application/json'

This will return Reporting Period and Check Date information.

{
    "status": 200,
    "success": true,
    "data": {
      "reportingPeriodID": "6580ce4a3808d60023b4e412",
      "start": "2024-08-24",
      "end": "2024-08-30",
      "checkDate": "2024-08-30"
    },
}

Create Employee Checks

You can now call the Create Employee Check endpoint, with the check date and reporting period information from the previous endpoint (see here for more details on how to create an Employee Check). Include a flat earning component with the appropriate hours and amount.

curl --request POST \
     --url https://api.zeal.com/employeeCheck \
     --header 'Accept: application/json' \
     --header 'Authorization: Bearer {{testApiKey}}' \
     --header 'Content-Type: application/json' \
     --data '
{
     "approval_required": false,
     "disbursement": {
          "method": "direct_deposit"
     },
     "shifts": [
          {
               "flat": {
                    "hours": 80,
                    "amount": 2500
               },
               "time": "2023-02-24T15:00"
          }
     ],
     "companyID": "{{companyID}}",
     "employeeID": "{{employeeID}}",
     "reportingPeriodID": "{{reportingPeriodID}}",
     "check_date": "2024-08-30"
}
'

With the check in our system, it will automatically be batched and begin processing 2 days before the check_date.

Note

If you create employee checks for “is_regular” employees through the API, you will not necessarily see payroll runs in the UI.