CitoHRCitoHR
API Reference

Leave Management API

Manage leave requests, view calendars, and handle leave approvals through the CitoHR API.

Get Leave Requests

Retrieve leave requests for a user.

GET /api/leave

Query parameters:

  • userId - Filter by user ID (optional, requires MANAGER or ADMIN role to access other users)

Authorization: Requires valid session. Users can view their own leave requests. MANAGER and ADMIN roles can view team members' requests.

Create Leave Request

Create a new leave request.

POST /api/leave

Request body: 

{
  "startDate": "2024-01-15T00:00:00.000Z",
  "endDate": "2024-01-20T00:00:00.000Z",
  "type": "ANNUAL",
  "notes": "Family vacation"
}

Leave Types: ANNUAL, SICK, UNPAID, MATERNITY, PATERNITY, BEREAVEMENT, OTHER

Update Leave Request

Update an existing leave request (only if status is PENDING).

PUT /api/leave/{id}

Request body (same as create): 

{
  "startDate": "2024-01-15T00:00:00.000Z",
  "endDate": "2024-01-22T00:00:00.000Z",
  "type": "ANNUAL",
  "notes": "Updated vacation dates"
}

Delete Leave Request

Delete a leave request (only if status is PENDING).

DELETE /api/leave/{id}

Approve or Reject Leave Request

Approve or reject a leave request. Requires MANAGER or ADMIN role.

PUT /api/leave/{id}/status

Request body: 

{
  "status": "APPROVED"
}

Status values: APPROVED, REJECTED

Get Leave Calendar

Retrieve leave calendar with leave requests and public holidays for a date range.

GET /api/leave/calendar

Query parameters:

  • startDate - Start date (required, ISO format)
  • endDate - End date (required, ISO format)
  • departmentId - Filter by department (optional)
  • types - Comma-separated list of leave types (optional)

Returns leave requests and public holidays grouped by user, with country-specific holidays based on employee nationality.

Get Pending Approvals

Retrieve pending leave requests for the current user.

GET /api/leave/pending-approvals

Get Upcoming Leave

Retrieve upcoming approved leave requests.

GET /api/leave/upcoming

Query parameters:

  • page - Page number (default: 1)
  • pageSize - Items per page (default: 10)
  • sortBy - Sort field (default: createdAt)
  • sortOrder - Sort order: asc or desc (default: desc)

Get Team Leave Requests

Retrieve leave requests for team members. Requires MANAGER or ADMIN role.

GET /api/leave/team

Query parameters:

  • page - Page number (default: 1)