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
date_from	string (date)	Keep only records overlapping the period
date_to	string (date)	Keep only records overlapping the period

date_from and date_to are independent - you may pass either one alone. A record is kept when its own period overlaps the requested one, so a leave that starts before date_from and ends inside the period is still returned. Passing date_from later than date_to returns 422.

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],
  "date_from": "2026-01-01",
  "date_to": "2026-12-31"
}

---

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

---

Employee time-off days

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

Returns the individual dates on which employees are on time off within the requested period. Multi-day leaves are expanded into separate days and clipped to the period, so you do not have to intersect intervals yourself.

Only occupied dates are returned. Free days, weekends and public holidays are not included, and part-time schedules are not taken into account - a day that is absent from the response simply has no leave booked on it.

Request parameters:

Field	Type	Description
date_from	string (date)	Start of the period (required)
date_to	string (date)	End of the period (required)
employee_ids	array[integer]	Filter by employee IDs
category_ids	array[integer]	Filter by time-off category IDs
department_ids	array[integer]	Filter by departments
team_ids	array[integer]	Filter by teams
division_ids	array[integer]	Filter by divisions
location_ids	array[integer]	Filter by locations

The period must not exceed 366 days, and date_from must not be later than date_to; otherwise the request returns 422.

Response fields (per employee):

Field	Type	Description
employee_id	integer	Employee ID
days	array	Days the employee is on time off, ascending

days[]:

Field	Type	Description
date	string (date)	The date the employee is on time off
time_off_category_id	integer	Category of that leave - join it with GET /api/v1/time-off/categories
is_pending	boolean	true while the request is still awaiting approval

Request example:

{
  "date_from": "2026-05-01",
  "date_to": "2026-05-07",
  "department_ids": [5]
}

Response example:

[
  {
    "employee_id": 123,
    "days": [
      { "date": "2026-05-04", "time_off_category_id": 3, "is_pending": false },
      { "date": "2026-05-05", "time_off_category_id": 3, "is_pending": false }
    ]
  }
]

Employees with no leave in the period come back with an empty days array, which is how you tell “available all period” apart from “not visible to this token”.

Note: is_pending: true means the leave is booked but not approved yet, so it may still be rejected. Treat such days as occupied only if your scenario should respect unapproved requests.

Requires permission access_to_leave_timeline=edit. Employees the token has no access to are omitted from the response rather than causing an error, so an empty list may mean the service account lacks the permission.

Passing category_ids also narrows the set of employees: those without leave of the requested categories drop out of the response entirely.

---

Public holidays

Holiday calendars hold public holidays, moved working days and compensation days off. Every employee gets a calendar from the location, department and division of the current position. All three methods require permission manage_holidays=edit.

Get holiday calendars

GET /api/v1/calendar-holidays

Returns every calendar of the company: id, title and country (id, title, or null).

Get holiday dates for a period

POST /api/v1/calendar-holidays/dates/search

Field	Type	Description
date_from	string (date)	Start of the period, inclusive (required)
date_to	string (date)	End of the period, inclusive (required)
calendar_holiday_ids	array[integer]	Calendars to read; empty or omitted returns all calendars

The period is limited to 366 days, and date_from must not be later than date_to - otherwise 422.

[
  {
    "id": 3051,
    "calendar_holiday_id": 4,
    "date": "2026-01-01",
    "title": "New Year's Day",
    "type": "non_working"
  }
]

type	Meaning
non_working	Public holiday, a day off
working	Working day moved onto a weekend
compensated	Day off moved from a public holiday that fell on a weekend

Get the calendar of each employee

POST /api/v1/calendar-holidays/employees/search

Field	Type	Description
employee_ids	array[integer]	Employees to resolve; omitted returns all employees
page_number	integer	Page number, starts at 1
page_size	integer	Page size, 1-500, default 20

Each item returns employee_id and calendar_holiday_id. calendar_holiday_id is null when no calendar applies to the employee.

The calendar is resolved from the current position and is not historical: after a relocation, past dates are resolved by the new calendar.

---

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.

---

Scenario: who is away on a given date

Goal: build a calendar or schedule that knows when a person is on leave.

1. Get categories (once, cache the result) to resolve time_off_category_id into a title:

   GET /api/v1/time-off/categories

2. Fetch the occupied days for the whole team in one request:

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

   Pass the period and, optionally, department_ids or employee_ids.

3. Look up a specific date in the returned days array. A date that is not there has no leave booked on it.

4. Skip public holidays if the calendar needs them: resolve each employee’s calendar with POST /api/v1/calendar-holidays/employees/search and read its dates with POST /api/v1/calendar-holidays/dates/search. See Public holidays.