Get Employee Leave Balances

curl -X GET "https://api.companyflow.com/employees/987e6543-e21b-12d3-a456-426614174000/leave-balances?year=2025" \
  -H "Authorization: Bearer YOUR_TOKEN"

const employeeId = '987e6543-e21b-12d3-a456-426614174000';
const year = 2025;

const response = await fetch(
  `https://api.companyflow.com/employees/${employeeId}/leave-balances?year=${year}`,
  {
    method: 'GET',
    headers: {
      'Authorization': 'Bearer YOUR_TOKEN'
    }
  }
);

const data = await response.json();

import requests

employee_id = '987e6543-e21b-12d3-a456-426614174000'
url = f'https://api.companyflow.com/employees/{employee_id}/leave-balances'
headers = {
    'Authorization': 'Bearer YOUR_TOKEN'
}
params = {
    'year': 2025
}

response = requests.get(url, headers=headers, params=params)
data = response.json()

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

{
  "success": false,
  "message": "invalid employee id"
}

{
  "success": false,
  "message": "year is required"
}

{
  "success": false,
  "message": "unauthorized"
}

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"

const employeeId = '987e6543-e21b-12d3-a456-426614174000';
const year = 2025;

const response = await fetch(
  `https://api.companyflow.com/employees/${employeeId}/leave-balances?year=${year}`,
  {
    method: 'GET',
    headers: {
      'Authorization': 'Bearer YOUR_TOKEN'
    }
  }
);

const data = await response.json();

import requests

employee_id = '987e6543-e21b-12d3-a456-426614174000'
url = f'https://api.companyflow.com/employees/{employee_id}/leave-balances'
headers = {
    'Authorization': 'Bearer YOUR_TOKEN'
}
params = {
    'year': 2025
}

response = requests.get(url, headers=headers, params=params)
data = response.json()

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

{
  "success": false,
  "message": "invalid employee id"
}

{
  "success": false,
  "message": "year is required"
}

{
  "success": false,
  "message": "unauthorized"
}

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

string

required

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

Query Parameters

integer

required

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

Response

boolean

Indicates if the request was successful

array

Array of leave balance objects for each leave type

Show LeaveBalance properties

string

Unique identifier for this leave balance record

string

UUID of the employee

string

UUID of the leave type

integer

The year this balance applies to

number

Total days allocated for this leave type (including carry forward)

number

Days already taken (approved leave)

number

Days with pending approval

number

Days available to request (total - used - pending)

number

Days carried forward from previous year

object

Associated leave type information

Show LeaveType properties

string

Leave type ID

string

Leave type name

string

Leave type code

string

Hex color code

string

ISO 8601 timestamp

string

ISO 8601 timestamp

curl -X GET "https://api.companyflow.com/employees/987e6543-e21b-12d3-a456-426614174000/leave-balances?year=2025" \
  -H "Authorization: Bearer YOUR_TOKEN"

const employeeId = '987e6543-e21b-12d3-a456-426614174000';
const year = 2025;

const response = await fetch(
  `https://api.companyflow.com/employees/${employeeId}/leave-balances?year=${year}`,
  {
    method: 'GET',
    headers: {
      'Authorization': 'Bearer YOUR_TOKEN'
    }
  }
);

const data = await response.json();

import requests

employee_id = '987e6543-e21b-12d3-a456-426614174000'
url = f'https://api.companyflow.com/employees/{employee_id}/leave-balances'
headers = {
    'Authorization': 'Bearer YOUR_TOKEN'
}
params = {
    'year': 2025
}

response = requests.get(url, headers=headers, params=params)
data = response.json()

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

{
  "success": false,
  "message": "invalid employee id"
}

{
  "success": false,
  "message": "year is required"
}

{
  "success": false,
  "message": "unauthorized"
}

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.

Check Balance - Quick balance check for current user
Get Balance by Type - Detailed balance for specific leave type
List Leave Types - View all available leave types

Authentication

Companies

Employees

Departments

Designations

Levels

Roles & Permissions

Leave Types

Leave Requests

Leave Balances

Memos

Approvals

Get Employee Leave Balances

Authentication

Path Parameters

Query Parameters

Response

Understanding Balance Fields

Use Cases

​Authentication

​Path Parameters

​Query Parameters

​Response

​Understanding Balance Fields

​Use Cases

​Related Endpoints

Authentication

Path Parameters

Query Parameters

Response

Understanding Balance Fields

Use Cases

Related Endpoints