Get holiday year

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:

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
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
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)

GET/holidays/years

Authorization

AuthorizationOAuth2 access token · headerrequired

Scopes:api:read

AuthorizationBearer token (JWT) · headerrequired

Query parameters

yearnumberrequired

The year to retrieve holidays for. Must be 1900 or later. The endpoint will return the appropriate configuration type (default, custom, or derived) for this year.

countrystringrequired

Country or region code (e.g., "US", "DE", "US-CA"). Must be one of the available codes from `GET /holidays/countries`.

Responses

200Holiday year retrieved successfully

countrystringrequired

Country or region code for this holiday configuration (e.g., "US", "DE", "US-CA").

derivedFromnumber

The year this configuration was derived from. Only present for derived type configurations. Indicates which custom year this configuration was copied from.

holidaysHolidayDayDto[]required

Complete list of all holidays for this year, including both fixed and rule-based holidays. Holidays are sorted by date and include computed dates for rule-based holidays.

Show properties

Array of HolidayDayDto

datestringrequired

The computed date of the holiday in ISO 8601 format. For Fixed holidays, this is the specific date. For Rule-based holidays, this is the date computed from the rule for the given year.

idstringrequired

Unique identifier for the holiday day. Only present for holidays in custom or derived years.

namestringrequired

The name of the holiday (e.g., "Christmas Day", "New Year's Day", "Company Outing").

rulestring

Rule string for rule-based holidays (only present for Rule type). Examples: "25 december", "easter monday", "first monday in september". The date is automatically computed from this rule for each year.

substitutebooleanrequired

Whether this is a substitute holiday (a replacement for a holiday that falls on a weekend). Substitute holidays are automatically created when official holidays fall on non-working days.

typestringrequired

The type of holiday: "Fixed" for specific dates, "Rule" for computed dates based on rules.

Allowed:FixedRule

idstring

Unique identifier for the holiday year. Only present for custom or derived years. Default years do not have an ID as they cannot be directly modified.

typestringrequired

The type of holiday configuration: - `"default"`: Official holidays from the holiday data source (cannot be modified) - `"custom"`: Workspace-specific configuration (can be modified) - `"derived"`: Configuration inherited from a previous custom year (can be modified)

Allowed:defaultcustomderived

validTillobject

The last year this configuration applies to. If `null`, the configuration applies indefinitely to all future years. Only present for custom or derived years. Controls how the configuration propagates to future years.

yearnumberrequired

The year this holiday configuration applies to.

401Unauthorized - Invalid or missing authentication token

403Forbidden - Insufficient API scopes or permissions

Request

curl -X GET "https://leadtime.app/api/public/holidays/years?year=2024&country=US" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

const response = await fetch("https://leadtime.app/api/public/holidays/years?year=2024&country=US", {
  method: "GET",
  headers: {
    "Authorization": "Bearer YOUR_ACCESS_TOKEN"
  }
});

import requests

response = requests.get(
    "https://leadtime.app/api/public/holidays/years?year=2024&country=US",
    headers={
        "Authorization": "Bearer YOUR_ACCESS_TOKEN"
    },
)

Response

{
  "country": "US",
  "derivedFrom": 2023,
  "holidays": [
    {
      "date": "2024-12-25T00:00:00.000Z",
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Christmas Day",
      "rule": "25 december",
      "substitute": false,
      "type": "Fixed"
    }
  ],
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "type": "default",
  "validTill": 2025,
  "year": 2024
}