The Time off API provides access to the details of your company 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 private policy | 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 and cancel people's requests that haven't been approved yet | Some endpoints require that you also set a '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 | This is required only when fetching 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 |
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.