Zoho People API Guide

Zoho People API overview

Zoho People is a leading HR solution provider which enables companies to automate and simplify their HR operations. Right from streamlining core HR processes, to supporting time and attendance management, to facilitating better performance management and fostering greater learning and development, Zoho People has been transforming HR operations for 4500+ companies for over a decade. 

With Zoho People API, companies can seamlessly extract and access employee data, update it and integrate this application with other third party applications like ATS, LMS, employee onboarding tools, etc. to facilitate easy exchange of information. 

This guide covers what the Zoho People API offers, how it authenticates, the endpoints and data models you will work with, common pitfalls, example use cases and answers to frequently asked questions.

Key highlights of Zoho People APIs

1. Employee data as a system-of-record
   Pull structured employee details and identifiers (like erecno) to keep downstream apps aligned.
2. Workflow automation via triggers + webhooks
   Automate key actions such as onboarding triggers, notifications, and cross-system updates.
3. LMS operations via API-first control
   Manage courses, batches, modules, sessions, enrollments, and learning activity states programmatically.
4. Attendance + leave sync for payroll and workforce ops
   Keep time and leave signals updated across payroll, analytics, and operational dashboards.
5. HR case management integration
   Create and track HR requests with categories, status, SLA indicators, and assignment visibility.
6. Designed for predictable bulk sync patterns
   Pagination and limits (like fetching 200 records at a time) encourage stable integration design.
7. OAuth-based access and scope-driven control
   Token-based authentication supports controlled access and traceable integrations.
8. Enterprise extensibility across modules
   Supports multi-module integration patterns without forcing a one-size-fits-all workflow.

Zoho People API Authentication

Like most industry leading HRIS applications, Zoho People API uses OAuth2.0 protocol for authentication. The application leverages Authorization Code Grant Type to obtain the grant token(code), allowing users to share specific data with applications, without sharing user credentials. Zoho People API uses access tokens for secure and temporary access which is used by the applications to make requests to the connected app. 

Using OAuth2.0, Zoho People API users can revoke a customer’s access to the application at any time, prevent disclosure of any credentials, ensure information safeguarding if the client is hacked as access tokens are issued to individual applications, facilitate application of specific scopes to either restrict or provide access to certain data for the client.

How to integrate with Zoho People API

To integrate your preferred applications with Zoho People API, you need valid Zoho People user credentials. In addition you also must have a valid authentication token or OAuth to access Zoho People API. 

Zoho People API Objects, Data Models & Endpoints

Integrating with any HRIS application requires the knowledge and understanding of the objects, data models and endpoints it uses. Here is a list of the key concepts about Zoho People API which SaaS developers must familiarize themselves with before commencing the integration process. 

Forms API

• POST Insert Record API: Inserts a record into a form.
  https://people.zoho.com/people/api/forms/<inputType>/<formLinkName>/insertRecord?inputData=<inputData>
• POST Insert Record API for Adding Employees: Adds a new employee record.
  https://people.zoho.com/people/api/forms/json/employee/insertRecord?inputData=<inputData>
• POST Update Record API: Updates an existing form record by its record ID.
  https://people.zoho.com/people/api/forms/<inputType>/<formLinkName>/updateRecord?inputData=<inputData>&recordId=<recordId>
• GET Get Bulk Records API: Fetches a form’s records in bulk, from a starting index up to a maximum count.
  https://people.zoho.com/people/api/forms/<formLinkName>/getRecords?sIndex=<record starting index>&limit=<maximum record to fetch>
• POST Add Department API: Adds a department.
  https://people.zoho.com/people/api/department/records?xmlData=<xmlData>
• GET Fetch Forms API: Lists the forms available in the account.
  https://people.zoho.com/people/api/forms?
• GET Fetch Single Record API: Fetches a single form record by its record ID.
  https://people.zoho.com/people/api/forms/<formLinkName>/getDataByID?recordId=261091000000049003
• GET Fetch Single Record API (Section Wise): Fetches a single record by its record ID, grouped by section.
  https://people.zoho.com/people/api/forms/<formLinkName>/getRecordByID?recordId=<recordId>
• GET Get Related Records API: Fetches the records related to a parent record through a lookup field.
  https://people.zoho.com/people/api/forms/<formLinkName>/getRelatedRecords?sIndex=<sIndex>&limit=<limit>& parentModule=<parentModule>&id=<id>&lookupfieldName=<lookupfieldName>
