Check Leave Balance

curl -X GET "https://api.companyflow.com/leave-balance?leaveTypeId=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=${leaveTypeId}&year=${year}`,
  {
    method: 'GET',
    headers: {
      'Authorization': 'Bearer YOUR_TOKEN'
    }
  }
);

const data = await response.json();

import requests

url = 'https://api.companyflow.com/leave-balance'
headers = {
    'Authorization': 'Bearer YOUR_TOKEN'
}
params = {
    'leaveTypeId': 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
    'year': 2025
}

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

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

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

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

{
  "success": false,
  "message": "invalid year"
}

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

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

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"

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

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

const data = await response.json();

import requests

url = 'https://api.companyflow.com/leave-balance'
headers = {
    'Authorization': 'Bearer YOUR_TOKEN'
}
params = {
    'leaveTypeId': 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
    'year': 2025
}

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

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

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

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

{
  "success": false,
  "message": "invalid year"
}

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

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

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

string

required

UUID of the leave type to check balance forExample: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"

integer

required

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

Response

boolean

Indicates if the request was successful

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"

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

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

const data = await response.json();

import requests

url = 'https://api.companyflow.com/leave-balance'
headers = {
    'Authorization': 'Bearer YOUR_TOKEN'
}
params = {
    'leaveTypeId': 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
    'year': 2025
}

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

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

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

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

{
  "success": false,
  "message": "invalid year"
}

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

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

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.

Get Balance by Type - Get detailed balance breakdown
Get Employee Balances - Get all leave 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

Authentication

Query Parameters

Response

Understanding the Balance

Use Cases

​Authentication

​Query Parameters

​Response

​Understanding the Balance

​Use Cases

​Related Endpoints

Authentication

Query Parameters

Response

Understanding the Balance

Use Cases

Related Endpoints