# Developer Docs Documentation

> The Developer Docs is where you'll find comprehensive guides and documentation to help you start working with Bob as quickly as possible.

Fetch the complete documentation index at: https://apidocs.hibob.com/llms.txt. Use this file to discover all available pages before exploring further. Append .md to any documentation page URL to get its markdown version.

## API Reference: Time Off API
- [Time off requests](https://apidocs.hibob.com/reference/time-off.md): The Time off API provides access to the details of your company time off   requests and policies.
- [Submit a new time off request.](https://apidocs.hibob.com/reference/post_timeoff-employees-id-requests.md): Submits a new time off request.<br /> <br />Time off requests can be of the listed types in the body params section below.<br /> <br />Each request type requires different parameters in the body params. Select the type in the body params section to view the expected fields. <br /><br>**Testing Note:**<br/> To test each type of request:<br /> 1. Open the relevant request type in the body params section.<br /> 2. In the test widget on the right, click "Request Example" to open the menu, and select the request type you want to send. <br /> 3. Update values and send.<br /> <br>**Important testing disclaimer:** Changing the request type example does not automatically switch the parameters. First, select the request schema, and then select the equivalent request in the "Request Example" to avoid inconsistencies in the example fields.
- [Get the details of an existing time off request.](https://apidocs.hibob.com/reference/get_timeoff-employees-id-requests-requestid.md): Retrieve the detailed info about an existing time off request.<br> <br>  <b>Possible time off request types:</b> <ul>   <li><b>days</b>: the request is for X days.</li>   <li>     <b>hours</b>: the request is for X hours during the requested day     (supported only for policy types measured in hours).   </li>   <li>     <b>portionOnRange</b>: the request is for every morning or every afternoon     during the requested days.   </li>   <li>     <b>hoursOnRange</b>: the request is for X hours every day during the     requested days.   </li>   <li>     <b>differentDayDurations</b>: the request is for a different amount of     hours on each requested day.   </li>   <li>     <b>specificHoursDayDurations</b>: the request is for specific hours per day.   </li>   <li>     <b>differentSpecificHoursDayDurations</b>: the request is for different     specific hours or portions on each day.   </li>   <li>     <b>percentageOnRange</b>: the request is for X percent of every day during     the requested days.   </li>   <li><b>openEnded</b>: the request does not have an end date yet.</li> </ul> Each request type is represented by a separate schema with the relevant fields. <p><b>Daily durations and cost:</b>This endpoint returns a full daily duration and cost breakdown for <b>all request types</b> when <code>includeDailyDurations=true</code> is provided.</p> <p><b>Permissions required</b>: Please refer to the main <a href="https://apidocs.hibob.com/reference/time-off#required-permissions">Time off API Required Permissions</a> page. </p>
- [Cancel an existing time off request](https://apidocs.hibob.com/reference/delete_timeoff-employees-id-requests-requestid.md): Cancels an existing time off request.<br /> <br /> **Permissions required**: Please refer to the main <a href="https://apidocs.hibob.com/reference/time-off#required-permissions">Time off API Required Permissions</a> page.
- [Get time off requests changes](https://apidocs.hibob.com/reference/get_timeoff-requests-changes.md): Returns an array of all changes made to time off requests within a specified date range. Each item in the array includes: the time off request details at the time of the change, and the type of change, such as `created` or `deleted`. Optionally, requests that were changed to status `pending` can also be included.  <br /><br /> **Notes:**  <p> <ul> <li>The results are filtered by **the date the change has occurred** (when the request was created or updated), not the start/end date of the time off request itself. </li>         <li>Each change reflects a snapshot of the time off request's status **at the time of the change**, and may not reflect the current status. </li> </ul></p> <p><strong>Durations and cost:</strong></p> <ul>   <li>     This endpoint returns daily durations only for requests that use day-by-day duration configurations, including:     <code>DifferentDayDurations</code>, <code>specificHoursDayDurations</code>, <code>differentSpecificHoursDayDurations</code>.   </li>   <li>These durations do not include a daily cost breakdown.</li>   <li>     All requests return <code>totalCost</code>, which represents the amount deducted from the balance for the whole request.   </li>   <li>     To retrieve the cost per day, use <strong><a href="https://apidocs.hibob.com/reference/get_timeoff-employees-id-requests-requestid">Get the details of an existing time off request.</a></strong> with     <code>includeDailyDurations=true</code>.   </li> </ul> <p><strong>Permissions required</strong>: Please refer to the main <a href="https://apidocs.hibob.com/reference/time-off#required-permissions">Time off API Required Permissions</a> page.</p>
- [Read a list of who's out of the office.](https://apidocs.hibob.com/reference/get_timeoff-whosout.md): Returns time off information for a given date range, only for the users the Service User can access.<br /><br />  <b>Possible time off request types:</b> <ul>   <li><b>days</b>: the request is for X days.</li>   <li>     <b>hours</b>: the request is for X hours during the requested day     (supported only for policy types measured in hours).   </li>   <li>     <b>portionOnRange</b>: the request is for every morning or every afternoon     during the requested days.   </li>   <li>     <b>hoursOnRange</b>: the request is for X hours every day during the     requested days.   </li>   <li>     <b>differentDayDurations</b>: the request is for a different amount of     hours on each requested day.   </li>   <li>     <b>specificHoursDayDurations</b>: the request is for specific hours per day.   </li>   <li>     <b>differentSpecificHoursDayDurations</b>: the request is for different     specific hours or portions on each day.   </li>   <li>     <b>percentageOnRange</b>: the request is for X percent of every day during     the requested days.   </li>   <li><b>openEnded</b>: the request does not have an end date yet.</li> </ul> Each request type is represented by a separate schema with the relevant fields. <p><strong>Durations and cost:</strong></p> <ul>   <li>     This endpoint returns daily durations only for requests that use day-by-day duration configurations, including:     <code>DifferentDayDurations</code>, <code>specificHoursDayDurations</code>, <code>differentSpecificHoursDayDurations</code>.   </li>   <li>These durations do not include a daily cost breakdown.</li>   <li>     All requests return <code>totalCost</code>, which represents the amount deducted from the balance for the whole request.   </li>   <li>     To retrieve the cost per day, use <strong><a href="https://apidocs.hibob.com/reference/get_timeoff-employees-id-requests-requestid">Get the details of an existing time off request.</a></strong> with     <code>includeDailyDurations=true</code>.   </li> </ul> <p><b>Notes:</b></p> <ul>   <li><b>Only active users</b> are included in the response.</li>   <li>     <b>Permissions</b>: Follow the     <a href="https://apidocs.hibob.com/reference/time-off#required-permissions">       Time off API Required Permissions     </a>     instructions to ensure the service user has the required permissions.   </li>   <li>     <b>Parameters</b>: The data returned is subject to the parameters used and     the permissions granted to the service user. Make sure the relevant     permissions are set when using the <code>includePrivate</code> and     <code>includePending</code> flags.   </li> </ul>
- [Read a list of who's out of the office today or on the specified date.](https://apidocs.hibob.com/reference/get_timeoff-outtoday.md): Returns the list of people that have a time off request today or on the specified date, only for the users the Service User can access.<br /><br /> <b>Possible time off request types (<code>requestRangeType</code>):</b> <ul>   <li><b>days</b>: the request is for X full days.</li>   <li>     <b>hours</b>: the request is for X hours during the requested day     (supported only for policy types measured in hours).   </li>   <li>     <b>portionOnRange</b>: the request is for every morning or every afternoon     during the requested days.   </li>   <li>     <b>hoursOnRange</b>: the request is for X hours every day during the     requested days.   </li>   <li>     <b>differentDayDurations</b>: the request is for a different number of     hours on each requested day.   </li>   <li>     <b>specificHoursDayDurations</b>: the request is for specific hours per day.   </li>   <li>     <b>differentSpecificHoursDayDurations</b>: the request is for different     specific hours or portions on each day.   </li>   <li>     <b>percentageOnRange</b>: the request is for X percent of every day during     the requested days.   </li>   <li><b>openEnded</b>: the request does not have an end date yet.</li> </ul> Each request type is represented by a separate schema with the relevant fields. <p><strong>Durations and cost:</strong></p> <ul>   <li>     This endpoint returns daily durations only for requests that use day-by-day duration configurations, including:     <code>DifferentDayDurations</code>, <code>specificHoursDayDurations</code>, <code>differentSpecificHoursDayDurations</code>.   </li>   <li>These durations do not include a daily cost breakdown.</li>   <li>     All requests return <code>totalCost</code>, which represents the amount deducted from the balance for the whole request.   </li>   <li>     To retrieve the cost per day, use <strong><a href="https://apidocs.hibob.com/reference/get_timeoff-employees-id-requests-requestid">Get the details of an existing time off request.</a></strong> with     <code>includeDailyDurations=true</code>.   </li> </ul> <p><b>Notes:</b></p> <ul> <li><b>Permissions</b>: Follow the <a href="https://apidocs.hibob.com/reference/time-off#required-permissions">Time off API Required Permissions</a> instructions to ensure the service user has the required permissions. </li> <li><b>Parameters</b>: The data returned is also subject to parameters and the permissions granted to the Service User. Make sure you set the relevant permissions when using the 'includePending' flag.</li> </ul>
- [Time off balance](https://apidocs.hibob.com/reference/time-off-balance.md)
- [Get the balance for a given employee](https://apidocs.hibob.com/reference/get_timeoff-employees-id-balance.md): Retrieve the balance for a given employee, for a given policy type, as of a given date.<br /> <br /> **Permissions required**: Please refer to the main <a href="https://apidocs.hibob.com/reference/time-off#required-permissions">Time off API Required Permissions</a> page.
- [Create a balance adjustment.](https://apidocs.hibob.com/reference/post_timeoff-employees-id-adjustments.md): Create a balance adjustment for a given employee for a given effective date.<br /> <br /> **Permissions required**: Please refer to the main <a href="https://apidocs.hibob.com/reference/time-off#required-permissions">Time off API Required Permissions</a> page.
- [Time off policies](https://apidocs.hibob.com/reference/time-off-policies.md)
- [Get Policy type reason codes](https://apidocs.hibob.com/reference/get_timeoff-policy-types-policytype-reason-codes.md): Get list of reason codes for a given policy type.<br /> <br /> **Permissions required**: Please refer to the main <a href="https://apidocs.hibob.com/reference/time-off#required-permissions">Time off API Required Permissions</a> page.
- [Add a list of reason codes for a given policy type.](https://apidocs.hibob.com/reference/post_timeoff-policy-types-policytype-reason-codes.md): Add a list of reason codes for a given policy type.<br /><b>Supported user types:</b> Service. <br /> **Permissions required**: Please refer to the main <a href="https://apidocs.hibob.com/reference/time-off#required-permissions">Time off API Required Permissions</a> page.
- [Get Policy type details](https://apidocs.hibob.com/reference/get_timeoff-policy-types-policytype.md): Get details about a given policy type.<br /> <br /> **Permissions required**: Please refer to the main <a href="https://apidocs.hibob.com/reference/time-off#required-permissions">Time off API Required Permissions</a> page.<br /><br />
- [Get all policy types names.](https://apidocs.hibob.com/reference/get_timeoff-policy-types.md): Get a list of all policy type names.<br /> <br /> **Permissions required**: Please refer to the main <a href="https://apidocs.hibob.com/reference/time-off#required-permissions">Time off API Required Permissions</a> page.
- [Get Policy details.](https://apidocs.hibob.com/reference/get_timeoff-policies.md): Get details about a given policy.<br /> <br /> **Permissions required**: Please refer to the main <a href="https://apidocs.hibob.com/reference/time-off#required-permissions">Time off API Required Permissions</a> page.
- [Get a list of policy names for a given policy type.](https://apidocs.hibob.com/reference/get_timeoff-policies-names.md): Get a list of policy names for the user's defined policy type.<br /> <br /> **Permissions required**: Please refer to the main <a href="https://apidocs.hibob.com/reference/time-off#required-permissions">Time off API Required Permissions</a> page.
- [Calendar events](https://apidocs.hibob.com/reference/calendar-events.md)
- [Search calendar events](https://apidocs.hibob.com/reference/post_timeoff-calendars-events-search.md): Read company-wide holidays and closures for a date range. Use with Search employee calendars to resolve which calendar applies to each employee before fetching events.
- [Search Employee Calendars](https://apidocs.hibob.com/reference/post_timeoff-calendars-employees-search.md): Resolves which holiday calendar applies to each employee in a single bulk call.  Each employee's effective calendar is computed server-side using the canonical resolution rule (matches Bob's product behaviour):  1. **Employment override** — if `payroll.employment.calendarId` is set on the    employee's employment record **and** that calendar currently exists in the    company, it is returned with `source = employment`. 2. **Site default** — otherwise, the calendar assigned to the employee's site    is returned with `source = site`. 3. **None** — if neither layer supplies a calendar (no override and the site    has no calendar configured, or the employee has no site), the item is    returned with `source = none` and `calendarId` / `calendarName` set to `null`.  **Missing employees:** Employee IDs that don't exist in the caller's company are silently dropped from `items` (the request does **not** fail). Diff the requested IDs against the returned `employeeId`s to detect unknowns.  **OAuth scopes (app-user):** `timeoff.calendars:write` AND `employee_data:read`.  **IAM permission:** `Settings / Calendars / Manage` (company-scoped).
- [Time off Webhooks](https://apidocs.hibob.com/reference/time-off-webhooks.md): Receive notifications about Time off requests
- [Time off request requested](https://apidocs.hibob.com/reference/post_webhook_timeoff-request-requested.md): Triggered when submitting a time off request.  Use the **getApi** URL in the payload to retrieve the full request details. When using the getApi URL immediately after this event, the status in the response will be **approved** if the request was auto-approved, or **pending** if it is awaiting approval.  In the right panel, open **Examples** and select **Payload Example** to see a real payload.
- [Time off request approved](https://apidocs.hibob.com/reference/post_webhook_timeoff-request-approved.md): Triggered when approving a time off request.  For auto-approved requests, two events are sent in sequence: **requested** then **approved**.  In the right panel, open **Examples** and select **Payload Example** to see a real payload.
- [Time off request declined](https://apidocs.hibob.com/reference/post_webhook_timeoff-request-declined.md): Triggered when declining a time off request.  When using the **getApi** URL to retrieve details of a declined request, the status in the response will be **disapproved** (not "declined").  In the right panel, open **Examples** and select **Payload Example** to see a real payload.
- [Time off request cancelled](https://apidocs.hibob.com/reference/post_webhook_timeoff-request-cancelled.md): Triggered when cancelling a time off request.  In the right panel, open **Examples** and select **Payload Example** to see a real payload.
- [Time off request deleted](https://apidocs.hibob.com/reference/post_webhook_timeoff-request-deleted.md): Triggered when deleting a time off request.  In the right panel, open **Examples** and select **Payload Example** to see a real payload.
- [Time off request updated](https://apidocs.hibob.com/reference/post_webhook_timeoff-request-updated.md): Triggered when updating a time off request.  For date or time changes (hard-update), a new request replaces the existing one. The payload then includes **originalRequestId** (the very first request before any modifications) and **previousRequestId** (the most recently replaced request).  In the right panel, open **Examples** and select **Payload Example** to see a real payload.
- [Time off request created from import](https://apidocs.hibob.com/reference/post_webhook_timeoff-request-imported.md): Triggered when importing a time off request.  Imported requests are always approved by default. When using the **getApi** URL immediately after this event, the status in the response will be **approved**.  In the right panel, open **Examples** and select **Payload Example** to see a real payload.
- [Set end date to a time off request](https://apidocs.hibob.com/reference/post_webhook_timeoff-request-set-end-date.md): Triggered when setting the end date of an open-ended time off request.  In the right panel, open **Examples** and select **Payload Example** to see a real payload.