Skip to main content
GET
/
leave-balance
curl -X GET "https://api.companyflow.com/leave-balance?leaveTypeId=a1b2c3d4-e5f6-7890-abcd-ef1234567890&year=2025" \
  -H "Authorization: Bearer YOUR_TOKEN"

{
  "success": true,
  "data": 15.5
}
Check the available leave balance for the authenticated employee for a specific leave type and year. This endpoint returns the number of available days that can be requested.

​
Authentication

Requires authentication with Bearer token. Available to:
  • Employee
  • Manager
This endpoint automatically uses the employee ID from the JWT token, so employees can only check their own balance.

​
Query Parameters

​
leaveTypeId
string
required
UUID of the leave type to check balance forExample: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
​
year
integer
required
The year to check balance for (between 2020 and 2100)Example: 2025

​
Response

​
success
boolean
Indicates if the request was successful
​
data
number
Available leave days remaining (can include decimal values for half days)Example: 15.5
curl -X GET "https://api.companyflow.com/leave-balance?leaveTypeId=a1b2c3d4-e5f6-7890-abcd-ef1234567890&year=2025" \
  -H "Authorization: Bearer YOUR_TOKEN"

{
  "success": true,
  "data": 15.5
}

​
Understanding the Balance

The returned balance represents:
  • Total allocated days for the year
  • Minus days already taken (approved leave)
  • Minus days pending approval
  • Plus any carried forward days from the previous year
Half-day leave is supported, so the balance can include decimal values like 15.5 (15 and a half days remaining).

​
Use Cases

This endpoint is typically used:
  • Before submitting a leave request to verify sufficient balance
  • In employee self-service portals to display available leave
  • In mobile apps for quick balance checks
  • When planning future leave requests
For a more detailed breakdown including total days, used days, and pending days, use the Get Balance by Type endpoint instead.

Build docs developers (and LLMs) love

Get started for freeTalk to us