Skip to main content

Leave API

Endpoints for managing leave requests, entitlements, and approval workflows.

List All Leave Requests​

GET /leave

Response: 200 OK with the list of leave requests.

Get Leave Request Details​

GET /leave/{id}

Response: 200 OK with leave request details.

Get Leave Entitlement​

Returns the current user's leave entitlement and balances.

GET /leave/entitlement

Response: 200 OK

Check Leave Availability​

Verifies whether a date range is available for a leave type.

GET /leave/check/{leaveType}/{startDate}/{endDate}

Path Parameters:

  • leaveType: Leave type ID
  • startDate: Start date (YYYY-MM-DD)
  • endDate: End date (YYYY-MM-DD)

Response: 200 OK with availability check result.

Apply for Leave​

Submits a new leave request.

POST /leave/apply

Request Body:

{
  "leave_type": 1,
  "start": "2026-05-01",
  "end": "2026-05-03",
  "details": "Family vacation",
  "attachment": null,
  "days": {
    "2026-05-01": "Full Day",
    "2026-05-02": "Full Day",
    "2026-05-03": "Half Day - Morning"
  }
}

Request Fields:

  • leave_type: Leave type ID
  • start: Start date (YYYY-MM-DD)
  • end: End date (YYYY-MM-DD)
  • details: Reason for leave
  • attachment: Optional attached file reference
  • days: Object mapping each date to a duration value

Response: 200 OK

Upload Leave Attachment​

Uploads a file attachment to attach to a leave request.

POST /leave/file-upload

Request: multipart/form-data with a file field.

Response: 200 OK with the uploaded filename.

Get Direct Reports' Leave Requests​

Returns all leave requests from employees who report to the current user.

GET /leave/direct-reports

Response: 200 OK

{
  "status": "SUCCESS",
  "data": [
    {
      "id": 12,
      "employee": "Jane Doe",
      "leave_type": "Annual Leave",
      "leave_period": "2026",
      "date_start": "2026-05-01",
      "date_end": "2026-05-03",
      "status": "Pending"
    }
  ]
}

Error Responses:

  • 401 Unauthorized
  • 404 Not Found if no employee record exists for the current user

Get Pending Direct Reports' Leave Requests​

Returns only leave requests with Pending status from direct reports.

GET /leave/direct-reports/pending

Response: 200 OK with pending leave requests.

Get Leave Details​

Returns full leave details including leave type, period, day breakdown, current balance, and activity logs.

GET /leave/details/{id}

Response: 200 OK

{
  "status": "SUCCESS",
  "id": 12,
  "currentBalance": 14.5,
  "leave": { },
  "leaveType": { },
  "leavePeriod": { },
  "days": [
    {"id": 1, "leave_date": "2026-05-01", "leave_type": "Full Day"}
  ],
  "logs": []
}

Approve Leave Request​

Approves a pending leave request. Only supervisors or authorized approvers can approve. The note is stored in the leave log.

POST /leave/{id}/approve

Request Body (optional):

{
  "reason": "Approved for the requested dates"
}

The fields reason and note are aliases.

Response: 200 OK

{
  "status": "SUCCESS",
  "message": "Leave request Approved",
  "leave": { }
}

Error Responses:

  • 401 Unauthorized
  • 403 Forbidden if not authorized to approve
  • 404 Not Found

Reject Leave Request​

Rejects a pending leave request. Only supervisors or authorized approvers can reject.

POST /leave/{id}/reject

Request Body (optional):

{
  "reason": "Insufficient leave balance"
}

Response: 200 OK

{
  "status": "SUCCESS",
  "message": "Leave request Rejected",
  "leave": { }
}

Leave Status Values​

  • Pending: Awaiting approval
  • Approved: Leave request approved
  • Rejected: Leave request rejected
  • Cancelled: Cancelled by employee

Leave Day Types​

  • Full Day: Entire day off
  • Half Day - Morning: Morning half-day leave
  • Half Day - Afternoon: Afternoon half-day leave