API Reference
Become a partner

Search Employee Calendars

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

Resolves which holiday calendar applies to each employee in a single bulk call.

Each employee's effective calendar is computed server-side using the canonical
resolution rule (matches Bob's product behaviour):

  1. Employment override — if payroll.employment.calendarId is set on the
    employee's employment record and that calendar currently exists in the
    company, it is returned with source = employment.
  2. Site default — otherwise, the calendar assigned to the employee's site
    is returned with source = site.
  3. None — if neither layer supplies a calendar (no override and the site
    has no calendar configured, or the employee has no site), the item is
    returned with source = none and calendarId / calendarName set to null.

Missing employees: Employee IDs that don't exist in the caller's company
are silently dropped from items (the request does not fail). Diff the
requested IDs against the returned employeeIds to detect unknowns.

OAuth scopes (app-user): timeoff.calendars:write AND employee_data:read.

IAM permission: Settings / Calendars / Manage (company-scoped).

Body Params

Request body for employee-calendar search. filters is required and must
always include at least one filter on /employeeCalendar/employeeId (the
batch of employees to resolve). fields is optional — omit it to return
every field; limit and cursor are optional and fall back to server
defaults (see examples for typical payloads).

Request body for employee-calendar search. filters is required and must
always include at least one filter on /employeeCalendar/employeeId (the
batch of employees to resolve). fields is optional — omit it to return
every field; limit and cursor are optional and fall back to server
defaults (see examples for typical payloads).

fields
array of objects | null
Defaults to /employeeCalendar/employeeId,/employeeCalendar/calendarId,/employeeCalendar/calendarName,/employeeCalendar/source,/employeeCalendar/siteId

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

fields
Allowed:

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

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

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

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

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

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

Filters to apply to the search.

You MUST always provide exactly one filter on /employeeCalendar/employeeId
listing the employees to resolve. The list of values is deduplicated
server-side and may contain at most 5000 employee IDs per request;
otherwise the API returns 400 with key
exception.employeeCalendar.publicApi.tooManyEmployeeIds. Only the
equals operator is supported for this filter.

On top of the mandatory employeeId filter you may add optional filters
to narrow the results. Supported filter field IDs (see
EmployeeCalendarFilterFieldId):
/employeeCalendar/employeeId, /employeeCalendar/calendarId,
/employeeCalendar/siteId, /employeeCalendar/source.

Any other fieldId under filters is rejected with 400 and key
exception.employeeCalendar.publicApi.unsupportedFilterField.

Example minimal payload:
[{"fieldId":"/employeeCalendar/employeeId","operator":"equals","values":["3001234567890123456"]}]

filters*
string
enum
required

Field ID to filter by. Must be one of the supported filter field IDs
(see EmployeeCalendarFilterFieldId).

Allowed:
string
required
length between 1 and 64

Comparison operator for this filter. Only equals is supported for
every filter field in this operation.

values
array of strings
required

Filter values, always sent as JSON strings.

Important: Some API consoles (including ReadMe "Try It") rebuild the request from YAML
examples and may drop quotes around large numeric-looking strings, which turns them into
JSON numbers and breaks this API (and can truncate snowflake-style ids past
Number.MAX_SAFE_INTEGER). If that happens, edit the JSON body so every id is a string
(e.g. "3332883884017713938").

  • For /employeeCalendar/employeeId: provide one or more employee IDs as strings.
  • For /employeeCalendar/calendarId and /employeeCalendar/siteId: provide one or more
    IDs as strings, even when they look numeric, so that large IDs are not truncated by
    JSON number precision in clients.
  • For /employeeCalendar/source: provide one or more values from EmployeeCalendarSource
    (employment, site, none).
values*
integer | null
1 to 1000
Defaults to 100

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

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 22 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 22 days ago