---
title: "List Calendar Events"
method: GET
path: "/api/v1/calendar-events"
tags: ["Calendar Events", "Public API"]
---

# List Calendar Events

`GET /api/v1/calendar-events`

## Request

- Base URL: `https://companySubDomain.bamboohr.com`
- URL: `https://companySubDomain.bamboohr.com/api/v1/calendar-events`
- Auth: one of:
  - HTTP basic
  - OAuth 2
    - Authorization code: `/authorize.php`
    - Token URL: `/token.php` scopes: `calendar:events`
- TypeScript: <https://skmtc.dev/bamboohr/apis/bamboohr-api/docs/api/v1/calendar-events/get.ts> (a function with typed inputs; its response is checked against the schema)

Lists calendar events (time off, holidays, birthdays, and anniversaries) overlapping the requested date range. Events are sorted by start ascending, then type ascending (ANNIVERSARY, BIRTHDAY, HOLIDAY, TIME_OFF), then id ascending. TIME_OFF events represent approved requests only. Events the caller cannot view are silently omitted.

OAuth Scopes: calendar:events

## Query parameters

- `start` string, date, required
- `end` string, date, required
- `filter` string
- `directReportsOnly` boolean
- `includePersons` boolean
- `page` integer
- `pageSize` integer

## Response `200`

A paginated list of calendar events.

- object
  - `data` union[]: Array of calendar event resource objects.
    - union
      - CalendarTimeOffCalendarEventV1: An approved time off request shown on the calendar. Pending, denied, and cancelled requests are never returned.
        - `id` string, required: The time off request id.
        - `type` 'TIME_OFF', required: Event type discriminator.
        - `start` string, date, required: Inclusive first day of the time off (YYYY-MM-DD).
        - `end` string, date, required: Inclusive last day of the time off (YYYY-MM-DD). Same as start for single-day requests.
        - `employeeId` integer, required: The employee taking time off.
        - `timeOffTypeId` integer, nullable, required: The time off type. Null when the caller cannot view this time off type's identity.
      - CalendarHolidayCalendarEventV1: A company holiday shown on the calendar. Holiday events are not affected by per-employee filters or directReportsOnly.
        - `id` string, required: The company holiday id.
        - `type` 'HOLIDAY', required: Event type discriminator.
        - `start` string, date, required: Inclusive first day of the holiday (YYYY-MM-DD).
        - `end` string, date, required: Inclusive last day of the holiday (YYYY-MM-DD). Same as start for single-day holidays.
        - `name` string, required: The holiday name.
      - CalendarBirthdayCalendarEventV1: An employee birthday occurrence on the calendar.
        - `id` string, required: Deterministic synthetic id in the form birthday-{employeeId}-{year}, where year is the year of this occurrence.
        - `type` 'BIRTHDAY', required: Event type discriminator.
        - `start` string, date, required: The day of the birthday occurrence (YYYY-MM-DD).
        - `end` string, date, required: Same as start; birthday events are single-day.
        - `employeeId` integer, required: The employee whose birthday it is.
      - CalendarAnniversaryCalendarEventV1: An employee work anniversary occurrence on the calendar.
        - `id` string, required: Deterministic synthetic id in the form anniversary-{employeeId}-{year}, where year is the year of this occurrence.
        - `type` 'ANNIVERSARY', required: Event type discriminator.
        - `start` string, date, required: The day of the anniversary occurrence (YYYY-MM-DD).
        - `end` string, date, required: Same as start; anniversary events are single-day.
        - `employeeId` integer, required: The employee whose anniversary it is.
        - `years` integer, required: The number of years being celebrated.
  - `persons` object: Present only when includePersons=true. Map keyed by employee id.
  - `_links` object: Pagination links. prev is omitted on the first page; next is omitted on the last page.
    - `prev` object: Link object for the previous page.
      - `href` string
    - `next` object: Link object for the next page.
      - `href` string
  - `meta` object: Pagination metadata. totalItems sums the four event sources within the requested range.
    - `page` integer, required
    - `pageSize` integer, required
    - `totalPages` integer, required
    - `totalItems` integer, required

## Other responses

- `401`: Unauthorized. Missing or invalid authentication.
- `403`: Forbidden. The caller lacks the calendar events scope or permission.
- `422`: Invalid query parameters (missing or malformed start/end, end before start, range spanning a year or more, invalid pageSize, or a malformed filter).

## Changes

- **2026-11-03** `922fc15f43a7`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/bamboohr/apis/bamboohr-api/changes/api/v1/calendar-events/get.md)

---

[API](https://skmtc.dev/bamboohr/apis/bamboohr-api.md) - [All operations](https://skmtc.dev/bamboohr/apis/bamboohr-api/llms.txt) - [OpenAPI document](https://skmtc.dev/bamboohr/apis/bamboohr-api/revisions/922fc15f43a7?raw)