---
search:
  tags:
    - holidays
    - POST
seo:
  description: >-
    Creates a custom holiday year configuration for the workspace, allowing you
    to… Reference for the POST /holidays/years endpoint in the Leadtime Public
    API API.
sidebar:
  badge: POST
  label: Create custom holiday year
title: Create custom holiday year
type: openapi-operation
---
Creates a custom holiday year configuration for the workspace, allowing you to customize holidays for a specific year and country/region.

**What this does:**
Creates a workspace-specific holiday configuration by copying the default holidays for the specified year and country. Once created, you can add, modify, or delete holidays using the holiday days endpoints.

**Important behavior:**
- If a custom year already exists for the specified year/country, it will be **deleted and recreated**
- This effectively resets the year to default holidays
- All existing custom holidays for that year will be lost
- Use this endpoint to start customizing a year or to reset it back to defaults

**Validity period (`validTill`):**
The `validTill` field controls how the custom configuration propagates to future years:
- If `validTill` is set (e.g., 2026), the configuration applies to all years from the specified year through `validTill`
- If `validTill` is `null`, the configuration applies indefinitely to future years
- Future years will automatically be created as "derived" configurations
- You can update `validTill` later using `PUT /holidays/years/:yearId`

**Use cases:**
- Adding company-specific holidays (e.g., "Company Outing", "Festivus")
- Removing holidays that don't apply to your organization
- Modifying holiday dates for your specific needs
- Resetting a customized year back to defaults

**Next steps:**
After creating a custom year, use:
- `POST /holidays/days` to add new holidays
- `PUT /holidays/days/:dayId` to modify existing holidays
- `DELETE /holidays/days/:dayId` to remove holidays

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