--- updatedAt: 2026-06-29T14:43:49.000Z --- Fetch the complete documentation index at: https://apidocs.hibob.com/llms.txt. Use this file to discover all available pages before exploring further. # Time off requests The Time off API provides access to the details of your company time off requests and policies. # Getting started Before you start [explore the Time off API](/docs/explore-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** 1. **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. 2. **Request visibility**: The request data includes a `visibility` property 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 12: Visibility. # Policy type names in API responses Time off request responses include three related fields: * **`policyTypeDisplayName`** — the policy type name exposed to the authenticated caller for this request. * **`policyTypeCustomName`** — the custom label configured on the policy, when one exists. * **`visibility`** — the policy's visibility setting: `Public`, `Private`, or `Custom name`. `policyTypeDisplayName` preserves existing API behavior. Its value depends on the policy's visibility, the caller's permissions, and (on supported endpoints) the `includePrivate` query parameter. `policyTypeCustomName` is always returned on endpoints that include it (currently [Get the details of an existing time off request](https://apidocs.hibob.com/reference/get_timeoff-employees-id-requests-requestid) only). That endpoint does not support `includePrivate`. When a custom label is configured, `policyTypeCustomName` contains that label regardless of caller permissions. When no custom label is configured, it is `null`. Use both name fields together with `visibility` to determine what the caller is allowed to see. For example, when `policyTypeCustomName` is not `null` and differs from `policyTypeDisplayName`, the caller has access to the underlying policy type name. ## How `policyTypeDisplayName` is determined On [Get the details of an existing time off request](https://apidocs.hibob.com/reference/get_timeoff-employees-id-requests-requestid), `policyTypeDisplayName` depends on the policy's visibility and the caller's permissions: | Visibility | Caller has permission | `policyTypeDisplayName` | | :------------ | :-------------------- | :-------------------------------------- | | `Public` | Any | Policy type name (e.g. `Sick`) | | `Custom name` | Yes | Original policy type name (e.g. `Sick`) | | `Custom name` | No | Custom label (e.g. `Out of office`) | | `Private` | Yes | Policy type name (e.g. `Sick`) | | `Private` | No | Request is not returned | On other endpoints (such as Who's out and Out today), `policyTypeDisplayName` also depends on the `includePrivate` query parameter. Set `includePrivate` to `true` to include private requests and return the original policy type name. When `includePrivate` is `false`, private requests are excluded and policies with a custom name return the custom label in `policyTypeDisplayName`. ## How `policyTypeCustomName` is determined | Visibility | `policyTypeCustomName` | | :------------ | :-------------------------------------------------------------- | | `Public` | `null` | | `Custom name` | The configured custom label (always, regardless of permissions) | | `Private` | `null` | ## Examples **Public policy** ```json { "policyTypeDisplayName": "Sick", "policyTypeCustomName": null, "visibility": "Public" } ``` **Custom name — caller with permission** ```json { "policyTypeDisplayName": "Sick", "policyTypeCustomName": "Out of office", "visibility": "Custom name" } ``` **Custom name — caller without permission** ```json { "policyTypeDisplayName": "Out of office", "policyTypeCustomName": "Out of office", "visibility": "Custom name" } ``` **Private policy — caller with permission** ```json { "policyTypeDisplayName": "Sick", "policyTypeCustomName": null, "visibility": "Private" } ``` ## Detecting what the caller can see Compare `policyTypeCustomName` and `policyTypeDisplayName`: * **`policyTypeCustomName` is `null`** — no custom label is configured (`Public` or `Private` visibility). * **Both values are equal and not `null`** — the caller sees only the custom/public-facing label; the underlying policy type name is hidden. * **Values differ** — the caller has access to the underlying policy type name in `policyTypeDisplayName`, and the employee-facing custom label is in `policyTypeCustomName`. 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.
Search calendar events Settings > Calendar > Manage company calendar Scope: `timeoff.calendars:write` If missing, the API returns 403 Forbidden with an explanation
To learn more about setting permissions for service users, see [API Service Users](https://apidocs.hibob.com/docs/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](https://apidocs.hibob.com/docs/rate-limit). 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](https://apidocs.hibob.com/reference/post_timeoff-employees-id-requests) | 20 | | GET | [Get the details of an existing timeoff request](https://apidocs.hibob.com/reference/get_timeoff-employees-id-requests-requestid) | 20 | | DELETE | [Cancel an existing timeoff request](https://apidocs.hibob.com/reference/delete_timeoff-employees-id-requests-requestid) | 20 | | GET | [Get time off request changes](https://apidocs.hibob.com/reference/get_timeoff-requests-changes) | 50 | | GET | [Read a list of who's out of the office](https://apidocs.hibob.com/reference/get_timeoff-whosout) | 50 | | GET | [Read a list of who's out of the office today or on the specified date](https://apidocs.hibob.com/reference/get_timeoff-outtoday) | 50 |