---
title: "List Who's Out"
method: GET
path: "/api/v1/whos-out"
tags: ["Time Off", "Public API"]
---

# List Who's Out

`GET /api/v1/whos-out`

## Request

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

Lists approved time off occurrences overlapping the requested date range, scoped to employees the caller can see. Results the caller lacks permission to view are silently excluded. Dates are interpreted in the company timezone. Results are sorted by start date ascending, then id ascending.

OAuth Scopes: time_off

## Query parameters

- `start` string, date, required
- `end` string, date, required
- `filter` string
- `directReportsOnly` boolean
- `includePersons` boolean
- `page` integer
- `pageSize` integer

## Response `200`

A paginated list of approved time off occurrences.

- object
  - `data` WhosOutV1[]: Collection of approved time off occurrences
    - `id` string: The time off request ID. Stable across calls.
    - `employeeId` integer: The id of the employee taking time off.
    - `timeOffTypeId` integer: The id of the time off type.
    - `start` string, date: The first day of the time off, in ISO 8601 format (YYYY-MM-DD). All-day inclusive. Interpreted in the company timezone.
    - `end` string, date: The last day of the time off, in ISO 8601 format (YYYY-MM-DD). All-day inclusive. Same as start for single-day requests.
  - `persons` object: Employee display data keyed by employee id. Present only when includePersons=true.
  - `_links` object
    - `prev` object: Link object for the previous page. Omitted when there is no previous page.
      - `href` string
    - `next` object: Link object for the next page. Omitted when there is no next page.
      - `href` string
  - `meta` object
    - `page` integer
    - `pageSize` integer
    - `totalPages` integer
    - `totalItems` integer

## Other responses

- `401`: Unauthorized. Missing or invalid authentication.
- `403`: Forbidden. Missing the time_off scope.
- `422`: Invalid query parameters (e.g. missing or malformed start/end, end before start, range over 366 days, pageSize outside 10-100, 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/whos-out/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)