Get Balance by Type

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

const leaveTypeId = 'a1b2c3d4-e5f6-7890-abcd-ef1234567890';
const year = 2025;

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

const data = await response.json();

import requests

leave_type_id = 'a1b2c3d4-e5f6-7890-abcd-ef1234567890'
url = f'https://api.companyflow.com/leave-balance/{leave_type_id}'
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",
      "days_allowed": 20,
      "is_paid": true,
      "color_code": "#3B82F6"
    },
    "created_at": "2025-01-01T00:00:00Z",
    "updated_at": "2025-03-03T10:30:00Z"
  }
}

{
  "success": false,
  "message": "invalid leave type id"
}

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

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

{
  "success": false,
  "message": "internal server error"
}

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"

const leaveTypeId = 'a1b2c3d4-e5f6-7890-abcd-ef1234567890';
const year = 2025;

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

const data = await response.json();

import requests

leave_type_id = 'a1b2c3d4-e5f6-7890-abcd-ef1234567890'
url = f'https://api.companyflow.com/leave-balance/{leave_type_id}'
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",
      "days_allowed": 20,
      "is_paid": true,
      "color_code": "#3B82F6"
    },
    "created_at": "2025-01-01T00:00:00Z",
    "updated_at": "2025-03-03T10:30:00Z"
  }
}

{
  "success": false,
  "message": "invalid leave type id"
}

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

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

{
  "success": false,
  "message": "internal server error"
}

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

string

required

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

Query Parameters

integer

required

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

Response

boolean

Indicates if the request was successful

object

Detailed leave balance object

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

number

Base days allowed per year

boolean

Whether this is paid leave

string

Hex color code

string

ISO 8601 timestamp

string

ISO 8601 timestamp

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

const leaveTypeId = 'a1b2c3d4-e5f6-7890-abcd-ef1234567890';
const year = 2025;

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

const data = await response.json();

import requests

leave_type_id = 'a1b2c3d4-e5f6-7890-abcd-ef1234567890'
url = f'https://api.companyflow.com/leave-balance/{leave_type_id}'
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",
      "days_allowed": 20,
      "is_paid": true,
      "color_code": "#3B82F6"
    },
    "created_at": "2025-01-01T00:00:00Z",
    "updated_at": "2025-03-03T10:30:00Z"
  }
}

{
  "success": false,
  "message": "invalid leave type id"
}

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

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

{
  "success": false,
  "message": "internal server error"
}

Balance Breakdown

The response provides a complete picture of leave balance:

Total Days

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

Used Days

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

Pending Days

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

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)

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.

Check Balance - Quick available days check
Get Employee Balances - All balances for an employee
Request Leave - Submit a new leave request

Authentication

Companies

Employees

Departments

Designations

Levels

Roles & Permissions

Leave Types

Leave Requests

Leave Balances

Memos

Approvals

Get Balance by Type

Authentication

Path Parameters

Query Parameters

Response

Balance Breakdown

Comparison with Check Balance

Check Balance