Skip to main content
POST
/
leave-requests
curl -X POST https://api.companyflow.com/leave-requests \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "leaveTypeId": "123e4567-e89b-12d3-a456-426614174000",
    "startDate": "2025-03-15",
    "endDate": "2025-03-19",
    "daysRequested": 5,
    "reason": "Family vacation",
    "attachment": ""
  }'

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

​
Overview

Employees can submit leave requests specifying the leave type, dates, and reason. The request enters the approval workflow and deducts from the employee’s available leave balance upon approval.

​
Authentication

Requires authentication with Bearer token. Available to:
  • Employee
  • Manager

​
Request body

​
leaveTypeId
string
required
UUID of the leave type (e.g., Annual Leave, Sick Leave)
​
startDate
string
required
Leave start date in YYYY-MM-DD format (e.g., “2025-02-10”)
​
endDate
string
required
Leave end date in YYYY-MM-DD format (e.g., “2025-02-15”)
​
daysRequested
number
required
Total number of leave days requested (supports half days with decimal values like 0.5)
​
reason
string
required
Explanation for the leave request
​
attachment
string
Optional attachment URL (e.g., medical certificate for sick leave)

​
Response

​
success
boolean
Indicates if the request was successful
​
data
object
The created leave request object
curl -X POST https://api.companyflow.com/leave-requests \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "leaveTypeId": "123e4567-e89b-12d3-a456-426614174000",
    "startDate": "2025-03-15",
    "endDate": "2025-03-19",
    "daysRequested": 5,
    "reason": "Family vacation",
    "attachment": ""
  }'

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

​
Leave types

Common leave types include:
Standard paid vacation time allocated to employees annually. Typically allows carry-forward of unused days.
Paid time off for medical reasons. May require medical documentation if configured in the leave type settings.
Time off without pay. No balance deduction required.
Extended leave for parents. Paid status and duration vary by company policy.

​
Validation rules

The system validates several conditions before accepting a leave request:
  • End date must be equal to or after start date
  • Employee must have sufficient available balance for the leave type
  • Dates cannot overlap with existing approved leave requests
  • Days requested must match the actual working days between start and end dates

​
Approval workflow

Once submitted, leave requests follow this workflow:
1

Pending

Request is created with status pending and awaits manager approval.
2

Review

Manager reviews the request and can either approve or reject it.
3

Final status

Request reaches final status: approved, rejected, or withdrawn (if employee cancels).
4

Balance update

If approved, the system deducts days from the employee’s leave balance.

​
Error responses

{
  "success": false,
  "message": "insufficient leave balance"
}

Build docs developers (and LLMs) love

Get started for freeTalk to us