• GET Search Records Based on Record Values: Searches a form’s records by field, operator and text value.
  https://people.zoho.com/people/api/forms/<formLinkName>/getRecords?searchParams={searchField: '<fieldLabelName>', searchOperator: '<operator>', searchText : '<textValue>'}
• GET Get Fields of Form API: Returns the fields of a form.
  https://people.zoho.com/people/api/forms/<formLinkName>/components?

Cases API

• POST Add Case API: Adds an HR case.
  https://people.zoho.com/api/hrcases/addcase?categoryId=<Category ID>&subject=<subject>&description=<description>
• GET View Case API: Returns a single HR case by its record ID.
  https://people.zoho.com/api/hrcases/viewcase?recordId=<Reord ID of the case>
• GET View Case Listing API: Lists the requested HR cases by status.
  https://people.zoho.com/api/hrcases/getRequestedCases?index=<index>&status=<status>
• GET View List of Categories API: Lists the HR case categories.
  https://people.zoho.com/api/hrcases/listCategory?

Timesheet API

• POST Create Timesheets API: Creates a timesheet.
  https://people.zoho.com/people/api/timetracker/createtimesheet?user=<user>&timesheetName=<timesheetName>&description=<description>&dateFormat=<dateFormat>&fromDate=<fromDate>&toDate=<toDate>&billableStatus=<billableStatus>&jobId=<jobId>&projectId=<projectId>&clientId=<clientId>&sendforApproval=<sendforApproval>
• POST Modify Timesheets API: Modifies an existing timesheet.
  https://people.zoho.com/people/api/timetracker/modifytimesheet?timesheetId=<timesheetId>&timesheetName=<timesheetName>&description=<description>&sendforApproval=<sendforApproval>&removeAttachment=<removeAttachment>
• GET Get Timesheets API: Lists timesheets by user and approval status.
  https://people.zoho.com/people/api/timetracker/gettimesheet?user=<user>&approvalStatus=<approvalStatus>&employeeStatus=<employeeStatus>&dateFormat=<dateFormat>&fromDate=<fromDate>&toDate=<toDate>&sIndex=<sIndex>&limit=<limit>
• GET Get Timesheets Details API: Returns the details of a timesheet by its ID.
  https://people.zoho.com/people/api/timetracker/gettimesheetdetails?timesheetId=<timesheetId>&dateFormat=<dateFormat>
• POST Approve Timesheets API: Approves a timesheet.
  https://people.zoho.com/people/api/timetracker/approvetimesheet?authtoken=<authtoken>&timesheetId=<timesheetId>&approvalStatus=<approvalStatus>&timeLogs=<timeLogs>&comments=<comments>&isAllLevelApprove=<isAllLevelApprove>
• POST Delete Timesheets API: Deletes a timesheet.
  https://people.zoho.com/people/api/timetracker/deletetimesheet?timesheetId=<timesheetId>

Onboarding and Candidate API

• POST Trigger Onboarding API: Starts onboarding for an existing candidate or employee. Limit: 30 requests per minute, 5-minute lock period.
  https://people.zoho.com/api/<Employee|Candidate>/triggerOnboarding
• POST Add Candidate API: Adds a candidate.
  https://people.zoho.in/people/api/forms/json/Candidate/insertRecord?inputData=<inputData>
• POST Update Candidate API: Updates a candidate record.
  https://people.zoho.com/people/api/forms/<inputType>/Candidate/updateRecord?inputData=<inputData>&recordId=<recordId>
• POST Reopen Onboarding API: Reopens onboarding for a candidate. Limit: 30 requests per minute, 5-minute lock period.
  https://people.zoho.com/api/candidate/reopen

Leave API

• POST Add Leave API: Adds a leave request.
  https://people.zoho.com/people/api/forms/<inputType>/<formLinkName>/insertRecord?inputData=<inputData>
• POST Get Record API: Fetches a leave record by its record ID.
  https://people.zoho.com/people/api/forms/leave/getDataByID?recordId=413124000068132003
• PATCH Cancel Leave API: Cancels a leave record.
  https://people.zoho.com/api/v2/leavetracker/leaves/records/cancel/<record-id>
• GET User Report API: Returns the leave report for a user.
  https://people.zoho.com/people/api/v2/leavetracker/reports/user
