Vacation Tracker Docs
REST API v2API referenceLocations

List a location's holidays

This API method returns the holiday days of a location in one year, sorted by date, in one response without pagination. Requires `holidays:read`. - Each day is a separate entry: a multi-day holiday returns one entry per day, sharing `multiDayId`. - `year` defaults to the current UTC year. Errors: `400 VALIDATION_ERROR` (`year` is not a whole number) and `404 RESOURCE_NOT_FOUND` (the location does not exist or is outside the key's data reach).

GET
/v2/locations/{id}/holidays

Authorization

bearerAuth holidays:read
AuthorizationBearer <token>

API key sent as Authorization: Bearer vt_live_<secret>. See the Authentication and Scopes sections at the top of this document for how keys are created, which scopes exist and how the key owner's role limits them.

In: header

Scope: holidays:read

Path Parameters

id*string

resource ID.

Query Parameters

year?integer

the year to list holidays for, defaults to the current UTC year.

Range0 <= value

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v2/locations/string/holidays"
{
  "data": [
    {
      "id": "holiday-8e1f2a3b-4c5d-4e6f-9a7b-8c9d0e1f2a3b",
      "locationId": "location-79c77ac8-e5bf-479f-9488-648a58379ff1",
      "name": "New Year's Day",
      "date": "2026-01-01",
      "isHalfDay": false,
      "type": "imported",
      "recurring": true
    },
    {
      "id": "holiday-5a6b7c8d-9e0f-4a1b-8c2d-3e4f5a6b7c8d",
      "locationId": "location-79c77ac8-e5bf-479f-9488-648a58379ff1",
      "name": "Company retreat",
      "date": "2026-06-18",
      "isHalfDay": false,
      "type": "custom",
      "recurring": false,
      "multiDayId": "multiDay-2b3c4d5e-6f7a-4b8c-9d0e-1f2a3b4c5d6e"
    },
    {
      "id": "holiday-5a6b7c8d-9e0f-4a1b-8c2d-3e4f5a6b7c8d",
      "locationId": "location-79c77ac8-e5bf-479f-9488-648a58379ff1",
      "name": "Company retreat",
      "date": "2026-06-19",
      "isHalfDay": false,
      "type": "custom",
      "recurring": false,
      "multiDayId": "multiDay-2b3c4d5e-6f7a-4b8c-9d0e-1f2a3b4c5d6e"
    },
    {
      "id": "holiday-4d2b7c1e-9a3f-4e5d-8c6b-1a2f3e4d5c6b",
      "locationId": "location-79c77ac8-e5bf-479f-9488-648a58379ff1",
      "name": "Christmas Day",
      "date": "2026-12-25",
      "isHalfDay": false,
      "type": "custom",
      "recurring": true
    }
  ]
}
{
  "error": {
    "code": "VALIDATION_ERROR",
    "name": "ValidationError",
    "description": "A query parameter, body field or header failed validation.",
    "resolution": "Fix the fields listed in details.fields and send the request again.",
    "requestId": "c6af9ac6-7b61-11e6-9a41-93e8deadbeef",
    "details": {
      "fields": [
        {
          "path": "startDate",
          "message": "\"startDate\" is required"
        }
      ]
    }
  }
}
{
  "error": {
    "code": "UNAUTHORIZED",
    "name": "Unauthorized",
    "description": "The API key is missing, malformed or not recognized.",
    "resolution": "Send a valid API key in the Authorization header as Bearer followed by the full vt_live_ key.",
    "requestId": "c6af9ac6-7b61-11e6-9a41-93e8deadbeef"
  }
}

{
  "error": {
    "code": "INSUFFICIENT_SCOPE",
    "name": "InsufficientScope",
    "description": "The API key does not have the scopes this request needs.",
    "resolution": "Add the scopes listed in details.requiredScopes to the key in the Vacation Tracker dashboard.",
    "requestId": "c6af9ac6-7b61-11e6-9a41-93e8deadbeef",
    "details": {
      "requiredScopes": [
        "leaves:write"
      ]
    }
  }
}

{
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "name": "ResourceNotFound",
    "description": "The requested resource does not exist or is outside the data this key can access.",
    "resolution": "Check the ID of the resource named in details.resource and that the key owner can see it.",
    "requestId": "c6af9ac6-7b61-11e6-9a41-93e8deadbeef"
  }
}
{
  "error": {
    "code": "RATE_LIMITED",
    "name": "RateLimited",
    "description": "Too many requests were sent in a short time.",
    "resolution": "Wait a few seconds and retry, using the same Idempotency-Key for writes.",
    "requestId": "c6af9ac6-7b61-11e6-9a41-93e8deadbeef"
  }
}
{
  "error": {
    "code": "INTERNAL_ERROR",
    "name": "InternalError",
    "description": "Something went wrong on our side.",
    "resolution": "Retry later, and if it keeps happening, contact Vacation Tracker support and quote the requestId.",
    "requestId": "c6af9ac6-7b61-11e6-9a41-93e8deadbeef"
  }
}

Need help?

developers@vacationtracker.io

Replace a location's work week

This API method replaces the working days and work hours of a location. Requires `locations:write`. The acting user is the key owner, or the `X-On-Behalf-Of` user. It waits for the change and returns the new work week with `200`, or `202 Accepted` with an operation to poll. - This is a full replacement, not a merge: send every working day in `days`, and every custom work-hours entry in `workHours`. Days without a `workHours` entry use the default work hours. - `resetUserOverrides` defaults to `false`. Set it to `true` to also clear every per-user work week override in this location, so every user follows the new work week. Errors: `400 VALIDATION_ERROR` (`details.fields`), `400 INVALID_REQUEST_BODY`, `403 ON_BEHALF_OF_NOT_ALLOWED`, `403 FORBIDDEN`, `403 WORK_HOURS_LIMIT_REACHED` (custom work hours need a plan that includes them), `404 RESOURCE_NOT_FOUND` (the location does not exist or is outside the key's data reach), and the `Idempotency-Key` codes.

Create a holiday

This API method creates a holiday in a location: a single day, a multi-day holiday, or a holiday that repeats every year. Requires `holidays:write`. The acting user is the key owner, or the `X-On-Behalf-Of` user. It waits for the holiday to be created and returns its first day with `201`, or `202 Accepted` with an operation to poll. - `name` and `startDate` are required. `endDate` defaults to `startDate`, and must be in the same year. - `isHalfDay`, `transferIfFallsOnNonWorkingDay` and `recurring` default to `false`. For a recurring holiday that is not on the same date every year, describe the rule in `recurringRules`. - The start year must be from 2020 to next year, and the dates cannot overlap another holiday of the location. - Unknown fields fail validation. Errors: `400 VALIDATION_ERROR` (`details.fields`), `400 INVALID_REQUEST_BODY`, `403 ON_BEHALF_OF_NOT_ALLOWED`, `403 FORBIDDEN`, `404 RESOURCE_NOT_FOUND` (the location does not exist or is outside the key's data reach), `409 HOLIDAY_DATES_OVERLAP`, `422 HOLIDAY_INVALID_DATES` (the dates are in different years, the start is after the end, or the start year is outside 2020 to next year), and the `Idempotency-Key` codes.