Introduction
This article is part of a broader series covering the Zoho People API in depth. It focuses on a high-frequency use case: retrieving employee leave data efficiently and reliably.
If you’re building HR integrations or automating workforce workflows, this is not optional plumbing, it’s core infrastructure.
For a complete breakdown of Zoho People API capabilities, including authentication and rate limits, refer to the full guide here.
Pre-requisites
- Zoho People account with API access
- OAuth token for authentication
- Employee ID, email ID, or record ID
API Endpoints
- Get Leave Types:
https://people.zoho.com/people/api/leave/getLeaveTypeDetails?userId=<userId> - Get Holidays:
https://people.zoho.com/people/api/leave/getHolidays?userId=<userId> - Fetch Single Record:
https://people.zoho.com/people/api/forms/leave/getDataByID?recordId=<recordId>
Step-by-Step Process
1. Get Leave Types
import requests
def get_leave_types(user_id, auth_token):
url = f"https://people.zoho.com/people/api/leave/getLeaveTypeDetails?userId={user_id}"
headers = {"Authorization": f"Zoho-oauthtoken {auth_token}"}
response = requests.get(url, headers=headers)
return response.json()
# Example usage
leave_types = get_leave_types("user@example.com", "your_auth_token")
print(leave_types)2. Get Holidays
def get_holidays(user_id, auth_token):
url = f"https://people.zoho.com/people/api/leave/getHolidays?userId={user_id}"
headers = {"Authorization": f"Zoho-oauthtoken {auth_token}"}
response = requests.get(url, headers=headers)
return response.json()
# Example usage
holidays = get_holidays("user@example.com", "your_auth_token")
print(holidays)3. Fetch Single Record
def fetch_single_record(record_id, auth_token):
url = f"https://people.zoho.com/people/api/forms/leave/getDataByID?recordId={record_id}"
headers = {"Authorization": f"Zoho-oauthtoken {auth_token}"}
response = requests.get(url, headers=headers)
return response.json()
# Example usage
record = fetch_single_record("413124000068132003", "your_auth_token")
print(record)Common Pitfalls
- Rate limits will break your flow
Zoho enforces strict limits. No throttling strategy = failed pipelines. - Token handling is often sloppy
Expired or mis-scoped OAuth tokens are the #1 failure point. - Identifier inconsistency creates silent errors
Mixing user ID, email, and record ID without validation leads to bad data pulls. - Error handling is usually an afterthought
If you’re not actively parsing response codes, you’re flying blind. - JSON parsing assumptions don’t hold
Field structures can vary, hardcoding schemas is a mistake. - No retry logic = fragile integrations
Temporary failures will cascade without retries and backoff. - Ignoring API changes will cost you later
Zoho updates APIs. If you’re not monitoring, your integration will degrade.
Top FAQs
Q: How do I obtain an OAuth token?
A: Generate it from the Zoho Developer Console.
Q: What is the rate limit for API calls?
A: 30 requests per minute with a 5-minute lock period.
Q: Can I use email ID instead of user ID?
A: Yes, both are supported.
Q: What data format is returned?
A: JSON format.
Q: How do I handle API errors?
A: Check the status code and error message in the response.
Q: Is there a sandbox environment?
A: Yes, Zoho provides a sandbox for testing.
Q: Can I fetch data for all employees?
A: Yes, but you need to iterate over each employee ID.
Knit for Zoho People API Integration
For quick and scalable access to the Zoho People API, Knit provides a cleaner path. One integration replaces multiple point solutions.
Authentication, authorization, and ongoing maintenance are handled upfront, reducing engineering overhead and operational risk. The result: faster deployment, fewer breakpoints, and a more reliable integration stack.
Ready to build this integration?
Explore Knit’s Zoho People integration or read more about our Unified HRIS API.
Changing integration landscape, one organization at a time
