Leaves API — Leave, WFH, and Half-Day Requests - Workforce Intelligence & Execution OS

The Leaves API handles the full lifecycle of employee time-off requests — from initial submission by the employee, through manager review and resolution, to optional escalation for HR oversight. Results are automatically scoped by the caller’s role so that employees see only their own requests, managers see their team’s queue, and admins see everything.

All endpoints are prefixed with /api/v1/leaves and require an Authorization: Bearer <token> header. Dates are plain YYYY-MM-DD strings; timestamps are ISO-8601 UTC.

Enum Reference

Leave Type

Value	Description
`sick`	Medical or health-related absence.
`casual`	Short personal leave for everyday matters.
`annual`	Pre-planned annual leave entitlement.
`half_day`	Either the first or second half of a working day. Set `is_half_day: true` and supply `half_day_period`.
`wfh`	Work-from-home day tracked through the leave system.

Leave Status

Value	Description
`pending`	Submitted and awaiting manager action.
`approved`	Approved by the authorised approver.
`rejected`	Declined; `manager_comment` contains the reason.
`escalated`	Escalated to a senior approver.
`cancelled`	Cancelled by the submitting employee.
`needs_clarification`	Approver has requested more detail from the employee.

Half-Day Period

Value	Description
`first_half`	Morning half of the working day.
`second_half`	Afternoon half of the working day.

Approval Action (for resolve)

Value	Description
`approved`	Grant the request.
`rejected`	Decline the request. A `manager_comment` is required.
`escalated`	Escalate to the next approver. A `manager_comment` is required.
`cancelled`	Cancel the request (used by the approver to withdraw).
`clarified`	Mark that clarification has been provided.

POST /leaves

Submit a new leave, WFH, or half-day request. The system routes the request to the employee’s direct manager as the initial approver. Auth: Any authenticated user.

Request Body

start_date

string

required

First day of requested leave. Format: YYYY-MM-DD.

end_date

string

required

Last day of requested leave. Format: YYYY-MM-DD. Must be equal to or after start_date.

leave_type

string

required

Type of request: sick, casual, annual, half_day, or wfh.

reason

string

required

Explanation for the request. Required by the approval workflow.

is_half_day

boolean

Set to true when requesting only half a day. Default: false.

half_day_period

string

Required when is_half_day is true. Must be first_half or second_half.

Response Fields

Returns the newly created LeaveRequestRead object with status: "pending" and current_approver_id pointing to the employee’s manager.

uuid

required

Unique request identifier.

user_id

uuid

required

UUID of the employee who submitted the request.

user_full_name

string

Resolved display name of the requesting employee.

start_date

date

required

First day of the requested leave (YYYY-MM-DD).

end_date

date

required

Last day of the requested leave (YYYY-MM-DD).

leave_type

string

required

One of the leave type enum values listed above.

status

string

required

Current request status (see status table above).

is_half_day

boolean

required

true when the request covers only half a working day.

half_day_period

string

Which half: first_half or second_half. Present only when is_half_day is true.

reason

string

required

Employee-supplied explanation for the request.

manager_comment

string

Reviewer’s note attached during resolution; required when rejecting or escalating.

current_approver_id

uuid

UUID of the user whose action is currently awaited.

escalated_from_id

uuid

UUID of the approver the request was escalated from.

escalated_at

datetime

Timestamp of escalation, if applicable.

escalation_count

integer

Number of times this request has been escalated.

created_at

datetime

required

ISO-8601 UTC submission timestamp.

updated_at

datetime

required

ISO-8601 UTC last-update timestamp.

start_date must not be after end_date. For single-day requests, set both to the same date. Violating this constraint returns 400 Bad Request.

Example — Full-day sick leave

curl -X POST "https://api.example.com/api/v1/leaves" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "start_date": "2024-07-15",
    "end_date": "2024-07-16",
    "leave_type": "sick",
    "reason": "Flu and fever — doctor advised two days rest."
  }'

Example — Half-day

curl -X POST "https://api.example.com/api/v1/leaves" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "start_date": "2024-07-18",
    "end_date": "2024-07-18",
    "leave_type": "half_day",
    "reason": "Personal errand in the morning.",
    "is_half_day": true,
    "half_day_period": "first_half"
  }'

GET /leaves/me

Retrieve the authenticated employee’s own leave request history, ordered by submission date descending. Auth: Any authenticated user.

Response Fields

Returns an array of LeaveRequestRead objects. See POST /leaves for the full field list.

Example

curl -X GET "https://api.example.com/api/v1/leaves/me" \
  -H "Authorization: Bearer <token>"

GET /leaves/pending

Return the list of leave requests currently awaiting the authenticated user’s approval action. This is the primary data source for a manager’s or HR admin’s approval inbox. Auth: Any authenticated user. Returns only requests where current_approver_id matches the caller’s UUID.

