---
title: "Find public holidays"
method: GET
path: "/public-holidays"
tags: ["public-holidays"]
---

# Find public holidays

`GET /public-holidays`

## Request

- Base URL: `https://api.hoorayhr.io`
- URL: `https://api.hoorayhr.io/public-holidays`
- Auth: API key in header `authorization`

Returns the company public holidays within the provided date range.

**Date range**

A date range is **required**: provide both `date[$gte]` and `date[$lte]` (format `YYYY-MM-DD`). The maximum range is **one year**.

**Behavior**

- Holidays whose policy has no active users are omitted.
- `userIds` only contains active (non-archived) users.
- A holiday that belongs to multiple policies is returned as a separate record per policy, each carrying its own `userIds` (the active users of that policy). The same holiday can therefore appear more than once in the response, once for each policy it belongs to.
- Holiday names are localized to the language of the user the OAuth integration or API key is linked to.
- Provide an optional `userId` to only return the holidays applying to that user.

## Query parameters

- `date[$gte]` string, date, required
- `date[$lte]` string, date, required
- `userId` number

## Response `200`

success

- PublicHolidays[]
  - `id` number: The holiday unique ID
  - `name` string: The name of the holiday
  - `date` string, date: The date of the holiday. Format: YYYY-MM-DD
  - `subtractFromBudget` boolean: Whether the holiday is subtracted from the leave budget
  - `userIds` number[]: Ids of the active users the holiday applies to

## Other responses

- `401`: not authenticated
- `500`: general error

---

[API](https://skmtc.dev/hoorayhr/apis/hoorayhr-api-documentation.md) · [All operations](https://skmtc.dev/hoorayhr/apis/hoorayhr-api-documentation/llms.txt) · [OpenAPI document](https://skmtc.dev/hoorayhr/apis/hoorayhr-api-documentation/revisions/3adcd47cd827?raw)