---
title: "List Time Off Policy Versions"
method: GET
path: "/api/v1/time-off/policies/{id}/versions"
tags: ["Time Off", "Public API"]
---

# List Time Off Policy Versions

`GET /api/v1/time-off/policies/{id}/versions`

## Request

- Base URL: `https://companySubDomain.bamboohr.com`
- URL: `https://companySubDomain.bamboohr.com/api/v1/time-off/policies/{id}/versions`
- Auth: one of:
  - HTTP basic
  - OAuth 2
    - Authorization code: `/authorize.php`
    - Token URL: `/token.php` scopes: `time_off:policies`
- TypeScript: <https://skmtc.dev/bamboohr/apis/bamboohr-api/docs/api/v1/time-off/policies/:id/versions/get.ts> (a function with typed inputs; its response is checked against the schema)

Lists a time off policy's rate-table versions, with each version's milestones inlined. Ordered by effective date descending, most recent first, with a secondary ordering by version id so paging stays stable when two versions share an effective date. Both currently effective and superseded (archived) versions are returned; versions the server discarded when a schedule was re-saved are not. Unlimited and manual policies have no accrual schedule, so they return an empty list.

OAuth Scopes: time_off:policies

## Path parameters

- `id` integer, required

## Query parameters

- `filter` string
- `page` integer
- `pageSize` integer

## Response `200`

A paginated list of the policy's versions.

- object
  - `data` TimeOffPolicyVersionV1[]: Collection of time off policy versions
    - `id` integer: The unique identifier for the policy version.
    - `policyId` integer: The id of the time off policy this version belongs to.
    - `effectiveDate` string, date, nullable: The date this version becomes effective, in ISO 8601 format (YYYY-MM-DD). Null when the version applies from the beginning of the policy.
    - `status` 'ACTIVE' | 'ARCHIVED': The status of the policy version.
    - `rateTransitions` 'IMMEDIATELY' | 'NEXT_PERIOD': When a rate change between milestones takes effect.
    - `firstAccrual` 'PRORATE' | 'FULL': How the first accrual is handled when an employee starts partway through an accrual period.
    - `carryOverYmd` string, nullable: The calendar date each year when unused time carries over, in MM-DD format. Null when the version has no annual carryover date, which also covers the anniversary-based carryover the settings UI can configure but this contract cannot express.
    - `negativeBalanceResetOnCarryOver` boolean: Whether negative balances are reset to zero at the carryover date. Derived from the milestones: the setting is stored as a zero minimum carryover on every milestone rather than as its own field, so a version with no milestones reports false.
    - `milestones` TimeOffPolicyMilestoneV1[]: The milestones that make up this policy version, ordered chronologically.
      - `id` integer: The unique identifier for the milestone.
      - `accrualBeginsInterval` integer: How long after the accrual-begins reference point this milestone takes effect, measured in the unit given by accrualBeginsType.
      - `accrualBeginsType` 'IMMEDIATELY' | 'DAYS' | 'WEEKS' | 'MONTHS' | 'YEARS': The unit used with accrualBeginsInterval to determine when this milestone begins.
      - `accrualHours` number, nullable: The amount of time accrued each interval, measured in the time off category unit. Null when the policy accrues per hour worked.
      - `accrualInterval` 'HOURLY' | 'DAILY' | 'WEEKLY' | 'BIWEEKLY' | 'SEMIMONTHLY' | 'MONTHLY' | 'QUARTERLY' | 'SEMIANNUALLY' | 'ANNUALLY' | 'ANNIVERSARY': How often time is accrued for this milestone.
      - `maximumHours` number, nullable: The maximum balance an employee may hold under this milestone. Null when there is no cap.
      - `maximumCarryOver` number, nullable: The maximum balance that may carry over at the carryover date. Null when there is no carryover cap.
      - `minimumCarryOver` number, nullable: The minimum balance retained at the carryover date. Null when no minimum is configured.
      - `accruesPerHourWorked` boolean: Whether time accrues per hour worked rather than on a fixed schedule.
      - `preaccruing` boolean: Whether the accrual is granted at the start of the period (preaccruing) rather than at the end.
    - `createdAt` string, date-time, nullable: UTC timestamp when the policy version was created. Null for legacy versions migrated from the pre-versioning schema without a usable creation timestamp.
    - `updatedAt` string, date-time, nullable: UTC timestamp when the policy version was last updated. Null when the version has never been updated.
  - `meta` object
    - `page` integer
    - `pageSize` integer
    - `totalPages` integer
    - `totalItems` integer
  - `_links` object: Pagination links. `prev` is absent on the first page and `next` is absent on the last; neither is ever null.
    - `prev` object
      - `href` string
    - `next` object
      - `href` string

## Other responses

- `401`: Unauthorized. The credentials are missing or invalid.
- `403`: Forbidden. The authenticated user may not view this time off policy.
- `404`: The time off policy does not exist.
- `422`: Invalid query parameters (e.g. invalid page, pageSize, or an unsupported filter field).

## Changes

- **2026-11-03** `922fc15f43a7`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/bamboohr/apis/bamboohr-api/changes/api/v1/time-off/policies/:id/versions/get.md)

---

[API](https://skmtc.dev/bamboohr/apis/bamboohr-api.md) - [All operations](https://skmtc.dev/bamboohr/apis/bamboohr-api/llms.txt) - [OpenAPI document](https://skmtc.dev/bamboohr/apis/bamboohr-api/revisions/922fc15f43a7?raw)