Search Calendar Events

Calendar events are company-wide holidays and closures (and similar events) that affect work schedules and time off. Use this API to read those events and keep Bob's external calendars in sync.

Each event is tied to a calendarId and siteId. To see which calendars and sites exist in your company (and their IDs), call the Get a specific company list by name endpoint with listName = calendar or site.

Events for a specific employee

To get the events that apply to a specific employee, you need to find out the calendar linked to the employee. The employee uses their site's default holiday calendar unless a calendar is set on the employment table.

Read the following fields with the Search employee by ID endpoint (POST /v1/people/{identifier}): payroll.employment.calendarId and work.siteId.

Then fetch the employee's assigned calendar events:

• If payroll.employment.calendarId is null — filter by /calendarEvent/siteId using work.siteId.
• If payroll.employment.calendarId is set — filter by /calendarEvent/calendarId using that value.

Start date range span: The mandatory from / to pair on /calendarEvent/startDate must describe at most 366 calendar days inclusive (both endpoints count). If the span is longer, the API returns 400 Bad Request with key exception.calendar.publicApi.dateRangeTooLong. For multi-year exports, run several searches (for example one per calendar year or successive 366-day windows) and merge results client-side.

When a filter uses a fieldId that is not supported for search (for example /calendarEvent/visibility), the API returns 400 with key exception.calendar.publicApi.unsupportedFilterField and the rejected path(s) in args.

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

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