--- 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. Returns time off information for a given date range, only for the users the Service User can access.

Possible time off request types: 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/whosout": { "get": { "operationId": "get_timeoff-whosout", "tags": [ "Time off requests" ], "summary": "Read a list of who's out of the office.", "description": "Returns time off information for a given date range, only for the users the Service User can access.

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

Durations and cost:

\n

Notes:

", "parameters": [ { "name": "from", "in": "query", "description": "Start period date", "required": true, "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "description": "End period date", "required": true, "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": "includePending", "in": "query", "description": "Include Pending Requests", "schema": { "type": "boolean", "default": false } }, { "name": "includeWorkingRequests", "in": "query", "description": "Determines whether to include requests linked to “working” policy types, such as Work From Home (WFH) or business travel. These requests are reported as time off but do not represent actual leave.
", "schema": { "type": "boolean", "default": true } } ], "responses": { "200": { "description": "Time off requests as seen by the logged in user for a given date range.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TimeOffWhosoutResponse" } } } }, "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" } } } ] }, "TimeOffWhosoutBase": { "title": "Who's out item (base)", "type": "object", "properties": { "requestId": { "type": "integer", "format": "int64", "description": "The backend ID of the request." }, "employeeId": { "type": "string", "description": "Employee ID.", "format": "uuid" }, "employeeDisplayName": { "type": "string", "description": "Employee display name." }, "policyType": { "type": "string", "description": "Request policy type, e.g. Holiday, Sick or any defined custom type." }, "policyTypeDisplayName": { "type": "string", "description": "Display name for the policy type. This will be translated based on the locale.\n" }, "status": { "type": "string", "description": "Request status. This can be either Approved or Pending." }, "visibility": { "allOf": [ { "$ref": "#/components/schemas/GetTimeoffRequestBase/properties/visibility" } ] } } }, "TimeOffWhosoutHours": { "title": "Who's out (hours)", "allOf": [ { "$ref": "#/components/schemas/TimeOffWhosoutBase" }, { "type": "object", "properties": { "date": { "type": "string", "description": "Date of the time off\n", "format": "date" }, "hoursOnDate": { "type": "number", "description": "The time off duration in hours for the date (relevant for request using the hours type).\n" }, "minutes": { "type": "integer", "description": "Relevant for request using the hours type.\n" }, "type": { "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" ] } } } ] }, "TimeOffWhosoutDays": { "title": "Who's out (days)", "allOf": [ { "$ref": "#/components/schemas/TimeOffWhosoutBase" }, { "type": "object", "properties": { "startDate": { "type": "string", "description": "Date of the first day of the time off.\n", "format": "date" }, "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" }, "endDate": { "type": "string", "description": "Date of the last day of the time off (may be null for open ended requests).\n", "format": "date" }, "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" }, "type": { "type": "string", "description": "The type of request - days is when the request is for X days.
\n", "enum": [ "days" ] } } } ] }, "TimeOffWhosoutPortionOnRange": { "title": "Who's out (portionOnRange)", "allOf": [ { "$ref": "#/components/schemas/TimeOffWhosoutBase" }, { "type": "object", "properties": { "startDate": { "type": "string", "description": "Date of the first day of the time off.\n", "format": "date" }, "endDate": { "type": "string", "description": "Date of the last day of the time off.\n", "format": "date" }, "dayPortion": { "type": "string", "description": "What portion of the request's days is included - morning or afternoon.\n" }, "type": { "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" ] } } } ] }, "TimeOffWhosoutHoursOnRange": { "title": "Who's out (hoursOnRange)", "allOf": [ { "$ref": "#/components/schemas/TimeOffWhosoutBase" }, { "type": "object", "properties": { "startDate": { "type": "string", "description": "Date of the first day of the time off.\n", "format": "date" }, "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 day in the request.\n" }, "type": { "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" ] } } } ] }, "TimeOffWhosoutDifferentDayDurations": { "title": "Who's out (differentDayDurations)", "allOf": [ { "$ref": "#/components/schemas/TimeOffWhosoutBase" }, { "type": "object", "properties": { "startDate": { "type": "string", "description": "Date of the first day of the time off.\n", "format": "date" }, "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" } } } }, "type": { "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" ] } } } ] }, "TimeOffWhosoutSpecificHoursDayDurations": { "title": "Who's out (specificHoursDayDurations)", "allOf": [ { "$ref": "#/components/schemas/TimeOffWhosoutBase" }, { "type": "object", "properties": { "startDate": { "type": "string", "description": "Date of the first day of the time off.\n", "format": "date" }, "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" ] } } } }, "required": [ "date", "dayDuration" ] } }, "type": { "type": "string", "description": "The type of request - specificHoursDayDurations is when the request is for specific hours per day.
\n", "enum": [ "specificHoursDayDurations" ] } } } ] }, "TimeOffWhosoutDifferentSpecificHoursDayDurations": { "title": "Who's out (differentSpecificHoursDayDurations)", "allOf": [ { "$ref": "#/components/schemas/TimeOffWhosoutBase" }, { "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" ] } }, "type": { "type": "string", "enum": [ "differentSpecificHoursDayDurations" ] } } } ] }, "TimeOffWhosoutPercentageOnRange": { "title": "Who's out (percentageOnRange)", "allOf": [ { "$ref": "#/components/schemas/TimeOffWhosoutBase" }, { "type": "object", "properties": { "startDate": { "type": "string", "description": "Date of the first day of the time off.\n", "format": "date" }, "endDate": { "type": "string", "description": "Date of the last day of the time off (may be null for open ended requests).\n", "format": "date" }, "percentageOfDay": { "type": "integer", "description": "The percent of the day requested. \n" }, "type": { "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" ] } } } ] }, "TimeOffWhosoutOpenEnded": { "title": "Who's out (openEnded)", "allOf": [ { "$ref": "#/components/schemas/TimeOffWhosoutBase" }, { "type": "object", "properties": { "startDate": { "type": "string", "format": "date", "description": "Date of the first day of the time off." }, "endDate": { "type": [ "string", "null" ], "format": "date", "description": "Date of the last day of the time off (may be null for open-ended requests)." }, "startPortion": { "type": "string", "description": "What portion of the first day is included - all_day, morning or afternoon (relevant for requests using the `days`-like types).\n" }, "endPortion": { "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" }, "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" }, "type": { "type": "string", "description": "The type of request - openEnded is when the request doesn't have an end date yet.\n", "enum": [ "openEnded" ] } } } ] }, "TimeOffWhosout": { "title": "Who's out item", "oneOf": [ { "$ref": "#/components/schemas/TimeOffWhosoutDays" }, { "$ref": "#/components/schemas/TimeOffWhosoutHours" }, { "$ref": "#/components/schemas/TimeOffWhosoutPortionOnRange" }, { "$ref": "#/components/schemas/TimeOffWhosoutHoursOnRange" }, { "$ref": "#/components/schemas/TimeOffWhosoutDifferentDayDurations" }, { "$ref": "#/components/schemas/TimeOffWhosoutSpecificHoursDayDurations" }, { "$ref": "#/components/schemas/TimeOffWhosoutDifferentSpecificHoursDayDurations" }, { "$ref": "#/components/schemas/TimeOffWhosoutPercentageOnRange" }, { "$ref": "#/components/schemas/TimeOffWhosoutOpenEnded" } ], "discriminator": { "propertyName": "type", "mapping": { "days": "#/components/schemas/TimeOffWhosoutDays", "hours": "#/components/schemas/TimeOffWhosoutHours", "portionOnRange": "#/components/schemas/TimeOffWhosoutPortionOnRange", "hoursOnRange": "#/components/schemas/TimeOffWhosoutHoursOnRange", "differentDayDurations": "#/components/schemas/TimeOffWhosoutDifferentDayDurations", "specificHoursDayDurations": "#/components/schemas/TimeOffWhosoutSpecificHoursDayDurations", "differentSpecificHoursDayDurations": "#/components/schemas/TimeOffWhosoutDifferentSpecificHoursDayDurations", "percentageOnRange": "#/components/schemas/TimeOffWhosoutPercentageOnRange", "openEnded": "#/components/schemas/TimeOffWhosoutOpenEnded" } } }, "TimeOffWhosoutResponse": { "title": "Who's out response", "description": "Array of time off requests; each item’s shape depends on its `type`.", "type": "object", "properties": { "outs": { "type": "array", "items": { "$ref": "#/components/schemas/TimeOffWhosout" } } }, "required": [ "outs" ], "example": { "outs": [ { "date": "2025-08-04", "policyTypeDisplayName": "Holiday", "visibility": "Public", "requestId": 42016823, "minutes": 30, "policyType": "type6", "employeeId": "2911111434173677987", "employeeDisplayName": "TestRequest User", "hoursOnDate": 5, "type": "hours", "status": "approved" }, { "policyTypeDisplayName": "Holiday", "visibility": "Public", "endDate": "2025-08-06", "requestId": 42016838, "policyType": "type43", "startPortion": "all_day", "employeeId": "2911111434173677987", "employeeDisplayName": "TestRequest User", "endPortion": "morning", "type": "days", "startDate": "2025-08-05", "status": "approved" }, { "policyTypeDisplayName": "Holiday", "visibility": "Public", "endDate": "2025-08-12", "requestId": 42016862, "policyType": "type44", "employeeId": "2911111434173677987", "employeeDisplayName": "TestRequest User", "durations": [ { "date": "2025-08-11", "dayDuration": { "hours": 5, "minutes": 0, "dayDurationType": "hoursAndMinutesDayDuration" } }, { "date": "2025-08-12", "dayDuration": { "hours": 1, "minutes": 30, "dayDurationType": "hoursAndMinutesDayDuration" } } ], "type": "differentDayDurations", "startDate": "2025-08-11", "status": "approved" }, { "policyTypeDisplayName": "Holiday", "visibility": "Public", "endDate": "2025-08-14", "requestId": 42016894, "policyType": "type45", "employeeId": "2911111434173677987", "employeeDisplayName": "TestRequest User", "type": "portionOnRange", "startDate": "2025-08-13", "dayPortion": "morning", "status": "approved" }, { "policyTypeDisplayName": "Holiday", "visibility": "Public", "endDate": "2025-08-19", "requestId": 42017566, "policyType": "type46", "dailyHours": 2, "employeeId": "2911111434173677987", "employeeDisplayName": "TestRequest User", "type": "hoursOnRange", "startDate": "2025-08-18", "status": "approved" }, { "policyTypeDisplayName": "Holiday", "visibility": "Public", "endDate": "2025-08-29", "requestId": 42017666, "policyType": "type51", "timeZone": "Europe/London", "employeeId": "2911111434173677987", "employeeDisplayName": "TestRequest User", "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" } } ], "type": "specificHoursDayDurations", "startDate": "2025-08-28", "status": "approved" }, { "policyTypeDisplayName": "Holiday", "visibility": "Public", "endDate": "2025-08-31", "requestId": 42017707, "policyType": "type52", "timeZone": "Europe/London", "employeeId": "2911111434173677987", "employeeDisplayName": "TestRequest User", "type": "differentSpecificHoursDayDurations", "startDate": "2025-08-28", "status": "approved", "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", "endDate": "2025-08-03", "requestId": 42017704, "policyType": "type48", "percentageOfDay": 23, "employeeId": "2911111434173677987", "employeeDisplayName": "TestRequest User", "type": "percentageOnRange", "startDate": "2025-08-01", "status": "approved" }, { "policyTypeDisplayName": "Holiday", "visibility": "Public", "requestId": 42017706, "policyType": "type48", "employeeId": "2911111434173677987", "employeeDisplayName": "TestRequest User", "type": "openEnded", "startDate": "2025-08-31", "endDate": null, "timeZone": "Europe/London", "startPortion": "afternoon", "endPortion": null, "status": "approved" } ] } }, "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." } } } } ```