Request Leave

Submit a new leave request for approval

POST /leave-requests

cURL

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

Response

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

Show LeaveRequest properties

id · string

Unique identifier for the leave request

employeeId · string

UUID of the employee who submitted the request

leaveTypeId · string

UUID of the leave type

startDate · string

Leave start date (ISO 8601 format)

endDate · string

Leave end date (ISO 8601 format)

daysRequested · number

Number of days requested

reason · string

Reason for leave

attachmentUrl · string

URL of the attached document (if provided)

status · string

Current status: pending, approved, rejected, cancelled, or withdrawn

currentStep · integer

Current approval workflow step

approvedBy · string

UUID of the approver (null if not yet approved)

approvedAt · string

Approval timestamp (null if not yet approved)

rejectionReason · string

Reason for rejection (empty if not rejected)

createdAt · string

Request creation timestamp

updatedAt · string

Last update timestamp

cURL

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

Response

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

Annual Leave

Standard paid vacation time allocated to employees annually. Typically allows carry-forward of unused days.

Sick Leave

Paid time off for medical reasons. May require medical documentation if configured in the leave type settings.

Unpaid Leave

Time off without pay. No balance deduction required.

Maternity/Paternity Leave

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

Insufficient balance

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