> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/Falasefemi2/companyflow/llms.txt
> Use this file to discover all available pages before exploring further.

# List Leave Requests

> Retrieve a paginated list of leave requests with filtering options

## 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

<ParamField query="page" type="integer" default="1">
  Page number for pagination
</ParamField>

<ParamField query="pageSize" type="integer" default="10">
  Number of items per page (max: 100)
</ParamField>

<ParamField query="employeeId" type="string">
  Filter by employee UUID. Employees can only filter by their own ID.
</ParamField>

<ParamField query="status" type="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
</ParamField>

## Response

<ResponseField name="success" type="boolean">
  Indicates if the request was successful
</ResponseField>

<ResponseField name="data" type="object">
  Pagination wrapper containing leave requests

  <Expandable title="Pagination data">
    <ResponseField name="items" type="array">
      Array of leave request objects

      <Expandable title="LeaveRequest properties">
        <ResponseField name="id" type="string">
          Unique identifier for the leave request
        </ResponseField>

        <ResponseField name="employeeId" type="string">
          UUID of the employee
        </ResponseField>

        <ResponseField name="leaveTypeId" type="string">
          UUID of the leave type
        </ResponseField>

        <ResponseField name="startDate" type="string">
          Leave start date (ISO 8601)
        </ResponseField>

        <ResponseField name="endDate" type="string">
          Leave end date (ISO 8601)
        </ResponseField>

        <ResponseField name="daysRequested" type="number">
          Number of days requested
        </ResponseField>

        <ResponseField name="reason" type="string">
          Reason for leave
        </ResponseField>

        <ResponseField name="status" type="string">
          Current status
        </ResponseField>

        <ResponseField name="approvedBy" type="string">
          UUID of approver (null if pending)
        </ResponseField>

        <ResponseField name="approvedAt" type="string">
          Approval timestamp
        </ResponseField>

        <ResponseField name="createdAt" type="string">
          Creation timestamp
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="total" type="integer">
      Total number of leave requests matching the filters
    </ResponseField>

    <ResponseField name="page" type="integer">
      Current page number
    </ResponseField>

    <ResponseField name="pageSize" type="integer">
      Number of items per page
    </ResponseField>

    <ResponseField name="totalPages" type="integer">
      Total number of pages
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET "https://api.companyflow.com/leave-requests?page=1&pageSize=20&status=pending" \
    -H "Authorization: Bearer YOUR_TOKEN"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'https://api.companyflow.com/leave-requests?page=1&pageSize=20&status=pending',
    {
      headers: {
        'Authorization': 'Bearer YOUR_TOKEN'
      }
    }
  );

  const data = await response.json();
  ```

  ```python Python theme={null}
  import requests

  url = 'https://api.companyflow.com/leave-requests'
  headers = {'Authorization': 'Bearer YOUR_TOKEN'}
  params = {
      'page': 1,
      'pageSize': 20,
      'status': 'pending'
  }

  response = requests.get(url, headers=headers, params=params)
  data = response.json()
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "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
    }
  }
  ```
</ResponseExample>

## Filtering examples

<CodeGroup>
  ```bash Filter by employee theme={null}
  curl -X GET "https://api.companyflow.com/leave-requests?employeeId=987e6543-e21b-12d3-a456-426614174000" \
    -H "Authorization: Bearer YOUR_TOKEN"
  ```

  ```bash Filter by status theme={null}
  curl -X GET "https://api.companyflow.com/leave-requests?status=approved" \
    -H "Authorization: Bearer YOUR_TOKEN"
  ```

  ```bash Combined filters theme={null}
  curl -X GET "https://api.companyflow.com/leave-requests?status=pending&page=2&pageSize=50" \
    -H "Authorization: Bearer YOUR_TOKEN"
  ```
</CodeGroup>

## Use cases

<CardGroup cols={2}>
  <Card title="Manager dashboard" icon="clipboard-list">
    Retrieve all pending leave requests for team members to review and approve
  </Card>

  <Card title="Employee history" icon="calendar-days">
    View personal leave history filtered by status and date range
  </Card>

  <Card title="HR reporting" icon="chart-bar">
    Generate reports on leave usage across the organization
  </Card>

  <Card title="Team calendar" icon="users">
    Display approved leave requests for team scheduling
  </Card>
</CardGroup>

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