---
search:
  tags:
    - holidays
    - GET
seo:
  description: >-
    Retrieves the complete holiday configuration for a specific year and…
    Reference for the GET /holidays/years endpoint in the Leadtime Public API
    API.
sidebar:
  badge: GET
  label: Get holiday year
title: Get holiday year
type: openapi-operation
---
Retrieves the complete holiday configuration for a specific year and country/region.

**What is returned:**
The endpoint returns one of three types of holiday configurations:

1. **Default** (`type: "default"`): Official holidays from the holiday data source
   - No `id` field (not a custom year)
   - Cannot be modified directly
   - Used when no custom configuration exists

2. **Custom** (`type: "custom"`): Workspace-specific holiday configuration
   - Has an `id` field (UUID)
   - Can be modified (add, edit, delete holidays)
   - Created when you customize holidays for a year
   - May have a `validTill` year that controls propagation to future years

3. **Derived** (`type: "derived"`): Configuration inherited from a previous custom year
   - Has an `id` field (UUID)
   - Shows `derivedFrom` year that it was copied from
   - Created automatically when a custom year's `validTill` extends to future years
   - Can be modified like custom years

**Holiday types:**
Each holiday in the list can be:
- **Fixed**: A specific date (e.g., "2024-12-25" for Christmas)
- **Rule**: A computed date based on a rule (e.g., "25 december" or "easter monday")

**Response fields:**
- `id`: Holiday year ID (only for custom/derived types)
- `year`: The year this configuration applies to
- `country`: Country/region code
- `type`: Configuration type ("default", "custom", or "derived")
- `derivedFrom`: Source year for derived configurations
- `validTill`: Last year this configuration applies to (null = indefinite)
- `holidays`: Array of all holidays with name, date, type, rule, and substitute flag

**Use cases:**
- Displaying holidays in a calendar view
- Checking if a year has been customized
- Getting the complete holiday list for capacity planning
- Understanding the relationship between years (derived configurations)

<Operation source="api-reference" id="holidayscontroller-getholidayyear" />