--- updatedAt: 2026-01-21T12:15:58.000Z --- Fetch the complete documentation index at: https://apidocs.hibob.com/llms.txt. Use this file to discover all available pages before exploring further. # Read a list of who's out of the office today or on the specified date. 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.

Possible time off request types (requestRangeType): Each request type is represented by a separate schema with the relevant fields.

Durations and cost:

Notes:

# OpenAPI definition ```json { "openapi": "3.1.1", "info": { "title": "Time Off API", "description": "Use Public API to access Time off requests, policies, and balances in Bob", "license": { "name": "Proprietary", "url": "https://apidocs.hibob.com/docs/api-terms-of-use" }, "contact": { "name": "Hi Bob, Inc." }, "version": "1.0.0" }, "servers": [ { "url": "https://api.hibob.com/v1", "description": "Production" }, { "url": "https://api.sandbox.hibob.com/v1", "description": "Sandbox" } ], "x-readme": { "metrics-enabled": false }, "tags": [ { "name": "Time off requests", "description": "Operations for managing time off requests" }, { "name": "Time off Webhooks", "description": "Webhook events for time off request-related operations" } ], "webhooks": { "timeoffRequestRequested": { "post": { "operationId": "post_webhook_timeoff-request-requested", "tags": [ "Time off Webhooks" ], "summary": "Time off request requested", "description": "Triggered when submitting a time off request.\n\nUse the **getApi** URL in the payload to retrieve the full request details.\nWhen 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.\n\nIn the right panel, open **Examples** and select **Payload Example** to see a real payload.\n", "parameters": [ { "name": "bob-signature", "in": "header", "required": true, "description": "Base64-encoded signature sent with each webhook request. Use it to verify that the request came from Bob. To verify webhook authenticity, see How does Bob calculate the signature.", "schema": { "type": "string", "example": "EQScIBkAtTKFW0ictgt5zzOsqIc2+xGEsM88jOdLuW4CM/a3gLEfrKV+IC5IHx0xbirzLKPIfaZjCGwzuiyI8w==" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TimeoffRequestRequestedEvent" }, "example": { "companyId": 637323, "type": "timeoff.request.requested", "triggeredBy": "3419283646526259215", "triggeredAt": "2024-10-03T09:29:00.831502", "version": "v2", "data": { "timeoffRequestId": 32832853, "employeeId": "3373576791477190995", "getApi": "https://api.hibob.com/v1/timeoff/employees/3373576791477190995/requests/32832853" } } } } }, "responses": { "200": { "description": "Webhook received successfully" }, "400": { "description": "Invalid webhook payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [] } }, "timeoffRequestApproved": { "post": { "operationId": "post_webhook_timeoff-request-approved", "tags": [ "Time off Webhooks" ], "summary": "Time off request approved", "description": "Triggered when approving a time off request.\n\nFor auto-approved requests, two events are sent in sequence: **requested** then **approved**.\n\nIn the right panel, open **Examples** and select **Payload Example** to see a real payload.\n", "parameters": [ { "name": "bob-signature", "in": "header", "required": true, "description": "Base64-encoded signature sent with each webhook request. Use it to verify that the request came from Bob. To verify webhook authenticity, see How does Bob calculate the signature.", "schema": { "type": "string", "example": "EQScIBkAtTKFW0ictgt5zzOsqIc2+xGEsM88jOdLuW4CM/a3gLEfrKV+IC5IHx0xbirzLKPIfaZjCGwzuiyI8w==" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TimeoffRequestApprovedEvent" }, "example": { "companyId": 637323, "type": "timeoff.request.approved", "triggeredBy": "3419283646526259215", "triggeredAt": "2024-10-03T09:29:00.831502", "version": "v2", "data": { "timeoffRequestId": 32832853, "employeeId": "3373576791477190995", "getApi": "https://api.hibob.com/v1/timeoff/employees/3373576791477190995/requests/32832853" } } } } }, "responses": { "200": { "description": "Webhook received successfully" }, "400": { "description": "Invalid webhook payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [] } }, "timeoffRequestDeclined": { "post": { "operationId": "post_webhook_timeoff-request-declined", "tags": [ "Time off Webhooks" ], "summary": "Time off request declined", "description": "Triggered when declining a time off request.\n\nWhen using the **getApi** URL to retrieve details of a declined request, the status in the response will be **disapproved** (not \"declined\").\n\nIn the right panel, open **Examples** and select **Payload Example** to see a real payload.\n", "parameters": [ { "name": "bob-signature", "in": "header", "required": true, "description": "Base64-encoded signature sent with each webhook request. Use it to verify that the request came from Bob. To verify webhook authenticity, see How does Bob calculate the signature.", "schema": { "type": "string", "example": "EQScIBkAtTKFW0ictgt5zzOsqIc2+xGEsM88jOdLuW4CM/a3gLEfrKV+IC5IHx0xbirzLKPIfaZjCGwzuiyI8w==" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TimeoffRequestDeclinedEvent" }, "example": { "companyId": 637323, "type": "timeoff.request.declined", "triggeredBy": "3419283646526259215", "triggeredAt": "2024-10-03T09:29:00.831502", "version": "v2", "data": { "timeoffRequestId": 32832969, "employeeId": "3332883884017713938", "getApi": "https://api.hibob.com/v1/timeoff/employees/3332883884017713938/requests/32832969" } } } } }, "responses": { "200": { "description": "Webhook received successfully" }, "400": { "description": "Invalid webhook payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [] } }, "timeoffRequestCancelled": { "post": { "operationId": "post_webhook_timeoff-request-cancelled", "tags": [ "Time off Webhooks" ], "summary": "Time off request cancelled", "description": "Triggered when cancelling a time off request.\n\nIn the right panel, open **Examples** and select **Payload Example** to see a real payload.\n", "parameters": [ { "name": "bob-signature", "in": "header", "required": true, "description": "Base64-encoded signature sent with each webhook request. Use it to verify that the request came from Bob. To verify webhook authenticity, see How does Bob calculate the signature.", "schema": { "type": "string", "example": "EQScIBkAtTKFW0ictgt5zzOsqIc2+xGEsM88jOdLuW4CM/a3gLEfrKV+IC5IHx0xbirzLKPIfaZjCGwzuiyI8w==" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TimeoffRequestCancelledEvent" }, "example": { "companyId": 636192, "type": "timeoff.request.cancelled", "triggeredBy": "3332883804594373380", "triggeredAt": "2025-01-02T11:08:26.022782", "version": "v2", "data": { "timeoffRequestId": 32809865, "employeeId": "3332883804594373380", "getApi": "https://api.hibob.com/v1/timeoff/employees/3332883804594373380/requests/32809865", "originalRequestId": null } } } } }, "responses": { "200": { "description": "Webhook received successfully" }, "400": { "description": "Invalid webhook payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [] } }, "timeoffRequestDeleted": { "post": { "operationId": "post_webhook_timeoff-request-deleted", "tags": [ "Time off Webhooks" ], "summary": "Time off request deleted", "description": "Triggered when deleting a time off request.\n\nIn the right panel, open **Examples** and select **Payload Example** to see a real payload.\n", "parameters": [ { "name": "bob-signature", "in": "header", "required": true, "description": "Base64-encoded signature sent with each webhook request. Use it to verify that the request came from Bob. To verify webhook authenticity, see How does Bob calculate the signature.", "schema": { "type": "string", "example": "EQScIBkAtTKFW0ictgt5zzOsqIc2+xGEsM88jOdLuW4CM/a3gLEfrKV+IC5IHx0xbirzLKPIfaZjCGwzuiyI8w==" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TimeoffRequestDeletedEvent" }, "example": { "companyId": 636192, "type": "timeoff.request.deleted", "triggeredBy": "3332883804594373380", "triggeredAt": "2025-01-02T11:08:26.022782", "version": "v2", "data": { "timeoffRequestId": 32809865, "employeeId": "3332883804594373380", "getApi": "https://api.hibob.com/v1/timeoff/employees/3332883804594373380/requests/32809865", "originalRequestId": null } } } } }, "responses": { "200": { "description": "Webhook received successfully" }, "400": { "description": "Invalid webhook payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [] } }, "timeoffRequestUpdated": { "post": { "operationId": "post_webhook_timeoff-request-updated", "tags": [ "Time off Webhooks" ], "summary": "Time off request updated", "description": "Triggered when updating a time off request.\n\nFor 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).\n\nIn the right panel, open **Examples** and select **Payload Example** to see a real payload.\n", "parameters": [ { "name": "bob-signature", "in": "header", "required": true, "description": "Base64-encoded signature sent with each webhook request. Use it to verify that the request came from Bob. To verify webhook authenticity, see How does Bob calculate the signature.", "schema": { "type": "string", "example": "EQScIBkAtTKFW0ictgt5zzOsqIc2+xGEsM88jOdLuW4CM/a3gLEfrKV+IC5IHx0xbirzLKPIfaZjCGwzuiyI8w==" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TimeoffRequestUpdatedEvent" }, "example": { "companyId": 636192, "type": "timeoff.request.updated", "triggeredBy": "3332883804594373380", "triggeredAt": "2025-02-18T16:15:00.218602", "version": "v2", "data": { "timeoffRequestId": 34902625, "employeeId": "3332883884017713938", "getApi": "https://api.hibob.com/v1/timeoff/employees/3332883884017713938/requests/34900183", "originalRequestId": 34615592, "previousRequestId": 34900183 } } } } }, "responses": { "200": { "description": "Webhook received successfully" }, "400": { "description": "Invalid webhook payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [] } }, "timeoffRequestImported": { "post": { "operationId": "post_webhook_timeoff-request-imported", "tags": [ "Time off Webhooks" ], "summary": "Time off request created from import", "description": "Triggered when importing a time off request.\n\nImported requests are always approved by default. When using the **getApi** URL immediately after this event, the status in the response will be **approved**.\n\nIn the right panel, open **Examples** and select **Payload Example** to see a real payload.\n", "parameters": [ { "name": "bob-signature", "in": "header", "required": true, "description": "Base64-encoded signature sent with each webhook request. Use it to verify that the request came from Bob. To verify webhook authenticity, see How does Bob calculate the signature.", "schema": { "type": "string", "example": "EQScIBkAtTKFW0ictgt5zzOsqIc2+xGEsM88jOdLuW4CM/a3gLEfrKV+IC5IHx0xbirzLKPIfaZjCGwzuiyI8w==" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TimeoffRequestImportedEvent" }, "example": { "companyId": 637323, "type": "timeoff.request.imported", "triggeredBy": "3419283646526259215", "triggeredAt": "2024-10-03T09:29:00.831502", "version": "v2", "data": { "timeoffRequestId": 24640322, "employeeId": "3052501936990322832", "getApi": "https://api.hibob.com/v1/timeoff/employees/3052501936990322832/requests/24640322" } } } } }, "responses": { "200": { "description": "Webhook received successfully" }, "400": { "description": "Invalid webhook payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [] } }, "timeoffRequestSetEndDate": { "post": { "operationId": "post_webhook_timeoff-request-set-end-date", "tags": [ "Time off Webhooks" ], "summary": "Set end date to a time off request", "description": "Triggered when setting the end date of an open-ended time off request.\n\nIn the right panel, open **Examples** and select **Payload Example** to see a real payload.\n", "parameters": [ { "name": "bob-signature", "in": "header", "required": true, "description": "Base64-encoded signature sent with each webhook request. Use it to verify that the request came from Bob. To verify webhook authenticity, see How does Bob calculate the signature.", "schema": { "type": "string", "example": "EQScIBkAtTKFW0ictgt5zzOsqIc2+xGEsM88jOdLuW4CM/a3gLEfrKV+IC5IHx0xbirzLKPIfaZjCGwzuiyI8w==" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TimeoffRequestSetEndDateEvent" }, "example": { "companyId": 637323, "type": "timeoff.request.setEndDate", "triggeredBy": "3419283646526259215", "triggeredAt": "2024-10-03T09:29:00.831502", "version": "v2", "data": { "timeoffRequestId": 32832853, "employeeId": "3373576791477190995", "getApi": "https://api.hibob.com/v1/timeoff/employees/3373576791477190995/requests/32832853" } } } } }, "responses": { "200": { "description": "Webhook received successfully" }, "400": { "description": "Invalid webhook payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [] } } }, "paths": { "/timeoff/outtoday": { "get": { "operationId": "get_timeoff-outtoday", "tags": [ "Time off requests" ], "summary": "Read a list of who's out of the office today or on the specified date.", "description": "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.

