zoho-people-sdk

Python SDK for the Zoho People REST API.

Covers attendance, timesheet, leave management, and employee records — with automatic OAuth token refresh, typed exceptions, and full type hints.

📚 Full documentation: zoho-sdk-people.readthedocs.io

Features

• Attendance — check-in / check-out, bulk import, user reports, shift configuration
• Timesheet — create, submit, approve time logs and timesheet periods
• Leave — apply, approve, cancel leave requests; leave balance report
• Employees — list, search by email / ID, create and update records
• OAuth 2.0 — automatic token refresh, from_env() helper, multi data-centre support
• Typed exceptions — ZohoPeopleAuthError, ZohoPeoplePermissionError, ZohoPeopleRateLimitError, …
• PEP 561 — fully typed, py.typed marker included

Installation

pip install zoho-people-sdk

With browser fallback for attendance (when API permissions are unavailable):

pip install "zoho-people-sdk[browser]"
playwright install chromium

Quick Start

from zoho_people import ZohoPeopleAuth, ZohoPeopleClient

# Load credentials from environment variables:
# ZOHO_CLIENT_ID, ZOHO_CLIENT_SECRET, ZOHO_REFRESH_TOKEN, ZOHO_DATA_CENTRE
auth   = ZohoPeopleAuth.from_env()
client = ZohoPeopleClient(auth=auth)

# Employees
employees = client.employee.list()

# Add a time log
client.timesheet.add_timelog(
    user="mario.rossi@company.com",
    work_date="2026-04-25",
    hours="08:00",
    job_name="My Project",
)

# Pending leave requests
pending = client.leave.get_pending(
    from_date="01-Apr-2026",
    to_date="30-Apr-2026",
)

# Monthly attendance report
report = client.attendance.get_user_report(
    start_date="01/04/2026",
    end_date="30/04/2026",
    date_format="dd/MM/yyyy",
)

Environment Variables

Copy .env.example to .env:

ZOHO_CLIENT_ID=1000.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
ZOHO_CLIENT_SECRET=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
ZOHO_DATA_CENTRE=US          # US | EU | IN | AU | JP
ZOHO_REFRESH_TOKEN=1000.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
ZOHO_USER_EMAIL=you@company.com

Required OAuth scopes:

ZOHOPEOPLE.forms.ALL,ZOHOPEOPLE.attendance.ALL,ZOHOPEOPLE.timetracker.ALL,ZOHOPEOPLE.leave.ALL

Error Handling

from zoho_people.exceptions import (
    ZohoPeopleAuthError,
    ZohoPeoplePermissionError,
    ZohoPeopleRateLimitError,
    ZohoPeopleNotFoundError,
    ZohoPeopleValidationError,
    ZohoPeopleError,
)

try:
    client.timesheet.add_timelog(...)
except ZohoPeoplePermissionError:
    print("Missing role permission in Zoho People settings")
except ZohoPeopleAuthError:
    print("Invalid or expired OAuth token")
except ZohoPeopleRateLimitError:
    print("Rate limit hit — SDK will auto-retry")
except ZohoPeopleError as e:
    print(f"API error {e.status_code}: {e.message}")

Data Centres

Documentation

Full documentation at zoho-sdk-people.readthedocs.io in English and Italian:

• Getting Started
• User Guide
• API Reference

Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature/my-feature
3. Install dev dependencies: pip install -e ".[dev]"
4. Run tests: pytest
5. Lint: ruff check src/
6. Open a pull request

License

MIT © 2026 madyel83