Introduction

Welcome to the Zeal Payroll API Documentation!

Zeal Payroll API enables you to onboard employees, run payroll for hourly workers, and retrieve the payroll results. By connecting with Puzzl Group Inc.'s whitelabel payroll, you can seamlessly pay workers faster while owning the experience end-to-end.

Refer to this documentation for API endpoints, example request bodies, example responses, and error codes. You can find general information and support in our API Documentation. Please contact [email protected] for any questions or suggestions.


Zeal Postman Collection

Run in PostmanRun in Postman


Authentication and Keys

Zeal authenticates API requests using the employer accountโ€™s CompanyID and the employer or partner account's API key. The Zeal CompanyID and secret API key are necessary for authorized consumption of any endpoints. If you do not include your key when making an API request, or use one that is incorrect or outdated, Zeal returns a 401 error.

For employers: The CompanyID and API keys can be found under the 'API' Page on Zeal's dashboard. Your secret API key can be used to make any API call on behalf of your account.

For partners: An employer's Company ID can be found on the Zeal Partner dashboard or in the API Page of the employer's dashboard. Your API keys can be found under the 'API' Page on Zeal's Partner dashboard. Your secret API key can be used to make any API call on behalf of any of your sub-employers' accounts.

Treat your secret API keys as you would any other password. Grant access only to those who need it. Ensure it is kept out of any version control system you may be using.


Using Zeal Credentials

Include the API key in the Authentication as a bearer token.

Example: Authorization: Bearer

Include the companyID in the body or query of the request. You can find examples of usage in the endpoints specified below.


Test and Production Modes

Zeal features Production and Test modes to help with the integration process. The test and production modes function almost identically, with a few necessary differences:
In test mode, payroll is NOT run and NO money is moved. Test employer checks and employee checks contain simulated tax information based on the given gross pay.
In test mode, the number of test employees and amount of wages will not have any effect on the Zeal fees incurred.
In production mode, the number of employees and amount of wages paid out WILL incur charges from Zeal.

You can view test data by toggling the Zeal Dashboard's Test Mode button.


Test and Production API Keys

You can find Test and Production API Keys on your Zeal dashboard on the 'API' page.
API calls to the below endpoints using the Test key will result in responses reflecting Test data or changes to the Test data (test employees, test employer checks, test employee checks).
API calls to the below endpoints using the production key will result in responses reflecting Production data or changes to the Production data โ€” payrolls will be run and money will be disbursed.