Just looking to build an integration for your own company's data?
If you aren't looking to build an integration listed in our Zenefits App Directory that other companies can use, you can get started quickly with a Custom Integration instead.
Looking to integrate an app with Zenefits? You're in the right place!
At a high level, the Zenefits Integration Platform lets you:
- Pull Access company and employee information for 20,000+ companies on the Zenefits platform through a REST API.
- Push Subscribe and respond to changes in information, such as new hires, new terminations, promotions, manager changes, etc.
- Present Ask companies and employees for custom information within the Zenefits UI during key lifecycle events (hiring, promotions, terminations, etc) by presenting templatized user interface units called modules.
How do you sign up?
We hope this reference will give you an idea what kinds of applications you can integrate into the Zenefits platform. Reach out to us at [email protected] if you'd like to create a developer account in order to develop your app and be listed in the Zenefits App Directory!
Overview
There are four main steps to creating a Zenefits integration:
- Rest API: Decide what pieces of data and which events in Zenefits you care about.
- Collecting Custom Data: Define how your integration will collect any additional data you need in the Zenefits UI.
- Events & Webhooks: Setup webhooks and validation endpoints to respond to Zenefits events.
- Authorization: Configure what permissions your integration needs and implement OAuth authentication for it.
1. REST API
The Zenefits API is primarily read-only, supporting the GET method on all URLs. You can try the API by typing the following in your Unix-based shell, where the bearer token is retrieved after a company registers for your service.
API Endpoint Example:
curl -i https://api.zenefits.com/core/people -H "Authorization: Bearer [[app:key]]"
The API is divided into logical namespaces. The Platform API allows you to access information about your applications and the companies, employees, and lifecycle events relating to it. The Core API allows to access Zenefits HR specific data.
2. Modules
Zenefits lets you know about changes during key lifecycle events of employees or companies. You can also add modules that let you ask for more information directly in the Zenefits UI. In such cases, the payload of the corresponding events will have the information you requested, so that you can handle any downstream effects on your end.
Sample scenarios include:
- Creating an account in your service when someone is hired
- Updating that account once an offer letter is signed
- Updating that account when an employee is promoted, changes departments, changes locations, etc.
- Deleting someone's account when they are terminated
For example, an expense management app could add the following module and configure it to show up during hiring:
For more information, see Module UI
3. Webhooks
The webhook URLs that you have configured as part of setting up your integration will be called when the events that you care about occur in Zenefits. All webhooks from Zenefits will be POST calls with a JSON payload in the body that has the pertinent information.
For more information, see Events and Webhooks.
4. Authentication: Sync with Zenefits button
Once you have decided what permissions your integration needs and what its interaction with Zenefits will be, you need to add a "Sync with Zenefits" button on your website. It will call the OAuth URL embedded in the button to kick off the OAuth flow with Zenefits. See Authentication & Authorization to learn more about OAuth and the Sync with Zenefits Button.
5. Start helping folks run their business!
Once these components are implemented, your integration can be included in the Zenefits app directory page, giving you access to more than 10,000 businesses. We can't wait for HR admins to get the shared value of our integrated platform!