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_dateand anend_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 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.
Not all tools support time off balances. If they are not supported by a tool, expect all absence types to be available for all employees.
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
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.
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 or the work location 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.
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_dateand anend_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 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.
Not all tools support time off balances. If they are not supported by a tool, expect all absence types to be available for all employees.
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
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.
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 or the work location 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.