---
title: "List Time Off Policies"
method: GET
path: "/api/v1/time-off/policies"
tags: ["Time Off", "Public API"]
---

# List Time Off Policies

`GET /api/v1/time-off/policies`

## Request

- Base URL: `https://companySubDomain.bamboohr.com`
- URL: `https://companySubDomain.bamboohr.com/api/v1/time-off/policies`
- 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/get.ts> (a function with typed inputs; its response is checked against the schema)

Lists time off policies, with support for filtering, sorting, and pagination. Each accruing policy includes its currently effective version with milestones inlined.

OAuth Scopes: time_off:policies

## Query parameters

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

## Response `200`

A paginated list of time off policies.

- object
  - `data` TimeOffPolicyV1[]: Collection of time off policies
    - `id` integer: The unique identifier for the time off policy.
    - `name` string: The name of the time off policy.
    - `categoryId` integer: The id of the time off category this policy belongs to.
    - `type` 'ACCRUING' | 'UNLIMITED' | 'MANUAL': The type of the time off policy.
    - `currentVersion` TimeOffPolicyVersionV1: A version of an accruing time off policy that is effective from a given date, including the milestones that define its accrual behavior. Only accruing policies have 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.
    - `assignedEmployeeCount` integer: The number of active employees currently assigned to this policy.
    - `createdAt` string, date-time: UTC timestamp when the policy was created.
    - `updatedAt` string, date-time, nullable: UTC timestamp when the policy was last updated. Null when the policy has never been updated.
    - `deletedAt` string, date-time, nullable: UTC timestamp when the policy was deleted. Always null because deleted policies are excluded from the API.
  - `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

- `422`: Invalid query parameters (e.g. invalid page, pageSize, orderBy, or an unsupported filter field or value).

## Changes

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

[Operation history](https://skmtc.dev/bamboohr/apis/bamboohr-api/changes/api/v1/time-off/policies/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)