Manage Leave Request

curl -X POST https://api.companyflow.com/leave-requests/a1b2c3d4-e5f6-7890-abcd-ef1234567890/approve \
  -H "Authorization: Bearer YOUR_TOKEN"

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();

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()

{
  "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"
  }
}

POST

leave-requests

{id}

approve

curl -X POST https://api.companyflow.com/leave-requests/a1b2c3d4-e5f6-7890-abcd-ef1234567890/approve \
  -H "Authorization: Bearer YOUR_TOKEN"

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();

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()

{
  "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"
  }
}

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

string

required

UUID of the leave request to approve

Response

boolean

Indicates if the approval was successful

object

Updated leave request with approved status

curl -X POST https://api.companyflow.com/leave-requests/a1b2c3d4-e5f6-7890-abcd-ef1234567890/approve \
  -H "Authorization: Bearer YOUR_TOKEN"

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();

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()

{
  "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"
  }
}

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

string

required

UUID of the leave request to reject

Request body

string

required

Explanation for rejecting the leave request. This will be visible to the employee.

Response

boolean

Indicates if the rejection was successful

object

Updated leave request with rejected status and rejection reason

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."
  }'

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();

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()

{
  "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"
  }
}

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

string

required

UUID of the leave request to withdraw

Response

boolean

Indicates if the withdrawal was successful

object

Updated leave request with withdrawn status

curl -X POST https://api.companyflow.com/leave-requests/a1b2c3d4-e5f6-7890-abcd-ef1234567890/withdraw \
  -H "Authorization: Bearer YOUR_TOKEN"

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();

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()

{
  "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"
  }
}

Approval workflow

Understand how leave requests move through the approval process:

Employee submits request

Leave request is created with pending status. Employee’s leave balance shows the days as “pending.”

Manager reviews

Manager can approve or reject the request. Employees can withdraw at this stage.

Approval

When approved:

Status changes to approved
Days are deducted from available balance
approvedBy and approvedAt fields are populated
Employee receives confirmation

Rejection

When rejected:

Status changes to rejected
Pending days return to available balance
rejectionReason is recorded
Employee can submit a new request

Business rules

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

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

Error responses

{
  "success": false,
  "message": "leave request is not in pending status"
}

{
  "success": false,
  "message": "you cannot approve your own leave request"
}

{
  "success": false,
  "message": "rejection reason is required"
}

{
  "success": false,
  "message": "you can only withdraw your own leave requests"
}

Authentication

Companies

Employees

Departments

Designations

Levels

Roles & Permissions

Leave Types

Leave Requests

Leave Balances

Memos

Approvals

Overview

Approve leave request

Endpoint

Authentication

Path parameters

Response

Reject leave request

Endpoint

Authentication

Path parameters

Request body

Response

Withdraw leave request

Endpoint

Authentication

Path parameters

Response

Approval workflow

Business rules

Error responses

​Overview

​Approve leave request

​Endpoint

​Authentication

​Path parameters

​Response

​Reject leave request

​Endpoint

​Authentication

​Path parameters

​Request body

​Response

​Withdraw leave request

​Endpoint

​Authentication

​Path parameters

​Response

​Approval workflow

​Business rules

​Error responses

Overview

Approve leave request

Endpoint

Authentication

Path parameters

Response

Reject leave request

Endpoint

Authentication

Path parameters

Request body

Response

Withdraw leave request

Endpoint

Authentication

Path parameters

Response

Approval workflow

Business rules

Error responses