List Leave Requests

Retrieve a paginated list of leave requests with filtering options

GET /leave-requests

cURL

curl -X GET "https://api.companyflow.com/leave-requests?page=1&pageSize=20&status=pending" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response

{
  "success": true,
  "data": {
    "items": [
      {
        "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "employeeId": "987e6543-e21b-12d3-a456-426614174000",
        "leaveTypeId": "123e4567-e89b-12d3-a456-426614174000",
        "startDate": "2025-03-15T00:00:00Z",
        "endDate": "2025-03-19T00:00:00Z",
        "daysRequested": 5,
        "reason": "Family vacation",
        "attachmentUrl": null,
        "status": "pending",
        "currentStep": 1,
        "approvedBy": null,
        "approvedAt": null,
        "rejectionReason": "",
        "createdAt": "2025-03-03T10:30:00Z",
        "updatedAt": "2025-03-03T10:30:00Z"
      },
      {
        "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
        "employeeId": "987e6543-e21b-12d3-a456-426614174000",
        "leaveTypeId": "234f5678-f90c-23e4-b567-537725285111",
        "startDate": "2025-02-10T00:00:00Z",
        "endDate": "2025-02-12T00:00:00Z",
        "daysRequested": 3,
        "reason": "Medical appointment",
        "attachmentUrl": "https://storage.example.com/medical-cert.pdf",
        "status": "approved",
        "currentStep": 2,
        "approvedBy": "345a6789-a01d-34f5-c678-648836396222",
        "approvedAt": "2025-02-08T14:20:00Z",
        "rejectionReason": "",
        "createdAt": "2025-02-05T09:15:00Z",
        "updatedAt": "2025-02-08T14:20:00Z"
      }
    ],
    "total": 42,
    "page": 1,
    "pageSize": 20,
    "totalPages": 3
  }
}

Overview

Retrieve all leave requests with support for pagination and filtering by employee, status, and date range. Managers and HR can view all requests, while employees see only their own requests.

Authentication

Requires authentication with Bearer token. Available to:

• SuperAdmin
• HR Manager
• Manager
• Employee (limited to own requests)

Query parameters

page · integer · default: "1"

Page number for pagination

pageSize · integer · default: "10"

Number of items per page (max: 100)

employeeId · string

Filter by employee UUID. Employees can only filter by their own ID.

status · string

Filter by request status. Available values:

• pending - Awaiting approval
• approved - Approved by manager
• rejected - Rejected by manager
• cancelled - Cancelled by system
• withdrawn - Withdrawn by employee

Response

success · boolean

Indicates if the request was successful

data · object

Pagination wrapper containing leave requests

Show Pagination data

items · array

Array of leave request objects

Show LeaveRequest properties

id · string

Unique identifier for the leave request

employeeId · string

UUID of the employee

leaveTypeId · string

UUID of the leave type

startDate · string

Leave start date (ISO 8601)

endDate · string

Leave end date (ISO 8601)

daysRequested · number

Number of days requested

reason · string

Reason for leave

status · string

Current status

approvedBy · string

UUID of approver (null if pending)

approvedAt · string

Approval timestamp

createdAt · string

Creation timestamp

total · integer

Total number of leave requests matching the filters

page · integer

Current page number

pageSize · integer

Number of items per page

totalPages · integer

Total number of pages

cURL

curl -X GET "https://api.companyflow.com/leave-requests?page=1&pageSize=20&status=pending" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response

{
  "success": true,
  "data": {
    "items": [
      {
        "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "employeeId": "987e6543-e21b-12d3-a456-426614174000",
        "leaveTypeId": "123e4567-e89b-12d3-a456-426614174000",
        "startDate": "2025-03-15T00:00:00Z",
        "endDate": "2025-03-19T00:00:00Z",
        "daysRequested": 5,
        "reason": "Family vacation",
        "attachmentUrl": null,
        "status": "pending",
        "currentStep": 1,
        "approvedBy": null,
        "approvedAt": null,
        "rejectionReason": "",
        "createdAt": "2025-03-03T10:30:00Z",
        "updatedAt": "2025-03-03T10:30:00Z"
      },
      {
        "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
        "employeeId": "987e6543-e21b-12d3-a456-426614174000",
        "leaveTypeId": "234f5678-f90c-23e4-b567-537725285111",
        "startDate": "2025-02-10T00:00:00Z",
        "endDate": "2025-02-12T00:00:00Z",
        "daysRequested": 3,
        "reason": "Medical appointment",
        "attachmentUrl": "https://storage.example.com/medical-cert.pdf",
        "status": "approved",
        "currentStep": 2,
        "approvedBy": "345a6789-a01d-34f5-c678-648836396222",
        "approvedAt": "2025-02-08T14:20:00Z",
        "rejectionReason": "",
        "createdAt": "2025-02-05T09:15:00Z",
        "updatedAt": "2025-02-08T14:20:00Z"
      }
    ],
    "total": 42,
    "page": 1,
    "pageSize": 20,
    "totalPages": 3
  }
}

Filtering examples

Filter by employee

curl -X GET "https://api.companyflow.com/leave-requests?employeeId=987e6543-e21b-12d3-a456-426614174000" \
  -H "Authorization: Bearer YOUR_TOKEN"

Use cases

Manager dashboard

Retrieve all pending leave requests for team members to review and approve

Employee history

View personal leave history filtered by status and date range

HR reporting

Generate reports on leave usage across the organization

Team calendar

Display approved leave requests for team scheduling

Performance tip: Use pagination with reasonable page sizes (10-50 items) for optimal performance. The API enforces a maximum page size of 100.