Time Off

The /api/v1/time-off endpoint group lets you read the organization’s leave policy configuration, the accrual/usage history for each employee, and their current balance as of any date.

Get all time-off categories

GET /api/v1/time-off/categories

Returns all time-off policies/categories configured for the organization.

Response fields (per category):

Field	Type	Description
id	integer	Category ID
title	string	Name
description	string	Description
category_type	string	Type: manual, accrues_time, flexible
paid_type	string	Paid/unpaid classification
period_track_type	string	Tracking unit: hours or days
emoji	string	Emoji icon
color	string	Color
policies_count	integer	Number of attached policies
is_archived	boolean	Whether the category is archived
is_parental_leave	boolean	Whether this is a parental leave category

Response example:

[
  {
    "id": 3,
    "title": "Annual Paid Leave",
    "category_type": "accrues_time",
    "paid_type": "paid",
    "period_track_type": "days",
    "policies_count": 2,
    "is_archived": false,
    "is_parental_leave": false
  }
]

---

Employee time-off history

POST /api/v1/time-off/logs/search

Returns a paginated list of leave records - accruals, usages, expirations, and adjustments.

Request parameters:

Field	Type	Description
employee_id	integer	Employee ID (required)
page_number	integer	Page number
category_ids	array[integer]	Filter by category IDs
action_types	array[string]	Types: accrual, used, expired, adjustment
request_statuses	array[string]	Filter by approval request statuses

Response fields (per record):

Each record contains two objects: time_off_log and, when a request exists, approval_request_details.

time_off_log:

Field	Type	Description
id	integer	Record ID
date_adjustment	string (date)	Adjustment date
employee_id	integer	Employee ID
category	object	Time-off category
balance	string	Balance change
action	string	Action type
balance_type	string	Balance type
date_from	string	Leave period start
date_to	string	Leave period end
date_expire	string	Accrual expiration date
comment	string	Comment
files	array	Attached files

approval_request_details (when a request exists):

Field	Type	Description
id	integer	Request ID
type	string	Request type
status	string	Request status
confirmations	array	List of approvals
datetime_created_at	string	Creation timestamp

Request example:

{
  "employee_id": 123,
  "page_number": 1,
  "action_types": ["used", "accrual"],
  "category_ids": [3, 5]
}

---

Employee time-off balance on a date

POST /api/v1/time-off/employee/balance

Returns the balance for all time-off categories the employee is enrolled in, as of the specified date.

Request parameters:

Field	Type	Description
employee_id	integer	Employee ID (required)
date_balance	string (date)	Date for which to retrieve the balance (required)

Response fields (per category):

Field	Type	Description
id	integer	Category ID
title	string	Category name
category_type	string	Category type
period_track_type	string	Tracking unit
balance.available_balance	string	Available balance
balance.total_booked_amount	string	Booked amount (approved requests)
is_archived	boolean	Whether the category is archived

Request example:

{
  "employee_id": 123,
  "date_balance": "2024-06-30"
}

Response example:

[
  {
    "id": 3,
    "title": "Annual Paid Leave",
    "category_type": "accrues_time",
    "period_track_type": "days",
    "balance": {
      "available_balance": "12.5",
      "total_booked_amount": "3.0"
    },
    "is_archived": false
  }
]

---

Typical integration scenario

Goal: periodically sync leave data with a payroll system.

1. Get categories (once, cache the result):

   GET /api/v1/time-off/categories

2. Fetch history for the period for each employee:

   POST /api/v1/time-off/logs/search

   Filter by action_types: ["used", "accrual"] and the relevant category_ids.

3. Get the current balance as of the end of the pay period:

   POST /api/v1/time-off/employee/balance

   Pass date_balance as the cutoff date.

Tip: use date_adjustment from time_off_log for incremental sync - only fetch records with an adjustment date later than your last successful sync.