---
title: "List Company Holidays"
method: GET
path: "/api/v1/holidays"
tags: ["Holidays", "Public API"]
---

# List Company Holidays

`GET /api/v1/holidays`

## Request

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

Returns a paginated list of active company holidays. Soft-deleted holidays are never returned. Supports OData filtering via `filter`, sorting via `orderBy`, field projection via `select`, and page-based pagination.

OAuth Scopes: holidays

## Query parameters

- `filter` string
- `orderBy` string
- `select` string
- `page` integer
- `pageSize` integer

## Response `200`

A paginated list of company holidays.

- object
  - `data` HolidayCompanyHolidayV1[]: Collection of company holidays
    - `id` integer: The ID of the holiday
    - `name` string: The name of the holiday
    - `startDate` string, date: The start date of the holiday
    - `endDate` string, date, nullable: The end date of the holiday. Null for single-day holidays.
    - `isPublic` boolean: Whether the holiday is visible to all employees on calendars, independent of audience
    - `countryCodes` string[]: Country filter as ISO 3166-1 alpha-2 codes. Empty means no country filter.
    - `audience` HolidayCompanyHolidayAudienceV1: Defines which employees a company holiday applies to
      - `mode` 'ALL_EMPLOYEES' | 'FILTERED' | 'SPECIFIC_EMPLOYEES': How the holiday audience is determined
      - `filterListValueIds` integer[]: List-value IDs that filter the audience. Only populated in FILTERED mode.
      - `specificEmployeeIds` integer[]: Employee IDs that define the audience. Only populated in SPECIFIC_EMPLOYEES mode.
      - `additionalEmployeeIds` integer[]: Employee IDs explicitly included on top of the mode's default audience.
      - `exemptEmployeeIds` integer[]: Employee IDs explicitly excluded from the mode's default audience.
    - `holidayPay` HolidayCompanyHolidayPayV1, nullable: Pay treatment for a company holiday
      - `mode` 'HOURS_BY_STATUS' | 'MULTIPLIER': How holiday pay is calculated
      - `defaultHours` string, nullable: Catch-all hours applied to employment statuses without an override. Only populated in HOURS_BY_STATUS mode.
      - `hoursByEmploymentStatus` HolidayCompanyHolidayPayStatusHoursV1[]: Per-employment-status hour overrides. Only populated in HOURS_BY_STATUS mode.
        - `employmentStatusListValueId` integer: List-value ID from the company's Employment Status list
        - `hours` string: Paid hours for the employment status
      - `multiplier` string, nullable: Pay rate multiplier. Only populated in MULTIPLIER mode.
    - `globalHolidayUuid` string, uuid, nullable: UUID of the global catalog entry this holiday was sourced from. Null for custom holidays.
    - `createdAt` string, date-time: ISO 8601 timestamp when the holiday was created
    - `updatedAt` string, date-time: ISO 8601 timestamp when the holiday was last updated
    - `deletedAt` string, date-time, nullable: ISO 8601 timestamp when the holiday was soft-deleted. Null for active holidays.
  - `meta` object: Pagination metadata.
    - `page` integer, required
    - `pageSize` integer, required
    - `totalPages` integer, required
    - `totalItems` integer, required
  - `_links` object: Pagination links.
    - `prev` object, nullable, required: Link object for the previous page, or null when on the first page.
      - `href` string: Full URL for the previous page
    - `next` object, nullable, required: Link object for the next page, or null when on the last page.
      - `href` string: Full URL for the next page

## Other responses

- `401`: Unauthorized. Missing or invalid authentication.
- `403`: Forbidden. Insufficient permissions.
- `422`: Invalid query parameter (bad page or pageSize, unsupported filter/sort/select field, or malformed filter expression).

## Changes

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

[Operation history](https://skmtc.dev/bamboohr/apis/bamboohr-api/changes/api/v1/holidays/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)