A Guide to Integrating with Zenefits APIs

Zenefits API Directory

TriNet Zenefits is a leading provider of full service HR solutions. It enables small and medium sized companies to administer and manage benefits, HR offerings, including time tracking, onboarding, employee engagement, employee record keeping; payroll; performance and well-being. As a highly sought after HRIS platform, companies have been increasingly integrating with TriNet Zenefits to facilitate seamless exchange of HRIS data, captured by Zenefits, with their own apps to drive diverse use cases. 

Zenefits API Authentication, Filtering, Rate Limits

Owing to the sensitive nature of information held by the HRIS application, including personal identifiable information (PII), Zenefits API ensures that all data scopes are accessed at a granular level. The Zenefits API uses OAuth2 to authenticate and authorize access to information stored in the application. OAuth2 authorizes third party applications to request private details from Zenefits accounts, without passwords. It is limited only to admins and developers receive unique Client ID and Client Secret to access data with integration. 

‍

Zenefits API pagination helps developers define the records needed per page. The developers can use the limit parameter to specify the number of records in a response. The maximum limit can be 100, however, in case the limit is not defined, the default limit is 20. In case the total number of records do not fit into a single page, the next_url field will have a link to the next page with the remaining records. In case the next_url field displays null, then no records exist for subsequent pages. Developers can also use the starting_after or ending_before query parameter to specify pagination based on object ids. The ending_before query parameter is useful for backwards pagination. 

Zenefits API Objects, Data Models & Endpoints

It is extremely important for developers to understand the objects, data models and endpoints when it comes to integrating with Zenefits API. While the overall scope might be large, here are a few which can be considered as a starting point for Zenefits API integration. 

‍

• Applications: Used to return information about the application

GET https://api.zenefits.com/platform/applications

‍

• Companies: Used to get information about the company

GET https://api.zenefits.com/core/companies

Fields include: ‘legal_name', 'ein','departments', 'locations'

‍

• People: Used to return information about a company’s employees

GET https://api.zenefits.com/core/companies/{:company_id}/people

GET http://api.zenefits.com/core/people/{:id} (For information about a single employee)

GET http://api.zenefits.com/core/people (For information for all employees across the company)

Fields include: 'work_email', 'date_of_birth', 'manager', 'department', 'location', 'work_phone', 'status', 'subordinates', 'banks','company', 'employments', 'department', 'location', 'manager', 'banks'

‍

• Employments: Used to return information about an employee’s employment history

GET https://api.zenefits.com/core/people/{:person_id}/employments

GET https://api.zenefits.com/core/employments/{:employment_id} (For information on a specific employment

GET https://api.zenefits.com/core/employments (For information on all employments across all people)

Fields include: 'termination_type', 'employment_type', 'comp_type', 'annual_salary', 'pay_rate', 'working_hours_per_week','person'

‍

• Employee Bank Accounts: Used to return information about employee’s bank account

GET https://api.zenefits.com/core/people/{:person_id}/banks

GET http://api.zenefits.com/core/banks/{:bank_id} (For information for a specific bank)

GET http://api.zenefits.com/core/banks (For information for all banks across all people)

‍

• Departments: Used to return the list of a company’s department

GET https://api.zenefits.com/core/companies/{:id}/departments

GET http://api.zenefits.com/core/departments/{:department_id} (For information regarding a single department:

GET http://api.zenefits.com/core/departments (For information relating to all departments across all companies)

‍

• Locations: Used to return the list of a company’s location

GET https://api.zenefits.com/core/companies/{:company_id}/locations

GET http://api.zenefits.com/core/locations/{:location_id} (For information relating to a single location)

GET http://api.zenefits.com/core/locations (For information relating to all locations across all companies)

‍

• Vacation Requests: Used to return information about employees' PTO vacation requests

GET https://api.zenefits.com/time_off/vacation_requests

GET http://api.zenefits.com/time_off/vacation_requests/{:id} (For information relating to a single vacation request)

GET http://api.zenefits.com/time_off/vacation_types/{:vacation_type_id}/vacation_requests/ (For all vacation requests for a single vacation type)

Fields include: 

• status: Requested, approved, denied, cancelled, deleted
• vacation_type: Vacation Type for this request, e.g. Jury Duty, Work From Home, Doctor's Appointment
• start_date: Start date of vacation request (inclusive)
• end_date: End date of vacation request (inclusive) 
• creator i.e. Person who filed this vacation request
• person i.e. Person who this vacation request applies to (often the same as creator)
• created_date: Date this vacation request was created
• hours: Number of hours requested, generally calculated at 8 hours a day for multi-day requests and specified manually for single day requests
• approved_date: Date this request was moved from requested status, either to approved or denied.
• reason: Note from the person requesting this vacation
• deny_reason: Note from the approver for why this vacation request was denied. (Only applies if status is denied)

