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

{
  "success": true,
  "data": {
    "id": "bal-001-uuid",
    "employee_id": "987e6543-e21b-12d3-a456-426614174000",
    "leave_type_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "year": 2025,
    "total_days": 22,
    "used_days": 5,
    "pending_days": 1.5,
    "available_days": 15.5,
    "carried_forward_days": 2,
    "leave_type": {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "Annual Leave",
      "code": "AL",
      "days_allowed": 20,
      "is_paid": true,
      "color_code": "#3B82F6"
    },
    "created_at": "2025-01-01T00:00:00Z",
    "updated_at": "2025-03-03T10:30:00Z"
  }
}
Retrieve detailed leave balance information for the authenticated employee for a specific leave type and year. This provides a comprehensive breakdown including total days, used days, pending days, and available days.

​
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.

​
Path Parameters

​
leave_type_id
string
required
The unique identifier of the leave type (UUID format)Example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"

​
Query Parameters

​
year
integer
required
The year to retrieve balance for (between 2020 and 2100)Example: 2025

​
Response

​
success
boolean
Indicates if the request was successful
​
data
object
Detailed leave balance object
curl -X GET "https://api.companyflow.com/leave-balance/a1b2c3d4-e5f6-7890-abcd-ef1234567890?year=2025" \
  -H "Authorization: Bearer YOUR_TOKEN"

{
  "success": true,
  "data": {
    "id": "bal-001-uuid",
    "employee_id": "987e6543-e21b-12d3-a456-426614174000",
    "leave_type_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "year": 2025,
    "total_days": 22,
    "used_days": 5,
    "pending_days": 1.5,
    "available_days": 15.5,
    "carried_forward_days": 2,
    "leave_type": {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "Annual Leave",
      "code": "AL",
      "days_allowed": 20,
      "is_paid": true,
      "color_code": "#3B82F6"
    },
    "created_at": "2025-01-01T00:00:00Z",
    "updated_at": "2025-03-03T10:30:00Z"
  }
}

​
Balance Breakdown

The response provides a complete picture of leave balance:
1

Total Days

Base allocation (e.g., 20 days) + carried forward days (e.g., 2 days) = 22 total days
2

Used Days

Days already taken through approved leave requests (e.g., 5 days)
3

Pending Days

Days requested but awaiting approval (e.g., 1.5 days)
4

Available Days

Total days - used days - pending days = 15.5 days available

​
Comparison with Check Balance

Check Balance

Returns only the available days number (quick check)

Get Balance by Type

Returns complete breakdown with all balance components

​
Use Cases

This endpoint is ideal for:
  • Detailed balance display: Show comprehensive leave status in employee portals
  • Leave request forms: Display full context before submission
  • Balance analytics: Track usage patterns and trends
  • Approval workflows: Provide complete balance information to approvers
This endpoint includes the leave type configuration (name, code, color) making it perfect for building rich UI components without additional API calls.

Build docs developers (and LLMs) love

Get started for freeTalk to us