Explore Time off API

Understand the basic concepts of time off requests and policies in Bob

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:

Use casePublic API endpointComments
Manage Time off requestsSubmit a new time off request.
Get the details of the existing time off request.
Cancel an existing time off request.
Get all new/deleted time off requests since the specified date.
Submit, read, and cancel time off requests.
Identifier: Employee ID and Policy type name.
See who's outRead a list of who's out of the office.
Read a list of who's out of the office today or on the specified date.
Read who's out of the office (i.e., has time off request) by dates.
Get policy type and Policy metadataGet Policy type details
Get all policy types names
Get Policy type reason codes
Add reason codes to a policy type.

Get Policy details.
Get a list of policy names for a given policy type.
Read policy type details and manage their reason codes list and linked policies.

identifiers: Policy type name and Policy name.

Note: Policy details include details from the policy types, such as ‘unit’.
Adjust balanceCreate a balance adjustment.

Get the balance for a given policy type and employee.
Read the employee's balance and create a balance adjustment for an employee.
Identifiers: Employee ID and Policy type name

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