Overview

The Time Off module in Bob enables employees to manage their time off balances and submit requests for various types of leave, such as vacation days or sick leave.

The Time Off API provides programmatic access to time off policies, requests, and balances. It allows you to:
Retrieve time off requests for employees.

• Submit new Time off requests.
• Check who is on vacation on a specific date.
• Adjust time off balances and more.

Common use cases for the Time Off API include integrating with calendars or extracting time off data to meet payroll integration requirements.

The Time off API in Bob includes:

• Time off Policy types
• Time off Policies
• Time off Requests
• Time off Balance
• Time off Balance adjustments

Key concepts

Each policy belongs to a Policy Type (e.g., Sick, Holiday, Time Off in Lieu), and an employee can have one policy per type. The Policy Type may include Reason Codes, defining valid reasons for time-off requests.

Policy type
A policy type defines the type of leave that people may request. Common policy types for employees include Holiday/Vacation, Sick, Parental Leave, Compassionate Leave, and Unpaid Leave.

Policy
A policy is a set of rules, values, and validations that govern the specific regulations enforced. Each policy is linked to a policy type, and each employee can be connected to a single policy of each type.

Policy visibility
The policy’s visibility can be public, public with a custom name, or private. For example, A customer may have a policy type called "Sick" but due to privacy regulations (such as GDPR), may choose to show it to the public as "Out of office"

When using the Public API, the visibility will affect how you see the time off requests in the results based on the permissions assigned to the service user.

Reason codes
Each policy type can be linked to a list of possible reason codes, which defines specific reasons fir taking leave. This is typically used for Sick leave policy types and can include reason codes such as Headache, Mental health day, or Accident at work.

When using the Public API, you can read the existing reason codes and add new reason codes to a policy type.

Balance
The balance is the amount of leave that will be available for the employee at the end of the cycle. The balance can be affected by 3 sources:

• Accrual: Periodic additions to the time off balance.
• Time off requests: Requests posted by people.
• Balance adjustments: Manual adjustments made by managers to the employee's balance.

The Public API allows an employee's balance to be read for a specific policy type and date.

To learn more, see Manage and view attendance balance.
To learn about other Time off components, see the Time off glossary.

Balance adjustment
Adjusting time off means adding or reducing time from the balance for a particular employee (e.g., if someone worked on the weekend, we can give them time off in lieu). Balance adjustments can be made manually from the app or the Public API. Each adjustment is linked to a specific policy type.

Time off requests
The Request Time Off API is the equivalent of Bob's Request Time Off option.

Employees can request various types of time off requests, based on:

• Unit: Days or Hours.
• Portion: Day, Half-day (Morning/Afternoon)
• Amount of days: Day or Date range.
• Duration type: Number of hours or Between specific hours.

The Public API Time off requests types include:

• Amount of days
• Amount of hours for a specific date
• Different hours per day for a date range
• Same portion per day for a date range
• Same hours per day for a date range
• Specific hours per day for a date range

Note: You can only request time off for a single day or a consecutive date range.

Required permissions

Before accessing time off data, ensure the service user has permission to access the relevant information, just as you would when assigning permissions to a user in Bob.

See Time off permissions reference guide.

Time off endpoints

The Time off Public API serves the following use cases:

To learn more, see Time off reference.

Time off webhooks

Bob allows you to subscribe to system events by providing a Webhook URL as a listener. When an event occurs, Bob will call this listener and send details in the event's payload.

Each Webhook event sends information specific to the event, and the listener can then make an API call to retrieve additional data as needed for further context.

Time off Webhook events include the following events:

• Approved
• Declined
• Cancelled
• Deleted
• Updated
• Submitted
• Created from import

A common use case for subscribing to time off events is integrating with scheduling systems and notifying the system when a new time off request is approved.

To learn more, see Time off Webhook events.

Related resources

• Time off API reference
• Manage and view attendance balance.
• Time off glossary.
• Rate limiting.
• Getting started with Bob API.