‍

• Vacation Types: Used to return information about a company's PTO vacation types

GET https://api.zenefits.com/time_off/vacation_types 

GET http://api.zenefits.com/time_off/vacation_types/{:id} (For information relating to a single vacation type)

Fields include:

• status: Active, deleted
• vacation_types
• name: Name of the type
• company: Company for this vacation type
• vacation_requests: Vacation Requests for this type
• counts_as: What account this type counts towards (vacation, sick, personal)

‍

• Time Durations: Used to return information about a person's T&A hours

GET https://api.zenefits.com/time_attendance/time_durations

GET http://api.zenefits.com/time_attendance/time_durations/{:id} (For information relating to a single time duration object)

Fields include: 

• person: Person that this time duration is logged for people
• activity: Activity type (work, meal_break)
• state: Effective, overridden, deleted, correction
• valid_status: valid, exceeds, overlapping same day, overlapping previous day, overlapping next day, missing clock out, missing clock in
• hours: Number of hours logged
• start: When this time duration started
• end: When this time duration ended
• is_overnight: Whether this time duration has been marked as part of an overnight shift
• is_approved: When this time duration was approved. 
• approver: Person who approved this time duration

Zenefits API Use Cases

• Automate onboarding, saving 100s of hours as information gets auto synced to Benefits and Payroll
• Simplify employee management with organizational charts, company directories allowing employees to update their own records
• Improve HR processes and decision making with business intelligence reports and insights on turnover, workforce diversity, with understanding of how to pay new hires
• Simplify the process of providing great benefits to employees, from comprehensive healthcare plans to extra perks like commuter benefits
• Facilitate time and attendance management with employee scheduling tools, with time off and clocked-in hours automatically syncing Payroll

Zenefits API FAQs

Here is a list of FAQs about TriNet Zenefits API which can help commence and accelerate your integration:

‍

• What is the software stack of Zenefits? Answer
• How to address the CORS issue in Angular 8 without changing the backend in Zenefits API? Answer 
• How to handle New Company Installations in TriNet Zenefits API? Answer
• How to handle New People's Subscriptions in TriNet Zenefits API? Answer
• What does Webhooks shared secret vs OAuth client secret mean? Answer
• How to read and write custom data with Zenefits API? Answer
• How to issue Access Tokens for Zenefits API authentication and authorization? Answer
• Where can I find a guidebook for Zenefits integration? Answer
• Does Zenefits have a public API? Answer
• What is Zenefits’ App Acceptance Criteria for API integration? Answer
• Where is the developer portal for Zenefits API? Answer

Common Integrations with Zenefits API 

Several businesses are increasingly building integrations with Zenefits API to power operations for the end customers, facilitated by seamless data exchange, including:

‍

• Payroll providers to get access to employee information, employment records and agreement terms, compensation details and other relevant information like leaves, time off, etc. 
• Candidate recruitment companies to push data about selected candidates and relevant information for smooth onboarding
• Employee engagement companies to fetch employee data, including demographic information, personal and professional details, attendance, etc. 
• Early wage access providers to get access to employee information, payroll details and even write back data regarding early payments/ deductions for accurate payroll processing

How to integrate with Zenefits API 

To get started with the Zenefit API integration journey, a developer account needs to be created. To create the same, developers can reach out to Zenefits team by dropping an email on this email address. Reaching out on this email ID will take the developers to the next step to get access to a sandboxed Zenefits test company and credentials to start using the API. Once the Zenefits developer account is active, developers can leverage this getting started guide for a detailed overview on REST API, Modules, Webhooks, Authentication and much more.  It is important to read through and understand the App Acceptance Criteria well. The same can be accessed here. At the same time, knowledge of the Zenefits Developer Policy is critical to understand the technical, brand and general requirements and restrictions. 

Get started with Zenefits API 

Integrating with Zenefits API is beneficial for businesses looking to seamlessly exchange data with this leading HRIS provider with bi-directional sync. However, building a custom 1:1 integration can be a complex, time and resource intensive process. The above mentioned steps, restrictions and requirements can all choke up developer bandwidth. Invariably, SaaS businesses today are moving away from building integrations to partnering with unified APIs like Knit. A unified API, in this case for HRIS integrations, enables companies to integrate once and seamlessly connect with multiple HRIS applications, including Zenefits API, without any additional requirements. With a unified HRIS API, maintenance and management of integration with Zenefits and other applications also becomes quite easy. Book a discovery call today to learn how a unified API can help you ship and scale integrations fast. 

‍