Skip to main content
GET
/
employees
/
{employee_id}
/
leave-balances
curl -X GET "https://api.companyflow.com/employees/987e6543-e21b-12d3-a456-426614174000/leave-balances?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",
        "color_code": "#3B82F6"
      },
      "created_at": "2025-01-01T00:00:00Z",
      "updated_at": "2025-03-03T10:30:00Z"
    },
    {
      "id": "bal-002-uuid",
      "employee_id": "987e6543-e21b-12d3-a456-426614174000",
      "leave_type_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "year": 2025,
      "total_days": 10,
      "used_days": 2,
      "pending_days": 0,
      "available_days": 8,
      "carried_forward_days": 0,
      "leave_type": {
        "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
        "name": "Sick Leave",
        "code": "SL",
        "color_code": "#EF4444"
      },
      "created_at": "2025-01-01T00:00:00Z",
      "updated_at": "2025-02-15T14:20:00Z"
    }
  ]
}
Retrieve all leave balances for an employee across all leave types for a specific year. This provides a comprehensive view of an employee’s leave allocation and usage.

​
Authentication

Requires authentication with Bearer token. Available to:
  • Super Admin
  • HR Manager
  • Employee (can view their own balances)
  • Manager (can view their team members’ balances)

​
Path Parameters

​
employee_id
string
required
The unique identifier of the employee (UUID format)Example: "987e6543-e21b-12d3-a456-426614174000"

​
Query Parameters

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

​
Response

​
success
boolean
Indicates if the request was successful
​
data
array
Array of leave balance objects for each leave type
curl -X GET "https://api.companyflow.com/employees/987e6543-e21b-12d3-a456-426614174000/leave-balances?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",
        "color_code": "#3B82F6"
      },
      "created_at": "2025-01-01T00:00:00Z",
      "updated_at": "2025-03-03T10:30:00Z"
    },
    {
      "id": "bal-002-uuid",
      "employee_id": "987e6543-e21b-12d3-a456-426614174000",
      "leave_type_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "year": 2025,
      "total_days": 10,
      "used_days": 2,
      "pending_days": 0,
      "available_days": 8,
      "carried_forward_days": 0,
      "leave_type": {
        "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
        "name": "Sick Leave",
        "code": "SL",
        "color_code": "#EF4444"
      },
      "created_at": "2025-01-01T00:00:00Z",
      "updated_at": "2025-02-15T14:20:00Z"
    }
  ]
}

​
Understanding Balance Fields

Balance Calculation:available_days = total_days - used_days - pending_daysWhere total_days includes any carried forward days from the previous year.

​
Use Cases

This endpoint is useful for:
  • HR dashboards: View comprehensive leave status for any employee
  • Manager views: Check team member leave balances before approving requests
  • Employee portals: Display personal leave overview
  • Year-end reporting: Generate annual leave usage reports
  • Leave planning: Help employees plan their leave across different types
Use this endpoint at the start of a leave request workflow to show employees all their available balances across different leave types.

Build docs developers (and LLMs) love

Get started for freeTalk to us