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

# Manage Leave Request

> Approve, reject, or withdraw leave requests

## Overview

Managers can approve or reject pending leave requests. Employees can withdraw their own pending requests. These actions update the request status and trigger balance adjustments.

## Approve leave request

Managers approve pending leave requests, which deducts the days from the employee's leave balance.

### Endpoint

`POST /leave-requests/{id}/approve`

### Authentication

Requires authentication with Bearer token. Available to:

* SuperAdmin
* HR Manager
* Manager

### Path parameters

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

### Response

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

<ResponseField name="data" type="object">
  Updated leave request with approved status
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://api.companyflow.com/leave-requests/a1b2c3d4-e5f6-7890-abcd-ef1234567890/approve \
    -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}/approve`,
    {
      method: 'POST',
      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}/approve'
  headers = {'Authorization': 'Bearer YOUR_TOKEN'}

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

<ResponseExample>
  ```json Success 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",
      "status": "approved",
      "approvedBy": "345a6789-a01d-34f5-c678-648836396222",
      "approvedAt": "2025-03-03T15:20:00Z",
      "createdAt": "2025-03-03T10:30:00Z",
      "updatedAt": "2025-03-03T15:20:00Z"
    }
  }
  ```
</ResponseExample>

***

## Reject leave request

Managers can reject pending leave requests with a mandatory rejection reason.

### Endpoint

`POST /leave-requests/{id}/reject`

### Authentication

Requires authentication with Bearer token. Available to:

* SuperAdmin
* HR Manager
* Manager

### Path parameters

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

### Request body

<ParamField body="rejectionReason" type="string" required>
  Explanation for rejecting the leave request. This will be visible to the employee.
</ParamField>

### Response

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

<ResponseField name="data" type="object">
  Updated leave request with rejected status and rejection reason
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://api.companyflow.com/leave-requests/a1b2c3d4-e5f6-7890-abcd-ef1234567890/reject \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "rejectionReason": "Team is understaffed during this period. Please request alternative dates."
    }'
  ```

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

  const response = await fetch(
    `https://api.companyflow.com/leave-requests/${leaveRequestId}/reject`,
    {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        rejectionReason: 'Team is understaffed during this period. Please request alternative dates.'
      })
    }
  );

  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}/reject'
  headers = {
      'Authorization': 'Bearer YOUR_TOKEN',
      'Content-Type': 'application/json'
  }
  payload = {
      'rejectionReason': 'Team is understaffed during this period. Please request alternative dates.'
  }

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

<ResponseExample>
  ```json Success 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",
      "status": "rejected",
      "approvedBy": "345a6789-a01d-34f5-c678-648836396222",
      "rejectionReason": "Team is understaffed during this period. Please request alternative dates.",
      "createdAt": "2025-03-03T10:30:00Z",
      "updatedAt": "2025-03-03T15:45:00Z"
    }
  }
  ```
</ResponseExample>

***

## Withdraw leave request

Employees can withdraw their own pending leave requests before manager approval.

### Endpoint

`POST /leave-requests/{id}/withdraw`

### Authentication

Requires authentication with Bearer token. Available to:

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

### Path parameters

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

### Response

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

<ResponseField name="data" type="object">
  Updated leave request with withdrawn status
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://api.companyflow.com/leave-requests/a1b2c3d4-e5f6-7890-abcd-ef1234567890/withdraw \
    -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}/withdraw`,
    {
      method: 'POST',
      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}/withdraw'
  headers = {'Authorization': 'Bearer YOUR_TOKEN'}

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

<ResponseExample>
  ```json Success 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",
      "status": "withdrawn",
      "createdAt": "2025-03-03T10:30:00Z",
      "updatedAt": "2025-03-03T16:10:00Z"
    }
  }
  ```
</ResponseExample>

***

## Approval workflow

Understand how leave requests move through the approval process:

<Steps>
  <Step title="Employee submits request">
    Leave request is created with `pending` status. Employee's leave balance shows the days as "pending."
  </Step>

  <Step title="Manager reviews">
    Manager can approve or reject the request. Employees can withdraw at this stage.
  </Step>

  <Step title="Approval">
    When approved:

    * Status changes to `approved`
    * Days are deducted from available balance
    * `approvedBy` and `approvedAt` fields are populated
    * Employee receives confirmation
  </Step>

  <Step title="Rejection">
    When rejected:

    * Status changes to `rejected`
    * Pending days return to available balance
    * `rejectionReason` is recorded
    * Employee can submit a new request
  </Step>
</Steps>

## Business rules

<Warning>
  **Important constraints**:

  * Only pending requests can be approved, rejected, or withdrawn
  * Managers cannot approve their own leave requests
  * Employees can only withdraw requests they created
  * Approved requests cannot be modified (must create a new request)
  * Rejection reason is mandatory and must be at least 10 characters
</Warning>

<Tip>
  **Best practices**:

  * Provide clear, constructive rejection reasons
  * Review leave balance before approving to avoid negative balances
  * Process requests promptly to help employees plan
  * Consider team workload and coverage when approving overlapping requests
</Tip>

## Error responses

<ResponseExample>
  ```json Invalid status theme={null}
  {
    "success": false,
    "message": "leave request is not in pending status"
  }
  ```

  ```json Unauthorized action theme={null}
  {
    "success": false,
    "message": "you cannot approve your own leave request"
  }
  ```

  ```json Missing rejection reason theme={null}
  {
    "success": false,
    "message": "rejection reason is required"
  }
  ```

  ```json Invalid employee theme={null}
  {
    "success": false,
    "message": "you can only withdraw your own leave requests"
  }
  ```
</ResponseExample>