> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kombo.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Create and read absences

> Learn how properly utilize the Absence functionality.

The Time Off endpoints unify the reading, creating and deleting of absences
across all supported HRIS integrations.
This document describes what to look out for when using these endpoints.

## Basics

When dealing with absences, there are three relevant concepts:

* **Absences** are time-spans when an employee is absent. They are
  specific to an employee and are at minimum characterized by a `start_date` and
  an `end_date`.
* **Absence types** define what kind of absences an employee can request. They
  have a name and can have additional properties, such as whether absences of this
  type are in hours or days. An example absence type is 'Vacation'.
* **Time off balances** (often called vacation or holiday accounts) represent the balance a specific employee has for
  a particular absence type. For example, an employee with a balance of 15 days for the
  absence type 'Vacation' can request 15 days of vacation. At that point, the
  balance will be reduced to 0 and no more 'Vacation' absences can be created.

## Absence Types in Detail

Absence types have to be submitted when creating an absence. They hold useful
information about the absence type and are supported by almost all HRIS systems.

## Time Off Balances in Detail

Some instances might have dozens of absence types and usually an individual
employee is restricted to only a few. You can find out which absence types are
available for a specific employee by retrieving
[the time off balance](/hris/v1/get-time-off-balances) for that employee. If the
absence type has an associated time off balance for a given employee, and the
balance is greater than 0, then the employee can request an absence of that type.

<Note>
  Not all tools support [time off balances](/hris/v1/get-time-off-balances). If
  they are not supported by a tool, expect all absence types to be available for
  all employees.
</Note>

## Explaining absence type properties

Each absence type has a few fields that specify how absences of its type work.
Let's review them:

### `half_days_supported`

Some systems support half days (i.e. the ability to request half a day, e.g.,
'Wednesday morning' or 'Wednesday afternoon' off). If this is the case, you can
specify whether you want to use half days or not when creating an absence.

### `exact_times_supported`

Some systems support exact times. If this is the case, you can specify
a start and end time for your absence.

### How do these properties interact?

In many systems these `half_days_supported` and `exact_times_supported` are
independent of each other.

For example, if the absence type supports half-days, it doesn't necessarily mean
that exact times are supported. As many HRIS don't offer these kinds of
guarantees, we can't offer them either.

## Creating Absences

<Note>
  Some HRIS apply additional validation rules to requested absences, for example
  they might not allow you to create an absence that starts on a weekend. In
  these cases we will either return an error message that explains the problem
  or we return the error message from the HRIS system.
</Note>

When creating an absence, you have to specify the following parameters:

### `employee_id`

The ID of the employee for whom you want to create the absence.

### `absence_type_id`

The ID of the absence type you want to use.

### `start_date` and `end_date`

This defines the duration of the absence. These fields have the `YYYY-MM-DD`
format.

### `start_half_day` and `end_half_day`

If the absence type supports half days, you can specify whether you want to
use half days or not. If you don't want to use half days, you can omit these
parameters.

### `start_time` and `end_time`

If the absence type supports exact times, you can specify the start and end
time of the absence. If you don't want to use exact times, you can omit these
parameters.

### `amount` and `unit`

These parameter define the amount of time that the absence will count as
with regards to the time off balance of an employee. This
feature is only available for few HRIS systems. We recommend not using it
unless there is no alternative.

## Reading absences

### How should I interpret half days when building, e.g., a calendar UI?

We recommend displaying half-days as 4.5 hour blocks based on the typical start
and end time of your customer's workday, assuming a typical 8-hour workday with
one hour of lunch break.

If your customers are based in different timezones or
a single customer may have offices within different time zones, we
recommend trying to infer the time zone based on the office location (either
based on the associated [legal entity](/hris/v1/get-employees#:~:text=%227E2gyuv6TmvtByzBxW9Sxt53%22%2C-,%22legal_entity_id%22,-%3A%20%22xB32bied320csBSsl3XWdlw33%22) or the [work
location](/hris/v1/get-employees#:~:text=%7D%0A%20%20%20%20%20%20%20%20%5D%2C-,%22work_location%22,-%3A%20%7B%0A%20%20%20%20%20%20%20%20%20%20%22id)
of an employee).
It is not possible to tell at what exact time the half-day starts - you
need to make an assumption based on your business context.