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

# Get Leave Request

> Retrieve details of a specific leave request by ID

## Overview

Fetch complete details of a single leave request including approval history, attached documents, and current status.

## Authentication

Requires authentication with Bearer token. Available to:

* SuperAdmin
* HR Manager
* Manager
* Employee (own requests only)

## Path parameters

<ParamField path="id" type="string" required>
  UUID of the leave request to retrieve
</ParamField>

## Response

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

<ResponseField name="data" type="object">
  The leave request object

  <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 who submitted the request
    </ResponseField>

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

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

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

    <ResponseField name="daysRequested" type="number">
      Number of days requested (supports decimals for half days)
    </ResponseField>

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

    <ResponseField name="attachmentUrl" type="string">
      URL to attached documentation (e.g., medical certificate). Null if no attachment.
    </ResponseField>

    <ResponseField name="status" type="string">
      Current status of the request:

      * `pending` - Awaiting approval
      * `approved` - Approved by manager
      * `rejected` - Rejected by manager
      * `cancelled` - Cancelled by system
      * `withdrawn` - Withdrawn by employee
    </ResponseField>

    <ResponseField name="currentStep" type="integer">
      Current step in the approval workflow (1-based index)
    </ResponseField>

    <ResponseField name="approvedBy" type="string">
      UUID of the manager who approved the request. Null if not yet approved.
    </ResponseField>

    <ResponseField name="approvedAt" type="string">
      Timestamp when the request was approved (ISO 8601). Null if not yet approved.
    </ResponseField>

    <ResponseField name="rejectionReason" type="string">
      Explanation provided by manager if request was rejected. Empty string if not rejected.
    </ResponseField>

    <ResponseField name="createdAt" type="string">
      Timestamp when the request was created (ISO 8601)
    </ResponseField>

    <ResponseField name="updatedAt" type="string">
      Timestamp of the last update (ISO 8601)
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET https://api.companyflow.com/leave-requests/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
    -H "Authorization: Bearer YOUR_TOKEN"
  ```

  ```javascript JavaScript theme={null}
  const leaveRequestId = 'a1b2c3d4-e5f6-7890-abcd-ef1234567890';

  const response = await fetch(
    `https://api.companyflow.com/leave-requests/${leaveRequestId}`,
    {
      headers: {
        'Authorization': 'Bearer YOUR_TOKEN'
      }
    }
  );

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

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

  leave_request_id = 'a1b2c3d4-e5f6-7890-abcd-ef1234567890'
  url = f'https://api.companyflow.com/leave-requests/{leave_request_id}'
  headers = {'Authorization': 'Bearer YOUR_TOKEN'}

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

<ResponseExample>
  ```json Pending request theme={null}
  {
    "success": true,
    "data": {
      "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"
    }
  }
  ```

  ```json Approved request theme={null}
  {
    "success": true,
    "data": {
      "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"
    }
  }
  ```

  ```json Rejected request theme={null}
  {
    "success": true,
    "data": {
      "id": "c3d4e5f6-a7b8-9012-cdef-23456789012",
      "employeeId": "987e6543-e21b-12d3-a456-426614174000",
      "leaveTypeId": "123e4567-e89b-12d3-a456-426614174000",
      "startDate": "2025-04-01T00:00:00Z",
      "endDate": "2025-04-05T00:00:00Z",
      "daysRequested": 5,
      "reason": "Personal reasons",
      "attachmentUrl": null,
      "status": "rejected",
      "currentStep": 1,
      "approvedBy": "345a6789-a01d-34f5-c678-648836396222",
      "approvedAt": null,
      "rejectionReason": "Team is understaffed during this period. Please request alternative dates.",
      "createdAt": "2025-03-01T08:00:00Z",
      "updatedAt": "2025-03-02T11:45:00Z"
    }
  }
  ```
</ResponseExample>

## Status definitions

<AccordionGroup>
  <Accordion title="pending">
    Leave request has been submitted and is awaiting manager review. Employee can still withdraw the request at this stage.
  </Accordion>

  <Accordion title="approved">
    Manager has approved the request. Leave days are deducted from the employee's balance and the leave is confirmed.
  </Accordion>

  <Accordion title="rejected">
    Manager has rejected the request with a reason. No balance deduction occurs. Employee can submit a new request with different dates.
  </Accordion>

  <Accordion title="withdrawn">
    Employee has withdrawn their pending request before manager approval. No balance impact.
  </Accordion>

  <Accordion title="cancelled">
    System-cancelled due to policy changes or employee departure. Rare status for administrative purposes.
  </Accordion>
</AccordionGroup>

## Related operations

After retrieving a leave request, you may want to:

<CardGroup cols={2}>
  <Card title="Approve request" icon="check" href="/api/leaves/update">
    Approve a pending leave request (managers only)
  </Card>

  <Card title="Reject request" icon="xmark" href="/api/leaves/update">
    Reject a pending leave request with reason
  </Card>

  <Card title="Withdraw request" icon="arrow-rotate-left" href="/api/leaves/update">
    Employee can withdraw their own pending request
  </Card>

  <Card title="Check balance" icon="scale-balanced">
    View remaining leave balance for the employee
  </Card>
</CardGroup>

## Error responses

<ResponseExample>
  ```json Not found theme={null}
  {
    "success": false,
    "message": "leave request not found"
  }
  ```

  ```json Unauthorized theme={null}
  {
    "success": false,
    "message": "unauthorized access to this leave request"
  }
  ```

  ```json Invalid ID theme={null}
  {
    "success": false,
    "message": "invalid request id"
  }
  ```
</ResponseExample>