• GET Leave Booked and Balance Report API: Returns the leave booked and leave balance report.
  https://people.zoho.com/people/api/v2/leavetracker/reports/bookedAndBalance
• GET Leave Bradford API: Returns the leave Bradford report.
  https://people.zoho.com/people/api/v2/leavetracker/reports/bradford
• GET Encashment Report API: Returns the leave encashment report.
  https://people.zoho.com/people/api/v2/leavetracker/reports/encashment
• GET LOP Report API: Returns the LOP report.
  https://people.zoho.com/people/api/v2/leavetracker/reports/lop
• POST Add Leave Balance API: Adds to an employee’s leave balance.
  https://people.zoho.com/api/leave/addBalance?balanceData=<balanceData>&dateFormat=<dateFormat>

Attendance API

• POST Bulk Import API: Imports attendance entries in bulk.
  https://people.zoho.com/people/api/attendance/bulkImport?data=<JSONArray>
• GET Fetch Last Attendance Entries API: Fetches the latest attendance entries.
  https://people.zoho.com/api/attendance/fetchLatestAttEntries?duration=5&dateTimeFormat=dd-MM-yyyy HH:mm:ss
• POST Attendance Check In Check Out API: Records a check-in and check-out.
  https://people.zoho.com/people/api/attendance?dateFormat=<dateFormat>&checkIn=<checkin time>&checkOut=<checkout time>&empId=<employeeId>&emailId=<emailId>&mapId=<mapId>
• POST Attendance Entries API: Returns the attendance entries for a date.
  https://people.zoho.com/people/api/attendance/getAttendanceEntries?date=<date>&dateFormat=<dateformat>&erecno=<erecno>&mapId=<mapId>&emailId=<emailId>&empId=<empId>
• POST Attendance User Report API: Returns an attendance report for a user between two dates.
  https://people.zoho.com/people/api/attendance/getUserReport?sdate=<sdate>&edate=<edate>&empId=<employeeId>&emailId=<emailId>&mapId=<mapId>&dateFormat=<dateFormat>
• POST Employee Shift Mapping API: Maps an employee to a shift for a date range.
  https://people.zoho.com/people/api/attendance/updateUserShift?dateFormat=<dateformat>&empId=<employee Id>&shiftName=<shift name>&fdate=<FromDate>&tdate=<toDate>
• GET Getting Shift Details Of Employee API: Returns the shift details of an employee.
  https://people.zoho.com/people/api/attendance/getShiftConfiguration?empId=<employee Id>&emailId<email Id>=&mapId<Mapper ID>=&sdate<startDate>=&edate=<endDate>
• GET Get Regularization Records API: Returns attendance regularization records.
  https://people.zoho.com/people/api/attendance/getRegularizationRecords

Learning Management System (LMS) API

• GET Fetch Module Sessions API: Retrieves session details for the modules within a course batch.
  http://people.zoho.com/api/v1/courses/<courseId>/batches/<batchId>/modules/<moduleId>/sessions
• POST Unenroll Learner From Batch API: Unenrolls learners from a course batch.
  http://people.zoho.com/api/v1/courses/<courseId>/batches/<batchId>/unenroll?erecnosList=<erecnosList>
• DELETE Delete Online Test API: Deletes an online test from a course’s pre-learning activities.
  http://people.zoho.com/api/v1/courses/<courseId>/settings/precourseactivities/onlineTests/<testId>
• GET List Requisite Course Entities API: Lists the course entities that must be completed to unlock the current one.
  http://people.zoho.com/api/v1/courses/{Course ID}/batches/{Batch ID}/learners/{Learner ID}/lockedEntities/{Locked Entity ID}

Announcements API

• POST Add Announcement Comment API: Adds a comment to an announcement. Limit: 20 requests per minute, 5-minute lock period.
  https://people.zoho.com/api/announcement/addAnnouncementComment
• DELETE Delete Announcements API: Deletes a posted announcement by its ID. Limit: 20 requests per minute, 5-minute lock period.
  https://people.zoho.com/api/announcement/deleteAnnouncement
• DELETE Delete Announcement Comment API: Deletes a comment from an announcement. Limit: 20 requests per minute, 5-minute lock period.
  https://people.zoho.com/api/announcement/deleteAnnouncementComment
• POST Enable or Disable Announcements API: Enables or disables an announcement by its ID. Limit: 20 requests per minute, 5-minute lock period.
  https://people.zoho.com/api/announcement/enableDisableAnnouncement

