Leave

Leave API – time-off requests and leave balance in Zoho People.

Endpoints covered

• GET  forms/leave/getRecords – list leave requests (v1)

• GET  forms/leave/getDataByID – single leave request

• POST forms/leave/addLeave – submit a leave request

• POST forms/leave/updateLeave – update a leave request

• POST forms/leave/approveLeave – approve / reject

• POST forms/leave/cancelLeave – cancel a request

• GET  v2/leavetracker/reports/bookedAndBalance – leave balance report

• GET  v2/leavetracker/leaves/records – filtered records (v2)

Scope required: ZOHOPEOPLE.leave.ALL

zoho_people.api.leave.ACTIVE_STATUSES: frozenset[str] = frozenset({'approved', 'in sospeso', 'pending', 'submitted', 'waiting'})

ApprovalStatus values that represent an active (non-cancelled) leave.

class zoho_people.api.leave.LeaveAPI(client)

Bases: object

Manage leave and time-off requests in Zoho People.

Obtain an instance via ZohoPeopleClient.leave.

Examples

List approved leaves for April:

leaves = client.leave.list(
    from_date="01-Apr-2026",
    to_date="30-Apr-2026",
    approval_status="Approved",
)

Submit a leave request:

client.leave.apply(
    leave_type_id="413124000000645719",
    from_date="04-May-2026",
    to_date="05-May-2026",
    reason="Vacation",
)

Parameters:

client (ZohoPeopleClient)

list(from_date=None, to_date=None, approval_status=None, emp_id=None, leave_type=None, s_index=1, rec_limit=200)

Retrieve leave requests from the v1 endpoint.

Parameters:

• from_date (str | None) – Period start in the organisation’s date format.

• to_date (str | None) – Period end.

• approval_status (str | None) – "Approved" | "Pending" | "Rejected" | "Cancelled"

• emp_id (str | None) – Filter by employee ID or e-mail.

• leave_type (str | None) – Filter by leave type name or ID.

• s_index (int) – Pagination start index (default 1).

• rec_limit (int) – Records per page, max 200.

Returns:

{"records": {record_id: {...}}}

Return type:

dict

get(record_id)

Retrieve details for a single leave request.

Parameters:

record_id (str) – Leave request record ID.

Return type:

dict[str, Any]

get_balance(emp_ids=None, from_date=None, to_date=None)

Retrieve leave balance and booked days per leave type (up to 30 employees).

Parameters:

• emp_ids (list[str] | None) – Employee IDs or e-mails. Defaults to the authenticated user.

• from_date (str | None) – Period start date.

• to_date (str | None) – Period end date.

Return type:

dict[str, Any]

get_pending(from_date=None, to_date=None, data_select='MINE')

Retrieve leave requests pending approval (v2 endpoint).

Parameters:

• from_date (str | None) – Period start ("dd-MMM-yyyy"). Required by the API.

• to_date (str | None) – Period end.

• data_select (str) – "MINE" (default) | "SUB" | "ALL"

Returns:

{"records": {record_id: {...}}}

Return type:

dict

get_approved_and_pending(from_date=None, to_date=None, data_select='MINE')

Retrieve both approved and pending leave records.

Useful for excluding active leave days from attendance / timesheet calculations.

Returns:

{"records": {record_id: {...}}}

Return type:

dict

Parameters:

• from_date (str | None)

• to_date (str | None)

• data_select (str)

apply(leave_type_id, from_date, to_date, reason=None, emp_id=None, from_session=None, to_session=None)

Submit a leave request.

Parameters:

• leave_type_id (str) – Leave type ID — retrieve available types via get_balance().

• from_date (str) – Start date in the organisation’s date format.

• to_date (str) – End date.

• reason (str | None) – Optional reason text.

• emp_id (str | None) – Employee ID when applying on behalf of someone else.

• from_session (int | None) – Session start (1 = morning, 2 = afternoon, …).

• to_session (int | None) – Session end.

Returns:

Zoho API response with the new record ID.

Return type:

dict

update(record_id, data)

Update an existing leave request.

Parameters:

• record_id (str)

• data (dict[str, Any])

Return type:

dict[str, Any]

approve(record_id, status='Approved', comments=None)

Approve or reject a leave request.

Parameters:

• record_id (str) – Leave request record ID.

• status (str) – "Approved" | "Rejected"

• comments (str | None) – Optional approval / rejection comment.

Return type:

dict[str, Any]

cancel(record_id, reason=None)

Cancel a leave request.

Parameters:

• record_id (str)

• reason (str | None)

Return type:

dict[str, Any]