\nPossible time off request types (requestRangeType): Each request type is represented by a separate schema with the relevant fields.\n

Durations and cost:

\n

Notes:

", "parameters": [ { "name": "today", "in": "query", "description": "Date to report out of the office. If not specified, the date at UTC at the time of the request is used.", "schema": { "type": "string", "format": "date" } }, { "name": "includeHourly", "in": "query", "description": "Include Hourly Requests", "schema": { "type": "boolean", "default": false } }, { "name": "includePrivate", "in": "query", "description": "This flag determines whether to return private requests and which name to display in the policyTypeDisplayName field.
", "schema": { "type": "boolean", "default": false } }, { "name": "siteId", "in": "query", "description": "The employee's site ID", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "The list of people who have taken time off, as seen by the logged in user.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TimeOffOutTodayResponse" } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "security": [ { "Basic": [] }, { "Bearer": [] } ] } } }, "components": { "schemas": { "WebhookEvent": { "type": "object", "description": "Base webhook event structure containing common webhook properties", "properties": { "companyId": { "type": "number", "description": "The company ID" }, "type": { "type": "string", "description": "The event type (e.g., timeoff.request.requested)" }, "triggeredBy": { "type": "string", "description": "The backend-id of the employee that triggered the event, or 'system' for system-triggered events" }, "triggeredAt": { "type": "string", "description": "The timestamp when the event occurred (ISO 8601-style string)" }, "version": { "type": "string", "description": "The webhook version (e.g., v2)" }, "data": { "type": "object", "description": "Event-specific payload; structure varies by event type" } }, "required": [ "companyId", "type", "triggeredBy", "triggeredAt", "version", "data" ] }, "TimeoffRequestRequestedEventData": { "type": "object", "description": "Data payload for timeoff.request.requested event", "properties": { "timeoffRequestId": { "type": "integer", "format": "int64", "description": "The unique identifier of the time off request" }, "employeeId": { "type": "string", "description": "The unique identifier of the employee" }, "getApi": { "type": "string", "description": "URL to retrieve the full time off request details via the API" } }, "required": [ "timeoffRequestId", "employeeId", "getApi" ] }, "TimeoffRequestApprovedEventData": { "type": "object", "description": "Data payload for timeoff.request.approved event", "properties": { "timeoffRequestId": { "type": "integer", "format": "int64", "description": "The unique identifier of the time off request" }, "employeeId": { "type": "string", "description": "The unique identifier of the employee" }, "getApi": { "type": "string", "description": "URL to retrieve the full time off request details via the API" } }, "required": [ "timeoffRequestId", "employeeId", "getApi" ] }, "TimeoffRequestDeclinedEventData": { "type": "object", "description": "Data payload for timeoff.request.declined event", "properties": { "timeoffRequestId": { "type": "integer", "format": "int64", "description": "The unique identifier of the time off request" }, "employeeId": { "type": "string", "description": "The unique identifier of the employee" }, "getApi": { "type": "string", "description": "URL to retrieve the full time off request details via the API" } }, "required": [ "timeoffRequestId", "employeeId", "getApi" ] }, "TimeoffRequestCancelledEventData": { "type": "object", "description": "Data payload for timeoff.request.cancelled event", "properties": { "timeoffRequestId": { "type": "integer", "format": "int64", "description": "The unique identifier of the time off request" }, "employeeId": { "type": "string", "description": "The unique identifier of the employee" }, "getApi": { "type": "string", "description": "URL to retrieve the full time off request details via the API" }, "originalRequestId": { "type": [ "integer", "null" ], "format": "int64", "description": "The ID of the very first request before any modifications" } }, "required": [ "timeoffRequestId", "employeeId", "getApi" ] }, "TimeoffRequestDeletedEventData": { "type": "object", "description": "Data payload for timeoff.request.deleted event", "properties": { "timeoffRequestId": { "type": "integer", "format": "int64", "description": "The unique identifier of the time off request" }, "employeeId": { "type": "string", "description": "The unique identifier of the employee" }, "getApi": { "type": "string", "description": "URL to retrieve the full time off request details via the API" }, "originalRequestId": { "type": [ "integer", "null" ], "format": "int64", "description": "The ID of the very first request before any modifications" } }, "required": [ "timeoffRequestId", "employeeId", "getApi" ] }, "TimeoffRequestUpdatedEventData": { "type": "object", "description": "Data payload for timeoff.request.updated event", "properties": { "timeoffRequestId": { "type": "integer", "format": "int64", "description": "The unique identifier of the time off request" }, "employeeId": { "type": "string", "description": "The unique identifier of the employee" }, "getApi": { "type": "string", "description": "URL to retrieve the full time off request details via the API" }, "originalRequestId": { "type": [ "integer", "null" ], "format": "int64", "description": "The ID of the very first request before any modifications" }, "previousRequestId": { "type": [ "integer", "null" ], "format": "int64", "description": "The ID of the most recently replaced request (for date/time changes)" } }, "required": [ "timeoffRequestId", "employeeId", "getApi" ] }, "TimeoffRequestImportedEventData": { "type": "object", "description": "Data payload for timeoff.request.imported event", "properties": { "timeoffRequestId": { "type": "integer", "format": "int64", "description": "The unique identifier of the time off request" }, "employeeId": { "type": "string", "description": "The unique identifier of the employee" }, "getApi": { "type": "string", "description": "URL to retrieve the full time off request details via the API" } }, "required": [ "timeoffRequestId", "employeeId", "getApi" ] }, "TimeoffRequestSetEndDateEventData": { "type": "object", "description": "Data payload for timeoff.request.setEndDate event", "properties": { "timeoffRequestId": { "type": "integer", "format": "int64", "description": "The unique identifier of the time off request" }, "employeeId": { "type": "string", "description": "The unique identifier of the employee" }, "getApi": { "type": "string", "description": "URL to retrieve the full time off request details via the API" } }, "required": [ "timeoffRequestId", "employeeId", "getApi" ] }, "TimeoffRequestRequestedEvent": { "allOf": [ { "$ref": "#/components/schemas/WebhookEvent" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "timeoff.request.requested" ], "description": "Event type for time off request submitted" }, "data": { "$ref": "#/components/schemas/TimeoffRequestRequestedEventData" } } } ] }, "TimeoffRequestApprovedEvent": { "allOf": [ { "$ref": "#/components/schemas/WebhookEvent" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "timeoff.request.approved" ], "description": "Event type for time off request approved" }, "data": { "$ref": "#/components/schemas/TimeoffRequestApprovedEventData" } } } ] }, "TimeoffRequestDeclinedEvent": { "allOf": [ { "$ref": "#/components/schemas/WebhookEvent" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "timeoff.request.declined" ], "description": "Event type for time off request declined" }, "data": { "$ref": "#/components/schemas/TimeoffRequestDeclinedEventData" } } } ] }, "TimeoffRequestCancelledEvent": { "allOf": [ { "$ref": "#/components/schemas/WebhookEvent" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "timeoff.request.cancelled" ], "description": "Event type for time off request cancelled" }, "data": { "$ref": "#/components/schemas/TimeoffRequestCancelledEventData" } } } ] }, "TimeoffRequestDeletedEvent": { "allOf": [ { "$ref": "#/components/schemas/WebhookEvent" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "timeoff.request.deleted" ], "description": "Event type for time off request deleted" }, "data": { "$ref": "#/components/schemas/TimeoffRequestDeletedEventData" } } } ] }, "TimeoffRequestUpdatedEvent": { "allOf": [ { "$ref": "#/components/schemas/WebhookEvent" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "timeoff.request.updated" ], "description": "Event type for time off request updated" }, "data": { "$ref": "#/components/schemas/TimeoffRequestUpdatedEventData" } } } ] }, "TimeoffRequestImportedEvent": { "allOf": [ { "$ref": "#/components/schemas/WebhookEvent" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "timeoff.request.imported" ], "description": "Event type for time off request created from import" }, "data": { "$ref": "#/components/schemas/TimeoffRequestImportedEventData" } } } ] }, "TimeoffRequestSetEndDateEvent": { "allOf": [ { "$ref": "#/components/schemas/WebhookEvent" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "timeoff.request.setEndDate" ], "description": "Event type for setting the end date of an open-ended time off request" }, "data": { "$ref": "#/components/schemas/TimeoffRequestSetEndDateEventData" } } } ] }, "TimeOffOutTodayBase": { "title": "Out Today item (base)", "type": "object", "properties": { "employeeId": { "type": "string", "description": "Employee ID.", "format": "uuid" }, "employeeDisplayName": { "type": "string", "description": "Employee display name." }, "employeeEmail": { "type": "string", "description": "Employee email address." }, "policyTypeDisplayName": { "type": "string", "description": "Display name of the policy type." }, "startDate": { "type": "string", "format": "date", "description": "Date of the first day of the time off.\n" }, "visibility": { "allOf": [ { "$ref": "#/components/schemas/GetTimeoffRequestBase/properties/visibility" } ] } } }, "TimeOffOutTodayDays": { "title": "Out Today (days)", "allOf": [ { "$ref": "#/components/schemas/TimeOffOutTodayBase" }, { "type": "object", "properties": { "endDate": { "type": "string", "description": "Date of the last day of the time off. May be null for open ended requests.\n", "format": "date" }, "startDatePortion": { "type": "string", "description": "What portion of the first day is included - all_day, morning or afternoon (relevant for request using the days type).\n" }, "endDatePortion": { "type": "string", "description": "What portion of the last day is included - all_day, morning or afternoon (relevant for request using the days type).\n" }, "startPortion": { "type": "string", "description": "What portion of the first day is included - all_day, morning or afternoon (relevant for request using the days type).\n" }, "endPortion": { "type": "string", "description": "What portion of the last day is included - all_day, morning or afternoon (relevant for requests using the days type).\n" }, "requestRangeType": { "type": "string", "description": "The type of request - days is when the request is for X days.
\n", "enum": [ "days" ] } } } ] }, "TimeOffOutTodayHours": { "title": "Out Today (hours)", "allOf": [ { "$ref": "#/components/schemas/TimeOffOutTodayBase" }, { "type": "object", "properties": { "hours": { "type": "integer", "description": "The time off duration in hours for the date (relevant for requests with hours type).\n" }, "minutes": { "type": "integer", "description": "Relevant for requests using the hours type." }, "requestRangeType": { "type": "string", "description": "The type of request - hours is when the request is for X hours during the day requested (supported only for policy types measured in hours).
\n", "enum": [ "hours" ] } } } ] }, "TimeOffOutTodayPortionOnRange": { "title": "Out Today (portionOnRange)", "allOf": [ { "$ref": "#/components/schemas/TimeOffOutTodayBase" }, { "type": "object", "properties": { "endDate": { "type": "string", "description": "Date of the last day of the time off. May be null for open ended requests.\n", "format": "date" }, "dayPortion": { "type": "string", "description": "What portion of the request's days is included - morning or afternoon (relevant for request using the portionOnRange type).\n" }, "requestRangeType": { "type": "string", "description": "The type of request - portionOnRange is when the request is for every morning or every afternoon during the days requested.
\n", "enum": [ "portionOnRange" ] } } } ] }, "TimeOffOutTodayHoursOnRange": { "title": "Out Today (hoursOnRange)", "allOf": [ { "$ref": "#/components/schemas/TimeOffOutTodayBase" }, { "type": "object", "properties": { "endDate": { "type": "string", "description": "Date of the last day of the time off. May be null for open ended requests.\n", "format": "date" }, "dailyHours": { "type": "number", "description": "The time off duration in hours for every request's days (relevant for requests with hoursOnRange type).\n" }, "requestRangeType": { "type": "string", "description": "The type of request - hoursOnRange is when the request is for X hours every day during the days requested.
\n", "enum": [ "hoursOnRange" ] } } } ] }, "TimeOffOutTodayDifferentDayDurations": { "title": "Out Today (differentDayDurations)", "allOf": [ { "$ref": "#/components/schemas/TimeOffOutTodayBase" }, { "type": "object", "properties": { "endDate": { "type": "string", "description": "Date of the last day of the time off. May be null for open ended requests.\n", "format": "date" }, "durations": { "type": "array", "description": "Array of durations for each day in the request. \n", "items": { "type": "object", "properties": { "date": { "type": "string", "format": "date" }, "dayDuration": { "$ref": "#/components/schemas/HoursAndMinutesDayDuration" } } } }, "requestRangeType": { "type": "string", "description": "The type of request - differentDayDurations is when the request is for a different amount of hours on each of the days requested.
\n", "enum": [ "differentDayDurations" ] } } } ] }, "TimeOffOutTodaySpecificHoursDayDurations": { "title": "Out Today (specificHoursDayDurations)", "allOf": [ { "$ref": "#/components/schemas/TimeOffOutTodayBase" }, { "type": "object", "properties": { "endDate": { "type": "string", "description": "Date of the last day of the time off. May be null for open ended requests.\n", "format": "date" }, "timeZone": { "type": "string", "description": "The calculated time zone name. The value for this fields is automatically determined based on the time zone of the employee’s assigned site.\n" }, "durations": { "type": "array", "description": "Array of durations for each day in the request. \n", "items": { "type": "object", "properties": { "date": { "type": "string", "format": "date" }, "dayDuration": { "type": "object", "properties": { "localStartTime": { "type": "string" }, "localEndTime": { "type": "string" }, "dayDurationType": { "type": "string", "enum": [ "specificHoursDayDuration" ] } } } } } }, "requestRangeType": { "type": "string", "description": "The type of request - specificHoursDayDurations is when the request is for specific hours per day.
\n", "enum": [ "specificHoursDayDurations" ] } } } ] }, "TimeOffOutTodayDifferentSpecificHoursDayDurations": { "title": "Out Today (differentSpecificHoursDayDurations)", "allOf": [ { "$ref": "#/components/schemas/TimeOffOutTodayBase" }, { "type": "object", "properties": { "startDate": { "type": "string", "format": "date", "description": "Date of the first day of the time off" }, "endDate": { "type": "string", "format": "date", "description": "Date of the last day of the time off." }, "timeZone": { "type": "string", "description": "The time zone for the time off request" }, "durations": { "type": "array", "description": "Array of day durations for the time off request", "items": { "type": "object", "properties": { "date": { "type": "string", "format": "date", "description": "The date for this duration entry" }, "dayDuration": { "description": "The duration for this specific date. Each date must include exactly one of the following types: \n", "oneOf": [ { "$ref": "#/components/schemas/SpecificHoursDayDuration" }, { "$ref": "#/components/schemas/DiffSpecHoursPortionDayDuration" } ] } }, "required": [ "date", "dayDuration" ] } }, "requestRangeType": { "type": "string", "enum": [ "differentSpecificHoursDayDurations" ] } } } ] }, "TimeOffOutTodayPercentageOnRange": { "title": "Out Today (percentageOnRange)", "allOf": [ { "$ref": "#/components/schemas/TimeOffOutTodayBase" }, { "type": "object", "properties": { "endDate": { "type": "string", "description": "Date of the last day of the time off. May be null for open ended requests.\n", "format": "date" }, "percentageOfDay": { "description": "The percentage of day requested", "type": "integer" }, "requestRangeType": { "type": "string", "description": "The type of request percentageOnRange is when the request is for X percent of every day during the days requested.\n", "enum": [ "percentageOnRange" ] } } } ] }, "TimeOffOutTodayOpenEnded": { "title": "Out Today (openEnded)", "allOf": [ { "$ref": "#/components/schemas/TimeOffOutTodayBase" }, { "type": "object", "properties": { "endDate": { "type": [ "string", "null" ], "format": "date", "description": "Date of the last day of the time off (may be null for open-ended requests).\n" }, "startDatePortion": { "type": "string", "description": "What portion of the first day is included - all_day, morning or afternoon (relevant for request using the days type).\n" }, "endDatePortion": { "type": [ "string", "null" ], "description": "What portion of the last day is included - all_day, morning or afternoon (may be null for open-ended requests).\n" }, "startPortion": { "type": "string", "description": "What portion of the first day is included - all_day, morning or afternoon (relevant for request using the days type).\n" }, "endPortion": { "type": "string", "description": "What portion of the last day is included - all_day, morning or afternoon (relevant for requests using the days type).\n" }, "timeZone": { "type": "string", "description": "The calculated time zone name. The value for this fields is automatically determined based on the time zone of the employee’s assigned site.\n" }, "requestRangeType": { "type": "string", "description": "The type of request - openEnded is when the request doesn't have an end date yet.\n", "enum": [ "openEnded" ] } } } ] }, "TimeOffOutToday": { "title": "Out Today item", "oneOf": [ { "$ref": "#/components/schemas/TimeOffOutTodayDays" }, { "$ref": "#/components/schemas/TimeOffOutTodayHours" }, { "$ref": "#/components/schemas/TimeOffOutTodayPortionOnRange" }, { "$ref": "#/components/schemas/TimeOffOutTodayHoursOnRange" }, { "$ref": "#/components/schemas/TimeOffOutTodayDifferentDayDurations" }, { "$ref": "#/components/schemas/TimeOffOutTodaySpecificHoursDayDurations" }, { "$ref": "#/components/schemas/TimeOffOutTodayDifferentSpecificHoursDayDurations" }, { "$ref": "#/components/schemas/TimeOffOutTodayPercentageOnRange" }, { "$ref": "#/components/schemas/TimeOffOutTodayOpenEnded" } ], "discriminator": { "propertyName": "requestRangeType", "mapping": { "days": "#/components/schemas/TimeOffOutTodayDays", "hours": "#/components/schemas/TimeOffOutTodayHours", "portionOnRange": "#/components/schemas/TimeOffOutTodayPortionOnRange", "hoursOnRange": "#/components/schemas/TimeOffOutTodayHoursOnRange", "differentDayDurations": "#/components/schemas/TimeOffOutTodayDifferentDayDurations", "specificHoursDayDurations": "#/components/schemas/TimeOffOutTodaySpecificHoursDayDurations", "differentSpecificHoursDayDurations": "#/components/schemas/TimeOffOutTodayDifferentSpecificHoursDayDurations", "percentageOnRange": "#/components/schemas/TimeOffOutTodayPercentageOnRange", "openEnded": "#/components/schemas/TimeOffOutTodayOpenEnded" } } }, "TimeOffOutTodayResponse": { "title": "Out Today response", "type": "object", "properties": { "outs": { "type": "array", "items": { "$ref": "#/components/schemas/TimeOffOutToday" } } }, "required": [ "outs" ], "example": { "outs": [ { "policyTypeDisplayName": "Holiday", "visibility": "Public", "employeeEmail": "joe.doe@samplebob.com", "employeeId": "2911111434173677987", "employeeDisplayName": "TestRequest User", "requestRangeType": "hours", "startDate": "2025-08-04", "hours": 5, "minutes": 30 }, { "policyTypeDisplayName": "Holiday", "visibility": "Public", "employeeEmail": "joe.doe@samplebob.com", "employeeId": "2911111434173677987", "employeeDisplayName": "TestRequest User", "requestRangeType": "days", "startDate": "2025-08-05", "endDate": "2025-08-06", "startDatePortion": "all_day", "endDatePortion": "morning" }, { "policyTypeDisplayName": "Holiday", "visibility": "Public", "employeeEmail": "joe.doe@samplebob.com", "employeeId": "2911111434173677987", "employeeDisplayName": "TestRequest User", "requestRangeType": "differentDayDurations", "startDate": "2025-08-11", "endDate": "2025-08-12", "durations": [ { "date": "2025-08-11", "dayDuration": { "hours": 5, "minutes": 0, "dayDurationType": "hoursAndMinutesDayDuration" } }, { "date": "2025-08-12", "dayDuration": { "hours": 1, "minutes": 30, "dayDurationType": "hoursAndMinutesDayDuration" } } ] }, { "policyTypeDisplayName": "Holiday", "visibility": "Public", "employeeEmail": "joe.doe@samplebob.com", "employeeId": "2911111434173677987", "employeeDisplayName": "TestRequest User", "requestRangeType": "portionOnRange", "startDate": "2025-08-13", "endDate": "2025-08-14", "dayPortion": "morning" }, { "policyTypeDisplayName": "Holiday", "visibility": "Public", "employeeEmail": "joe.doe@samplebob.com", "employeeId": "2911111434173677987", "employeeDisplayName": "TestRequest User", "requestRangeType": "hoursOnRange", "startDate": "2025-08-18", "endDate": "2025-08-19", "dailyHours": 2 }, { "policyTypeDisplayName": "Holiday", "visibility": "Public", "employeeEmail": "joe.doe@samplebob.com", "employeeId": "2911111434173677987", "employeeDisplayName": "TestRequest User", "requestRangeType": "specificHoursDayDurations", "timeZone": "Europe/London", "startDate": "2025-08-28", "endDate": "2025-08-29", "durations": [ { "date": "2025-08-28", "dayDuration": { "localStartTime": "04:00:00", "localEndTime": "05:00:00", "dayDurationType": "specificHoursDayDuration" } }, { "date": "2025-08-29", "dayDuration": { "localStartTime": "04:00:00", "localEndTime": "05:00:00", "dayDurationType": "specificHoursDayDuration" } } ] }, { "policyTypeDisplayName": "Holiday", "visibility": "Public", "employeeEmail": "joe.doe@samplebob.com", "employeeId": "2911111434173677987", "employeeDisplayName": "TestRequest User", "requestRangeType": "differentSpecificHoursDayDurations", "timeZone": "Europe/London", "startDate": "2025-08-28", "endDate": "2025-08-31", "durations": [ { "date": "2025-08-28", "dayDuration": { "dayDurationType": "specificHoursDayDuration", "localStartTime": "09:00:00", "localEndTime": "11:00:00" } }, { "date": "2025-08-29", "dayDuration": { "dayDurationType": "portionDayDuration", "portion": "vacant" } }, { "date": "2025-08-30", "dayDuration": { "dayDurationType": "specificHoursDayDuration", "localStartTime": "14:00:00", "localEndTime": "16:30:00" } }, { "date": "2025-08-31", "dayDuration": { "dayDurationType": "portionDayDuration", "portion": "all_day" } } ] }, { "policyTypeDisplayName": "Holiday", "visibility": "Public", "employeeEmail": "joe.doe@samplebob.com", "employeeId": "2911111434173677987", "employeeDisplayName": "TestRequest User", "requestRangeType": "percentageOnRange", "startDate": "2025-08-01", "endDate": "2025-08-03", "percentageOfDay": 23 }, { "policyTypeDisplayName": "Holiday", "visibility": "Public", "employeeId": "2911111434173677987", "employeeDisplayName": "TestRequest User", "employeeEmail": "user@example.com", "requestRangeType": "openEnded", "startDate": "2025-08-31", "startPortion": "afternoon", "endPortion": null, "endDate": null, "timeZone": "Europe/London", "startDatePortion": "afternoon", "endDatePortion": null } ] } }, "HoursAndMinutesDayDuration": { "type": "object", "description": "Duration in hours and minutes for a day (relevant for `differentDayDurations` type)", "required": [ "hours", "minutes", "dayDurationType" ], "properties": { "hours": { "type": "integer", "description": "Number of hours" }, "minutes": { "type": "integer", "description": "Number of minutes (must match the minimal amount of minutes in the time off policy)\n" }, "dayDurationType": { "type": "string", "enum": [ "hoursAndMinutesDayDuration" ], "description": "Type of day duration" } } }, "SpecificHoursDayDuration": { "title": "Specific hours day duration", "description": "Defines the request by exact working hours (for example, 10:00-12:00).\n", "required": [ "dayDurationType", "localStartTime", "localEndTime" ], "type": "object", "properties": { "dayDurationType": { "type": "string", "enum": [ "specificHoursDayDuration" ], "description": "The type of day duration" }, "localStartTime": { "type": "string", "format": "time", "description": "Start time of the duration" }, "localEndTime": { "type": "string", "format": "time", "description": "End time of the duration" } } }, "DiffSpecHoursPortionDayDuration": { "title": "PortionDayDuration", "description": "Defines the request as either the entire day (all_day) or no hours at all (vacant).\n", "required": [ "dayDurationType", "portion" ], "type": "object", "properties": { "dayDurationType": { "type": "string", "enum": [ "portionDayDuration" ], "description": "The type of day duration" }, "portion": { "type": "string", "enum": [ "all_day", "vacant" ], "description": "The portion of the day" } } }, "GetTimeoffRequestBase": { "title": "Time off request (base)", "type": "object", "properties": { "employeeId": { "type": "string", "format": "string", "description": "Employee ID." }, "requestId": { "type": "integer", "description": "Time Off Request ID." }, "policyTypeDisplayName": { "type": "string", "description": "The policy type name returned for this request. May contain sensitive information, such as the original policy type name for `Private` policies or when the caller has permission on `Custom name` policies. When `policyTypeCustomName` is not null and differs from this value, this field contains the original policy type name, meaning the caller has permission to see it. Learn more about policy type names and visibility." }, "createdOn": { "type": "string", "format": "date-time", "description": "The date and time the time off request was created." }, "description": { "type": [ "string", "null" ], "description": "The request description." }, "durationUnit": { "type": "string", "enum": [ "days", "hours" ], "description": "The unit used for the totalDuration and totalCost - either 'days' or 'hours'\n" }, "totalDuration": { "type": "number", "description": "The total amount of time the request covers, including regular days off such as weekends\n" }, "totalCost": { "type": "number", "description": "The amount that will be deducted from the balance" }, "status": { "type": "string", "description": "Request status. This can be approved, pending, canceled, etc." }, "hasAttachment": { "type": "boolean", "description": "Whether the request has attachments" }, "attachmentLinks": { "type": "array", "description": "Attachments with download links", "items": { "type": "object", "properties": { "filename": { "type": "string" }, "url": { "type": "string" }, "mimeType": { "type": "string" } } } }, "reasonCode": { "type": [ "string", "null" ], "description": "The reason code taken from the policy type's reason codes list. The list is available in GET /timeoff/policy-types/{policyType}/reason-codes\n" }, "policyTypeCustomName": { "type": [ "string", "null" ], "description": "The custom public-facing label when the policy's `visibility` is `Custom name`; `null` for Public and Private policies. Never contains sensitive information. Always returned regardless of caller permissions. Learn more about policy type names and visibility." }, "previousRequestId": { "type": [ "integer", "null" ], "description": "The backend-id of the previous request that was replaced when this new request was created. This occurs when the request's date or time is updated, resulting in a new time off request record.\n" }, "originalRequestId": { "type": [ "integer", "null" ], "description": "The backend-id of the very first time-off request. It remains unchanged regardless of updates that create new time off request records. It serves as the anchor for tracing the request's entire history back to its initial submission.\n" }, "approved": { "type": "boolean", "description": "Whether the request is approved (and hence publicly visible)." }, "approvedBy": { "type": [ "string", "null" ], "description": "Who approved the request" }, "approvedAt": { "type": [ "string", "null" ], "description": "When the request was approved" }, "declinedBy": { "type": [ "string", "null" ], "description": "Who declined the request" }, "declinedAt": { "type": [ "string", "null" ], "description": "When the request was declined" }, "declineReason": { "type": [ "string", "null" ], "description": "Why the request was declined" }, "visibility": { "type": "string", "description": "The request visibility either 'Public', 'Private' or 'Custom name'", "enum": [ "Public", "Private", "Custom name" ] }, "timeZoneOffset": { "type": [ "string", "null" ], "description": "Calculated time zone offset from GMT in ±HH:MM format (e.g., \"GMT -5:00\"). This field is relevant only for time-off requests which allow specifying exact start and end times (e.g., 09:00–18:00). The value is automatically calculated based on the employee's assigned site time zone.\n" } } }, "Error": { "type": "object", "properties": { "key": { "type": "string", "description": "The unique identifier of the error." }, "error": { "type": "string", "description": "A human readable error message." } } } }, "securitySchemes": { "Basic": { "type": "http", "scheme": "basic" }, "Bearer": { "type": "http", "scheme": "bearer", "bearerFormat": "OAuth 2.0", "description": "OAuth 2.0 authentication using an Access Token is available for registered partners only. Try It! does not support the full HiBob OAuth flow. You can follow these steps to complete the OAuth 2.0 flow in Postman and then paste the token here." } } } } ```