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

# List Time Off Requests

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

## Request

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

Lists time off requests, with support for filtering, sorting, and pagination.

OAuth Scopes: time_off:requests

## Query parameters

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

## Response `200`

A paginated list of time off requests.

- object
  - `data` TimeOffRequestV1[]: Collection of time off requests
    - `id` integer: The unique identifier for the time off request.
    - `employeeId` integer: The id of the employee requesting time off.
    - `categoryId` integer: The id of the time off category for the request.
    - `startDate` string, date: The date the time off starts, in ISO 8601 format (YYYY-MM-DD).
    - `endDate` string, date: The date the time off ends, in ISO 8601 format (YYYY-MM-DD).
    - `amount` number: The amount of time off requested, measured in the unit defined by the time off category (e.g. 3.5 days if the unit is days, or 3.5 hours if the unit is hours).
    - `unit` 'HOURS' | 'DAYS': The unit of measurement for the time off request.
    - `status` 'REQUESTED' | 'APPROVED' | 'DENIED' | 'CANCELED': The status of the time off request.
    - `requestedAt` string, date-time: UTC timestamp when the time off request was requested.
    - `dailyAmounts` TimeOffRequestDailyAmountV1[]: The amount of time off requested per day.
      - `date` string, date: The date, in ISO 8601 format (YYYY-MM-DD).
      - `amount` number: The amount of time off requested on this day, measured in the request unit.
    - `employeeNote` string, nullable: The free-form note left by the employee who requested the time off. Null when never set.
    - `managerNote` string, nullable: The manager's note left when the request was approved or denied. Null when never set.
    - `statusUpdatedAt` string, date-time, nullable: UTC timestamp when the status was last updated. Null when the status has never changed.
    - `statusUpdatedBy` integer, nullable: The id of the user who last updated the status. Null when the status has never changed.
    - `_links` object: The state transitions available to the caller for this request. Only present when the request was made with `returnActions=true`. `self` is always present when the block is returned, and the absence of a transition is authoritative: calling it anyway returns 403 or 409.
  - `meta` object
    - `page` integer
    - `pageSize` integer
    - `totalPages` integer
    - `totalItems` integer
  - `_links` object
    - `prev` object, nullable
      - `href` string
    - `next` object, nullable
      - `href` string

## Other responses

- `422`: Invalid query parameters (e.g. invalid page, pageSize, orderBy, 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/requests/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)