Files API

• POST Add and Edit Folder API: Adds a folder, or edits an existing one, in the file modules.
  https://people.zoho.com/api/files/addFolder

Time Tracker API

• GET Add Job Schedule API: Adds a job schedule.
  https://people.zoho.com/api/timetracker/addJobSchedule
• DELETE Delete Job Schedule API: Deletes job schedules. Limit: 20 requests per minute, 5-minute lock period.
  https://people.zoho.com/api/timetracker/deleteJobSchedule
• POST Edit Job Schedule API: Modifies existing job schedules.
  https://people.zoho.com/api/timetracker/editJobSchedule
• GET Get Job Schedule API: Lists the job schedules of employees within a date range.
  https://people.zoho.com/api/timetracker/getJobSchedule
• GET Fetch Pay Period Details API: Retrieves pay period details for users or locations. Admins only. Limit: 20 requests per minute, 5-minute lock period.
  https://people.zoho.com/api/timetracker/getPayPeriodDetails
• GET Payroll Report API: Returns payroll data for users within a date range. Limit: 20 requests per minute, 5-minute lock period.
  https://people.zoho.com/api/timetracker/getpayrollreport
• GET Publish Job Schedule API: Publishes job schedules for users within a date range. Limit: 20 requests per minute, 5-minute lock period.
  https://people.zoho.com/api/timetracker/publishJobSchedule

For more information and details on other endpoints, check out this detailed resource. 

Common pitfalls (what usually breaks integrations)

• Ignoring rate limits and lock periods: You’ll get throttled or locked; design retries with backoff and respect module-specific thresholds.
• Not handling pagination properly: Many endpoints assume batch reads; implement startIndex/limit patterns consistently.
• Over-scoping OAuth permissions: Too-broad scopes increase security exposure; use least privilege.
• Weak identifier strategy: Standardize on stable identifiers (like erecno/record IDs) and map them cleanly across systems.
• No error logging discipline: Without structured logging, you’ll lose time diagnosing “random failures” that are actually predictable.
• Assuming admin-only APIs work for every token: Some endpoints are explicitly admin/data admin only, plan role access early.

Zoho People API Use Cases

Zoho People covers the HR workflows below. Many of them map to the API modules listed earlier (candidates, attendance, leave, timesheets and cases), so they show the kinds of processes you can read from, write to and automate through the API.

• Quick candidate onboarding with offer letter management, new hire portal, customizable workflows and status-view reports
• Cloud-based attendance management system to generate insightful reports, regularize attendance, option to check in from anywhere 
• Simple time off management tool with leave policy compliance, instant access to employee leave history, mobile leave applications and approvals and multi-location time off and holiday management
• Productivity timesheets to view the details of the time spent on every project, task, and client, get a centralized overview of your tasks and time resources, calculate payouts faster with accurate employee time logs and automate invoicing
• Shift scheduling to map employees to standard shifts, enable automatic shift rotation with a custom scheduler, mark, track, and analyze breaks and allowances
• Performance management with 360-degree, continuous feedback system, to evaluate employees with customized performance appraisal methods
• Case management to sort and organize employee questions, track their status, and reply promptly from a central location with an easily accessible knowledge base

Top customers

• Zomato, an Indian multinational restaurant aggregator and food delivery company
• The Logical Indian, an independent and public-spirited digital media platform for Indian millennials
• IIFL Finance, a leading finance & investment services company
• Meesho, an online shopping platform
• Waterfield Advisors, a leading independent Multi-Family Office and Wealth Advisory Firm
• DLT Labs, a global leader in the development and delivery of enterprise blockchain technologies and solutions

Zoho People API FAQs

• Does Zoho People have an API?
  • Yes, Zoho People provides a REST API for accessing and managing HR data programmatically – employee records, attendance, timesheets, cases, leave, and custom form data. The API uses OAuth 2.0 for authentication and returns data in JSON or XML format.
• How do I authenticate with the Zoho People API?
  • The Zoho People API uses OAuth 2.0 with the Authorization Code Grant Type – you obtain a grant token via the OAuth consent flow, then exchange it for an access token used in API requests. Access tokens are temporary and scoped to individual applications, meaning customers can revoke access at any time without exposing credentials. For multi-tenant integrations, each customer must complete the OAuth flow separately.
