The time off policy object

Required permissions

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

Administrators can list, create, update, deactivate, and permanently delete time off policies.

Non-administrators can list and view active policies that are configured as visible to all teammates. Listing policies will omit hidden or deactivated policies for non-administrators, and attempting to view a policy that is not visible will result in a 404 Not Found response code.

List all time off policies

Returns a list of time off policies.

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

GET /v2/pto/types

Example Request:

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

Example Response:

{
  "pto_types": [
    {
      "id": 101,
      "name": "Vacation",
      "color": "blue",
      "icon": "vacation",
      "accrual_type": "fixed",
      "accrual_schedule": "monthly",
      "default_days_per_year": 25.0,
      "max_carryover_days": 5.0,
      "requires_approval": true,
      "visible_to_all": true,
      "is_active": true,
      "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/types?page=1&per_page=2000",
    "next": null,
    "previous": null,
    "last": "https://api.harvestapp.com/v2/pto/types?page=1&per_page=2000"
  }
}

Retrieve a time off policy

Retrieves the details of an existing time off policy. Returns a time off policy object and a 200 OK response code.

GET /v2/pto/types/{PTO_TYPE_ID}

Example Request:

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

Example Response:

{
  "id": 101,
  "name": "Vacation",
  "color": "blue",
  "icon": "vacation",
  "accrual_type": "fixed",
  "accrual_schedule": "monthly",
  "default_days_per_year": 25.0,
  "max_carryover_days": 5.0,
  "requires_approval": true,
  "visible_to_all": true,
  "is_active": true,
  "created_at": "2026-01-01T00:00:00Z",
  "updated_at": "2026-01-01T00:00:00Z"
}

Create a time off policy

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

POST /v2/pto/types

Example Request:

curl -X POST "https://api.harvestapp.com/v2/pto/types" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Harvest-Account-Id: $ACCOUNT_ID" \
  -H "Content-Type: application/json" \
  -H "User-Agent: MyApp ([email protected])" \
  -d '{"name": "Floating Holiday", "default_days_per_year": 2.0, "requires_approval": false}'

Example Response:

{
  "id": 102,
  "name": "Floating Holiday",
  "color": "orange",
  "icon": "calendar",
  "accrual_type": "fixed",
  "accrual_schedule": "monthly",
  "default_days_per_year": 2.0,
  "max_carryover_days": 0.0,
  "requires_approval": false,
  "visible_to_all": true,
  "is_active": true,
  "created_at": "2026-09-03T12:00:00Z",
  "updated_at": "2026-09-03T12:00:00Z"
}

Update a time off policy

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

PATCH /v2/pto/types/{PTO_TYPE_ID}

Example Request:

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

Example Response:

{
  "id": 101,
  "name": "Vacation",
  "color": "blue",
  "icon": "vacation",
  "accrual_type": "fixed",
  "accrual_schedule": "monthly",
  "default_days_per_year": 28.0,
  "max_carryover_days": 5.0,
  "requires_approval": true,
  "visible_to_all": true,
  "is_active": true,
  "created_at": "2026-01-01T00:00:00Z",
  "updated_at": "2026-09-03T12:05:00Z"
}

Delete a time off policy

Deletes or deactivates an existing time off policy. By default, time off policies are deactivated rather than permanently deleted so historical requests and allocations remain preserved. Returns a 200 OK response code and the deactivated time off policy object with is_active set to false.

To permanently delete a policy along with all of its associated requests and historical data, pass keep_history=false and confirm_delete_history=1. A successful permanent deletion returns a 204 No Content response code. A policy cannot be permanently deleted if it is the only remaining policy in the company or if it has requests included in locked payroll. Only administrators can perform this action.

DELETE /v2/pto/types/{PTO_TYPE_ID}

Example Request:

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

Example Response:

{
  "id": 101,
  "name": "Vacation",
  "color": "blue",
  "icon": "vacation",
  "accrual_type": "fixed",
  "accrual_schedule": "monthly",
  "default_days_per_year": 28.0,
  "max_carryover_days": 5.0,
  "requires_approval": true,
  "visible_to_all": true,
  "is_active": false,
  "created_at": "2026-01-01T00:00:00Z",
  "updated_at": "2026-09-03T12:10:00Z"
}