API Reference
Become a partner

Search calendar events

post
https://api.hibob.com/v1/timeoff/calendars/events/search

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.

Body Params

Request body for calendar event search. filters is required and must
always include a date range on /calendarEvent/startDate as a from/to
pair (other filters may be added on top). fields is optional — omit it
to return every field; limit and cursor are optional and fall back to
server-defined paging (see examples for typical payloads).

Request body for calendar event search. filters is required and must
always include a date range on /calendarEvent/startDate as a from/to
pair (other filters may be added on top). fields is optional — omit it
to return every field; limit and cursor are optional and fall back to
server-defined paging (see examples for typical payloads).

fields
array of objects | null
Defaults to /calendarEvent/id,/calendarEvent/name,/calendarEvent/startDate,/calendarEvent/endDate,/calendarEvent/eventType,/calendarEvent/siteId

List of field IDs to include in each result item (see CalendarEventFieldId
for the available field IDs — they match the keys on each item in the response).
When omitted, all available fields are returned.

fields

Field IDs that can be requested in fields on the search request and that
can appear as keys on each result item. Use these IDs to project a subset
of the response and to discover the available calendar event fields.

Field IDs that can be requested in fields on the search request and that
can appear as keys on each result item. Use these IDs to project a subset
of the response and to discover the available calendar event fields.

Field IDs that can be requested in fields on the search request and that
can appear as keys on each result item. Use these IDs to project a subset
of the response and to discover the available calendar event fields.

Field IDs that can be requested in fields on the search request and that
can appear as keys on each result item. Use these IDs to project a subset
of the response and to discover the available calendar event fields.

Field IDs that can be requested in fields on the search request and that
can appear as keys on each result item. Use these IDs to project a subset
of the response and to discover the available calendar event fields.

Field IDs that can be requested in fields on the search request and that
can appear as keys on each result item. Use these IDs to project a subset
of the response and to discover the available calendar event fields.

filters
array of objects
required
length ≥ 2
Defaults to [object Object],[object Object]

Filters to apply to the search results.

You MUST always provide a date range as exactly two filters on
/calendarEvent/startDate — one with operator from and one with
operator to. Both are mandatory; requests without this pair are
rejected with 400 Bad Request.

The inclusive number of days from the from date through the to date must be
between 1 and 366; otherwise you receive 400 with
exception.calendar.publicApi.invalidDateRange (empty or inverted range) or
exception.calendar.publicApi.dateRangeTooLong (more than 366 days).

On top of the mandatory date range you may add more optional filters.

Any other fieldId under filters (for example /calendarEvent/visibility)
is rejected with 400 and exception.calendar.publicApi.unsupportedFilterField.

Example minimal payload:
[{"fieldId":"/calendarEvent/startDate","operator":"from","values":["2024-01-01"]},
{"fieldId":"/calendarEvent/startDate","operator":"to","values":["2024-01-31"]}]

filters*
string
enum
required

Field ID to filter by.

Allowed:
string
required
length between 1 and 64

Comparison operator for this filter. The allowed values depend on the
fieldId:

  • /calendarEvent/startDate: only from or to (paired to form a
    mandatory inclusive date range — see search operation docs).
  • /calendarEvent/calendarId, /calendarEvent/siteId,
    /calendarEvent/employeeId, /calendarEvent/eventType: either
    equals (row matches when its value appears in values) or
    notEqual (row matches when its value does not appear in
    values). Both operators accept one or multiple values and are
    treated symmetrically as in / not-in.

Any other operator (for example eq, in, not_equals, neq,
not_in, gt, lt) is rejected with 400 Bad Request and key
exception.calendar.publicApi.unsupportedOperator.

values
array of strings
required

Filter values, always sent as JSON strings.

  • For date filters (/calendarEvent/startDate with operator from or to):
    provide exactly one ISO 8601 calendar date string YYYY-MM-DD
    (e.g. "2024-01-31") — no time-of-day, no timezone offset. The paired mandatory
    from/to range on startDate must cover at most 366 inclusive days.
  • For /calendarEvent/siteId: provide one or more site IDs as strings. Use the
    company sites list endpoint to discover the valid IDs for the company.
  • For /calendarEvent/calendarId: provide one or more holiday calendar IDs as
    strings. Use the holiday calendars list endpoint to discover the valid IDs
    for the company.
  • For /calendarEvent/employeeId: provide one or more Bob employee IDs as
    strings. IDs must be sent as strings even when they look numeric, so that
    large IDs are not truncated by JSON number precision in clients.
  • For enum-style filters (/calendarEvent/eventType): provide one or more
    string values from the supported list (see CalendarEventType).
values*
string
enum
required

Field ID to filter by.

Allowed:
string
required
length between 1 and 64

Comparison operator for this filter. The allowed values depend on the
fieldId:

  • /calendarEvent/startDate: only from or to (paired to form a
    mandatory inclusive date range — see search operation docs).
  • /calendarEvent/calendarId, /calendarEvent/siteId,
    /calendarEvent/employeeId, /calendarEvent/eventType: either
    equals (row matches when its value appears in values) or
    notEqual (row matches when its value does not appear in
    values). Both operators accept one or multiple values and are
    treated symmetrically as in / not-in.

Any other operator (for example eq, in, not_equals, neq,
not_in, gt, lt) is rejected with 400 Bad Request and key
exception.calendar.publicApi.unsupportedOperator.

values
array of strings
required

Filter values, always sent as JSON strings.

  • For date filters (/calendarEvent/startDate with operator from or to):
    provide exactly one ISO 8601 calendar date string YYYY-MM-DD
    (e.g. "2024-01-31") — no time-of-day, no timezone offset. The paired mandatory
    from/to range on startDate must cover at most 366 inclusive days.
  • For /calendarEvent/siteId: provide one or more site IDs as strings. Use the
    company sites list endpoint to discover the valid IDs for the company.
  • For /calendarEvent/calendarId: provide one or more holiday calendar IDs as
    strings. Use the holiday calendars list endpoint to discover the valid IDs
    for the company.
  • For /calendarEvent/employeeId: provide one or more Bob employee IDs as
    strings. IDs must be sent as strings even when they look numeric, so that
    large IDs are not truncated by JSON number precision in clients.
  • For enum-style filters (/calendarEvent/eventType): provide one or more
    string values from the supported list (see CalendarEventType).
values*
integer | null
1 to 500
Defaults to 50

Maximum number of results per page (allowed range 1–500). When omitted, the server applies its own default (often 50).

string | null

Opaque cursor from a previous response's response_metadata.next_cursor. Omit on the first request;
when present it must be a non-empty opaque token (empty string is not valid).

Responses

Updated 23 days ago

Language
Credentials
:
URL
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json

Updated 23 days ago