• What data can I access through the Zoho People API?
  • The Zoho People API exposes employee profiles, employment details, departments, attendance records, timesheets, leave requests, HR cases, and custom form data. It uses a forms-based data model where most HR data is structured as form records with configurable fields. Data availability depends on which Zoho People modules your organisation uses.
• How do I access attendance data through the Zoho People API?
  • Zoho People provides dedicated attendance endpoints — use the Attendance Entries API to add or retrieve clock-in/out records, and the Timesheet API to create and manage timesheet entries. Endpoints follow the pattern people.zoho.com/people/api/timetracker/... for timesheets and people.zoho.com/people/api/attendance/... for attendance.
• What are the main Zoho People API endpoints?
  • Zoho People’s core API endpoints include: Forms API for inserting, updating, fetching, and searching employee and HR records; Cases API for HR case management; Timesheet API for timetracking entries; and Attendance API for clock-in/out data. Most endpoints follow the base URL people.zoho.com/people/api/ and use Zoho’s form-based data model where records are tied to named forms.
• What are the Zoho People API rate limits?
  • Zoho People does not publish a single account-wide rate limit. Instead, the API reference gives a threshold and a lock period for individual endpoints (for example, 20 requests per minute with a 5-minute lock period for deleting an announcement), so check the limits for each endpoint you call. Implement pagination using the sIndex and limit parameters when fetching bulk records to avoid hitting limits, and add retry logic with exponential backoff for any rate limit responses.
• What are common Zoho People API integration use cases?
  • Common Zoho People API integration use cases include: syncing employee data from an ATS into Zoho People at onboarding; pushing timesheet data from time-tracking tools into Zoho People for payroll processing; pulling attendance records into analytics dashboards; syncing leave balances with scheduling tools; and integrating with LMS platforms to track employee training and compliance.
• What are the main challenges of building a Zoho People API integration?
  • The main challenges are Zoho People’s forms-based data model (records are tied to named forms rather than standard object types, requiring familiarity with each customer’s form configuration), managing OAuth credentials across multiple customer accounts, handling custom fields that vary by account, and endpoint-specific rate limits and lock periods. For multi-tenant SaaS products, per-customer OAuth setup adds onboarding friction.

More Zoho People API FAQs

1. What’s the biggest practical use of the Zoho People API?
   Automating HR workflows and syncing HR data across payroll, IT provisioning, LMS, and reporting, so processes don’t depend on manual updates.
2. How does authentication work for Zoho People APIs?
   The endpoints use Zoho OAuth tokens in the Authorization header, with access governed by scopes.
3. What should I plan for when syncing large datasets?
   Pagination and record caps (for example, fetching up to 200 records at a time) and module-specific rate limits.
4. Are all endpoints available to all users?
   No. Some endpoints are restricted to admin/data admin users (for example, certain attendance APIs).
5. How do I avoid getting rate-limited?
   Implement request throttling, exponential backoff retries, and respect threshold + lock-period behavior per endpoint.
6. What identifiers should I use to link users across systems?
   Use stable platform identifiers like record IDs and erecno, and maintain a mapping layer in your integration.
7. Can Zoho People API be used for LMS automation end-to-end?
   Yes, based on the endpoints listed, you can manage course creation, enrollments, sessions, attendance marking, publishing states, and related settings.

Zoho People API questions from the community

• What to do when you cannot use searchParams on Zoho People API (HTTP Status 400)? Answer
• How to achieve webhook integration between Podio and Zoho People? Answer
• How to get the attendance API from Zoho People in postman? Answer
• What to do if permission is denied when trying to fetch records from Zoho People? Answer
• How to parse through the following ZOHO People JSON string using VB.NET? Answer
• How to write a custom function in Zoho People Deluge to fetch all the dates between from and to given? Answer
• How to sync Zoho People with Google Calendar API for event time update without changing date? Answer

Get started with Zoho People API

Integrating with Zoho People API requires engineering bandwidth, resources and knowledge. Invariably, building and maintaining this integration can be extremely expensive for SaaS companies. Fortunately, with Knit, a unified HRIS API, you can easily integrate with Zoho People API and other multiple HRIS applications at once. Knit enables users to normalize data from across HRIS applications, including Zoho People, 10x faster, ensure higher security with double encryption and facilitates bi-directional data sync with webhook architecture to ensure guaranteed scalability, irrespective of data load. Talk to a human to learn how you can get started with Zoho People API with ease.