Sign in

v1

latestOpenAPI 3.1.1Proprietary2026-07-26184406877.9 KB
Calendar events

Search Employee Calendars

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).

post/timeoff/calendars/employees/search

Request body

fieldsEmployeeCalendarFieldId[] nullable

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.

limitinteger nullable

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

cursorstring nullable

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).

Response

Success