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

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 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, policyTypeDisplayName depends on the policy's visibility and the caller's permissions:

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

Examples

Public policy

{
  "policyTypeDisplayName": "Sick",
  "policyTypeCustomName": null,
  "visibility": "Public"
}

Custom name — caller with permission

{
  "policyTypeDisplayName": "Sick",
  "policyTypeCustomName": "Out of office",
  "visibility": "Custom name"
}

Custom name — caller without permission

{
  "policyTypeDisplayName": "Out of office",
  "policyTypeCustomName": "Out of office",
  "visibility": "Custom name"
}

Private policy — caller with permission

{
  "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:

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.