Response Fields

Returns an array of LeaveRequestRead objects with status: "pending" or status: "needs_clarification".

Poll this endpoint periodically or listen to notification events to keep your approval UI badge count accurate.

Example

curl -X GET "https://api.example.com/api/v1/leaves/pending" \
  -H "Authorization: Bearer <token>"

PATCH /leaves//resolve

Approve, reject, escalate, or take another action on a pending leave request. The caller must be the current_approver_id on the request, or hold an admin or hr_operations role. Employees cannot approve their own requests. Auth: Manager, Team Lead, Admin, or HR Operations. Self-approval is explicitly blocked.

Path Parameters

request_id

uuid

required

UUID of the leave request to resolve.

Request Body

action

string

required

Resolution decision. One of: approved, rejected, escalated, cancelled, clarified.

manager_comment

string

Reviewer note. Required when action is rejected or escalated; optional for other actions.

Response Fields

Returns the updated LeaveRequestRead with the new status and manager_comment.

Attempting to resolve a request you do not own (not current_approver_id) without admin or hr_operations role returns 403 Forbidden. Managers cannot resolve requests for employees outside their direct reports.

Example — Approve

curl -X PATCH "https://api.example.com/api/v1/leaves/3fa85f64-5717-4562-b3fc-2c963f66afa6/resolve" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "approved",
    "manager_comment": "Approved. Get well soon."
  }'

Example — Reject with required comment

curl -X PATCH "https://api.example.com/api/v1/leaves/3fa85f64-5717-4562-b3fc-2c963f66afa6/resolve" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "rejected",
    "manager_comment": "Critical sprint delivery this week — please reschedule."
  }'

POST /leaves//cancel

Cancel a pending leave request. Only the employee who submitted the request may cancel it. Auth: Any authenticated user (own requests only).

Path Parameters

request_id

uuid

required

UUID of the leave request to cancel.

Response Fields

Returns the updated LeaveRequestRead with status: "cancelled".

Example

curl -X POST "https://api.example.com/api/v1/leaves/3fa85f64-5717-4562-b3fc-2c963f66afa6/cancel" \
  -H "Authorization: Bearer <token>"

GET /leaves//timeline

Retrieve the full approval timeline for a leave request, listing every action taken in chronological order. Auth: Any authenticated user (RBAC-scoped).

Path Parameters

request_id

uuid

required

UUID of the leave request.

Response Fields

Returns an array of ApprovalTimelineRead objects.

uuid

required

Unique timeline event identifier.

actor_id

uuid

required

UUID of the user who performed this action.

actor_name

string

Display name of the actor.

action

string

required

Action taken: created, clarified, approved, rejected, escalated, or cancelled.

comment

string

Comment attached to this action.

created_at

datetime

required

ISO-8601 UTC timestamp of the action.

Example

curl -X GET "https://api.example.com/api/v1/leaves/3fa85f64-5717-4562-b3fc-2c963f66afa6/timeline" \
  -H "Authorization: Bearer <token>"

Standard Error Response

{
  "detail": "You cannot approve or reject your own leave request."
}

Common HTTP status codes for this resource: 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found.

Overview

Endpoints

Leaves API — Leave, WFH, and Half-Day Requests

Enum Reference

Leave Type

Leave Status

Half-Day Period

Approval Action (for resolve)

POST /leaves

Request Body

Response Fields

GET /leaves/me

Response Fields

GET /leaves/pending

Response Fields

PATCH /leaves//resolve

Path Parameters

Request Body

Response Fields

POST /leaves//cancel

Path Parameters

Response Fields

GET /leaves//timeline

Path Parameters

Response Fields

Standard Error Response

Build docs developers (and LLMs) love

Overview

Endpoints

Documentation Index

​Enum Reference

​Leave Type

​Leave Status

​Half-Day Period

​Approval Action (for resolve)

​POST /leaves

​Request Body

​Response Fields

​GET /leaves/me

​Response Fields

​GET /leaves/pending

​Response Fields

​PATCH /leaves//resolve

​Path Parameters

​Request Body

​Response Fields

​POST /leaves//cancel

​Path Parameters

​Response Fields

​GET /leaves//timeline

​Path Parameters

​Response Fields

​Standard Error Response

Build docs developers (and LLMs) love

Enum Reference

Leave Type

Leave Status

Half-Day Period

Approval Action (for resolve)

POST /leaves

Request Body

Response Fields

GET /leaves/me

Response Fields

GET /leaves/pending

Response Fields

PATCH /leaves//resolve

Path Parameters

Request Body

Response Fields

POST /leaves//cancel

Path Parameters

Response Fields

GET /leaves//timeline

Path Parameters

Response Fields

Standard Error Response