Getting started

Before you start explore the Time off API to understand how the Public API supports time-off workflows and how to access Time off requests and policies

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.

Time off requests are always linked to a policy. Each policy can have different visibility settings:

Public
Public with Custom name
Private

Private policy requests

Retrieving private requests: Service users with permission to view private requests can retrieve requests made under a private policy type and, for public ones, the policy's original name. Service users without permissions on the other hand, will not see requests made under a private policy type at all, and for public ones, they will see the Custom name, if one is defined.
Request visibilty: The request data includes a visibilityproperty which reflects the visibility of the policy the request is based on. Possible visibility values: 'Public', 'Private' or 'Custom name'.

For more details about visibility settings, see Set up a time off policy > Step 7: Request > Step 12: Visibility.

To access time off requests and policies via the API, ensure the following permissions are set:

Data type / Method	Permission	Comment
Get Requests	People's Data > Time off > See who's out today > See who's out	For all endpoints that fetch request details need to have this permission
Private requests	People's Data > Time off > See who's out today > See who’s out because of a private policy or policies with a custom name	Some endpoints require that you also set a `includePrivate` parameter to true to retrieve private requests
Pending requests	People's Data > Time off > Requests > Create, edit all fields, and cancel people's requests that haven't been approved yet	Some endpoints require that you also set the `includePending` parameter to true to retrieve pending requests
Get request by ID	People's Data > Time off> Requests > Create, edit, and cancel people's requests that haven't been approved yet	Required only when fetching a specific request by ID
Get request attachments	People's Data > Time off> Requests > Upload, edit and view attachments in people's requests	Required to access attachments when retrieving a specific request by ID
Policy Type & Policies	Features > Time off > Settings > Manage company's time off settings	Note that this is a "Features" permission
Create request	Features > Time off > Settings > Manage company's time off settings & People's Data > Time off> Requests > Create, edit, and cancel people's requests that haven't been approved yet
Time off balance	People's data > Time off > Balance > See selected people's time off and sick leave balances People's data > Time off > Balance > Adjust selected people's time off balances and bank their overtime.

To learn more about setting permissions for service users, see API Service Users.

Rate limiting

Rate limits are restrictions that our API imposes on the number of times a user can access our endpoints within a specified period of time. To learn more about rate limiting best practices, see Rate limiting.

Below is a table detailing the rate limits for each endpoint in the Time off endpoints.

Method	Endpoint	Limit per minute
POST	Submit a new time off request	20
GET	Get the details of an existing timeoff request	20
DELETE	Cancel an existing timeoff request	20
GET	Get time off request changes	50
GET	Read a list of who's out of the office	50
GET	Read a list of who's out of the office today or on the specified date	50