Holiday Calendars

The holiday calendar object

Attribute	Type	Description
`id`	integer	Unique ID for the holiday calendar.
`name`	string	Name of the calendar.
`entries_count`	integer	Total count of scheduled holidays in the calendar.
`entries`	array	Sorted list of holiday entry objects containing `id`, `name`, and `date`.
`created_at`	datetime	Date and time the calendar was created. Use the ISO 8601 Format.
`updated_at`	datetime	Date and time the calendar was last updated. Use the ISO 8601 Format.

The holiday calendar entry object

Attribute	Type	Description
`id`	integer	Unique ID for the holiday entry.
`pto_holiday_calendar_id`	integer	The parent holiday calendar ID.
`name`	string	Name of the holiday.
`date`	date	Date of the holiday closure.
`created_at`	datetime	Date and time the entry was created. Use the ISO 8601 Format.
`updated_at`	datetime	Date and time the entry was last updated. Use the ISO 8601 Format.

Required permissions

The PTO API is currently being rolled out gradually. Requests from unavailable accounts return 403 Forbidden.

Only administrators can access, create, update, and delete holiday calendars and holiday entries. Insufficient permissions will result in a 403 Forbidden status code.

List all holiday calendars

Returns a list of holiday calendars.

The response contains an object with a pto_holiday_calendars property that contains an array of up to per_page holiday calendars. Each entry in the array is a separate holiday calendar object. If no more calendars are available, the resulting array will be empty. Several additional pagination properties are included in the response to simplify paginating your calendars.

GET /v2/pto/holiday_calendars

Parameter	Type	Description
`page`	integer	The page number to use in pagination. (Default: 1)
`per_page`	integer	The number of records to return per page. Can range between 1 and 2000. (Default: 2000)

Example Request:

curl "https://api.harvestapp.com/v2/pto/holiday_calendars" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Harvest-Account-Id: $ACCOUNT_ID" \
  -H "User-Agent: MyApp ([email protected])"

Example Response:

{
  "pto_holiday_calendars": [
    {
      "id": 12,
      "name": "US Holidays",
      "entries_count": 1,
      "entries": [
        {
          "id": 44,
          "name": "New Year's Day",
          "date": "2026-01-01"
        }
      ],
      "created_at": "2026-01-01T00:00:00Z",
      "updated_at": "2026-01-01T00:00:00Z"
    }
  ],
  "per_page": 2000,
  "total_pages": 1,
  "total_entries": 1,
  "next_page": null,
  "previous_page": null,
  "page": 1,
  "links": {
    "first": "https://api.harvestapp.com/v2/pto/holiday_calendars?page=1&per_page=2000",
    "next": null,
    "previous": null,
    "last": "https://api.harvestapp.com/v2/pto/holiday_calendars?page=1&per_page=2000"
  }
}

Retrieve a holiday calendar

Retrieves the details of an existing holiday calendar. Returns a holiday calendar object and a 200 OK response code.

GET /v2/pto/holiday_calendars/{HOLIDAY_CALENDAR_ID}

Example Request:

curl "https://api.harvestapp.com/v2/pto/holiday_calendars/12" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Harvest-Account-Id: $ACCOUNT_ID" \
  -H "User-Agent: MyApp ([email protected])"

Example Response:

{
  "id": 12,
  "name": "US Holidays",
  "entries_count": 1,
  "entries": [
    {
      "id": 44,
      "name": "New Year's Day",
      "date": "2026-01-01"
    }
  ],
  "created_at": "2026-01-01T00:00:00Z",
  "updated_at": "2026-01-01T00:00:00Z"
}

Create a holiday calendar

Creates a new holiday calendar. Returns a holiday calendar object and a 201 Created response code if the call succeeded. Only administrators can perform this action.

POST /v2/pto/holiday_calendars

Parameter	Type	Description
`name`	string	Required. Name of the calendar.
`country_code`	string	Optional ISO country code (e.g. `US`, `GB`) to auto-populate national public holidays.

Example Request:

curl -X POST "https://api.harvestapp.com/v2/pto/holiday_calendars" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Harvest-Account-Id: $ACCOUNT_ID" \
  -H "Content-Type: application/json" \
  -H "User-Agent: MyApp ([email protected])" \
  -d '{"name": "UK Holidays", "country_code": "GB"}'

Example Response:

{
  "id": 13,
  "name": "UK Holidays",
  "entries_count": 8,
  "entries": [
    {
      "id": 50,
      "name": "New Year's Day",
      "date": "2026-01-01"
    }
  ],
  "created_at": "2026-09-03T12:00:00Z",
  "updated_at": "2026-09-03T12:00:00Z"
}

Update a holiday calendar

Updates an existing holiday calendar. Returns a holiday calendar object and a 200 OK response code if the call succeeded. Only administrators can perform this action.

PATCH /v2/pto/holiday_calendars/{HOLIDAY_CALENDAR_ID}

Parameter	Type	Description
`name`	string	Required. Updated name of the calendar.

Example Request:

curl -X PATCH "https://api.harvestapp.com/v2/pto/holiday_calendars/13" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Harvest-Account-Id: $ACCOUNT_ID" \
  -H "Content-Type: application/json" \
  -H "User-Agent: MyApp ([email protected])" \
  -d '{"name": "UK Office Holidays"}'

Example Response:

{
  "id": 13,
  "name": "UK Office Holidays",
  "entries_count": 8,
  "entries": [
    {
      "id": 50,
      "name": "New Year's Day",
      "date": "2026-01-01"
    }
  ],
  "created_at": "2026-09-03T12:00:00Z",
  "updated_at": "2026-09-03T12:05:00Z"
}

Delete a holiday calendar

Deletes a holiday calendar. Returns a 200 OK response code and the deleted holiday calendar object. Only administrators can perform this action.

DELETE /v2/pto/holiday_calendars/{HOLIDAY_CALENDAR_ID}

Example Request:

curl -X DELETE "https://api.harvestapp.com/v2/pto/holiday_calendars/13" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Harvest-Account-Id: $ACCOUNT_ID" \
  -H "User-Agent: MyApp ([email protected])"

List entries in a holiday calendar

Returns a list of holiday entries for the calendar identified by HOLIDAY_CALENDAR_ID.

The response contains an object with a pto_holiday_calendar_entries property that contains an array of up to per_page entries.

GET /v2/pto/holiday_calendars/{HOLIDAY_CALENDAR_ID}/entries

Parameter	Type	Description
`page`	integer	The page number to use in pagination. (Default: 1)
`per_page`	integer	The number of records to return per page. Can range between 1 and 2000. (Default: 2000)

Example Request:

curl "https://api.harvestapp.com/v2/pto/holiday_calendars/12/entries" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Harvest-Account-Id: $ACCOUNT_ID" \
  -H "User-Agent: MyApp ([email protected])"

Example Response:

{
  "pto_holiday_calendar_entries": [
    {
      "id": 44,
      "pto_holiday_calendar_id": 12,
      "name": "New Year's Day",
      "date": "2026-01-01",
      "created_at": "2026-01-01T00:00:00Z",
      "updated_at": "2026-01-01T00:00:00Z"
    }
  ],
  "per_page": 2000,
  "total_pages": 1,
  "total_entries": 1,
  "next_page": null,
  "previous_page": null,
  "page": 1,
  "links": {
    "first": "https://api.harvestapp.com/v2/pto/holiday_calendars/12/entries?page=1&per_page=2000",
    "next": null,
    "previous": null,
    "last": "https://api.harvestapp.com/v2/pto/holiday_calendars/12/entries?page=1&per_page=2000"
  }
}

Create an entry in a holiday calendar

Creates one or more holiday entries in a calendar. Supports a single date or a range of dates. Returns a 201 Created response code. Only administrators can perform this action.

POST /v2/pto/holiday_calendars/{HOLIDAY_CALENDAR_ID}/entries

Parameter	Type	Description
`name`	string	Required. Holiday title.
`date`	date	Holiday date (for single date mode).
`date_mode`	string	Pass `range` to add a range of closed dates.
`start_date`	date	Start date when `date_mode` is `range`.
`end_date`	date	End date when `date_mode` is `range`.

Example Request:

curl -X POST "https://api.harvestapp.com/v2/pto/holiday_calendars/12/entries" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Harvest-Account-Id: $ACCOUNT_ID" \
  -H "Content-Type: application/json" \
  -H "User-Agent: MyApp ([email protected])" \
  -d '{"name": "Memorial Day", "date": "2026-05-25"}'

Example Response:

{
  "id": 45,
  "pto_holiday_calendar_id": 12,
  "name": "Memorial Day",
  "date": "2026-05-25",
  "created_at": "2026-09-03T12:00:00Z",
  "updated_at": "2026-09-03T12:00:00Z"
}

Update a holiday calendar entry

Updates an existing holiday calendar entry. Returns a holiday entry object and a 200 OK response code. Only administrators can perform this action.

PATCH /v2/pto/holiday_calendars/{HOLIDAY_CALENDAR_ID}/entries/{ENTRY_ID}

Parameter	Type	Description
`name`	string	Updated title.
`date`	date	Updated date.

Example Request:

curl -X PATCH "https://api.harvestapp.com/v2/pto/holiday_calendars/12/entries/45" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Harvest-Account-Id: $ACCOUNT_ID" \
  -H "Content-Type: application/json" \
  -H "User-Agent: MyApp ([email protected])" \
  -d '{"name": "Memorial Day Observed"}'

Example Response:

{
  "id": 45,
  "pto_holiday_calendar_id": 12,
  "name": "Memorial Day Observed",
  "date": "2026-05-25",
  "created_at": "2026-09-03T12:00:00Z",
  "updated_at": "2026-09-03T12:05:00Z"
}

Delete a holiday calendar entry

Deletes a holiday calendar entry. Returns a 200 OK response code and the deleted holiday entry object. Only administrators can perform this action.

DELETE /v2/pto/holiday_calendars/{HOLIDAY_CALENDAR_ID}/entries/{ENTRY_ID}

Example Request:

curl -X DELETE "https://api.harvestapp.com/v2/pto/holiday_calendars/12/entries/45" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Harvest-Account-Id: $ACCOUNT_ID" \
  -H "User-Agent: MyApp ([email protected])"

Welcome to the Harvest API v2 Help Center

The holiday calendar object

The holiday calendar entry object

Required permissions

List all holiday calendars

Retrieve a holiday calendar

Create a holiday calendar

Update a holiday calendar

Delete a holiday calendar

List entries in a holiday calendar

Create an entry in a holiday calendar

Update a holiday calendar entry

Delete a holiday calendar entry

Still have questions? We’re happy to help!