Skip to main content
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"

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

​
id
string
required
UUID of the leave request to approve

​
Response

​
success
boolean
Indicates if the approval was successful
​
data
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"

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

​
id
string
required
UUID of the leave request to reject

​
Request body

​
rejectionReason
string
required
Explanation for rejecting the leave request. This will be visible to the employee.

​
Response

​
success
boolean
Indicates if the rejection was successful
​
data
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."
  }'

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

​
id
string
required
UUID of the leave request to withdraw

​
Response

​
success
boolean
Indicates if the withdrawal was successful
​
data
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"

{
  "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:
1

Employee submits request

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

Manager reviews

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

Approval

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

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

Build docs developers (and LLMs) love

Get started for freeTalk to us