BAbamboohr
Time Off
Public API

List Time Off Requests

Changed on

Returns time off requests whose date range overlaps the start/end window, requests whose updated timestamp is on or after updatedSince, or, when all three are supplied, requests matching either one. Supply start and end together (YYYY-MM-DD), updatedSince, or all three. The date search is inclusive: requests whose date range overlaps the query window are returned. Results can be further filtered by status, employee, time off type, or limited to requests the caller can approve.

Do not pass employeeId=0 expecting the caller's own requests. Unlike Get Employee (get-employee), the 0 self sentinel is not supported here and returns an empty array with HTTP 200 rather than an error, which is easily misread as the caller having no requests. Use action=myRequests for the authenticated caller's own requests, or resolve their internal employee ID with get-employee using the id 0 and pass that value.

An empty result does not mean the employee has no requests. A caller who lacks permission to view another employee's time off receives an empty array with HTTP 200, indistinguishable from an employee with no requests in the window. Before concluding that someone has no time off requests, confirm that the window is wide enough and that the caller can actually view that employee. This endpoint and Get Time Off Balance (get-time-off-balance) are gated independently, so neither one's outcome predicts the other's. A caller can receive 403 from the balance endpoint for an employee while still receiving that same employee's requests here, which has been observed for a manager viewing a direct report. Do not infer access to one endpoint from access to the other, and do not treat a result from one as evidence about the other.

OAuth Scopes: time_off

get/api/v1/time_off/requests

Request

Query parameters

idstring

A particular request ID to limit the response to.

action'view' | 'approve' | 'myRequests'

Limit to requests the caller can view, requests they can approve, or only their own requests via myRequests. Defaults to view.

employeeIdstring

A particular internal employee ID to limit the response to.

startstring date

The left boundary of the search window, in YYYY-MM-DD format. Required unless updatedSince is supplied, and always required together with end. Returns any request whose end date falls on or after this date — i.e., requests that are still active at the start of your window. To find all requests overlapping a date range, pass your range start here. Note: this parameter filters on each request's end date, not its start date.

endstring date

The right boundary of the search window, in YYYY-MM-DD format. Required unless updatedSince is supplied, and always required together with start. Returns any request whose start date falls on or before this date — i.e., requests that have begun by the end of your window. To find all requests overlapping a date range, pass your range end here. Note: this parameter filters on each request's start date, not its end date.

updatedSincestring date-time
Example:2026-01-05T13:45:00Z

An inclusive lower bound on each request's updated timestamp, as an ISO 8601 date-time with a Z or numeric offset and no fractional seconds, for example 2026-01-05T13:45:00Z. URL-encode a + offset as %2B. Use this to pick up retroactive changes that a start/end window alone cannot surface. updated is set when a request is created and moves when it is approved, denied, canceled, superseded, or edited. Editing a pending request supersedes it with a new request that has a new id. Changes to related data do not move updated: the employee's name, the time off type's name, icon, or unit, comments, and the caller's permissions. Requests that stop being returned, such as those that are deleted or belong to a deleted employee or time off type, are not reported. Poll with an overlap rather than from the exact last updated value, because a change can commit shortly after the time it records. When this parameter is supplied start and end become optional; when all three are supplied, requests matching either the window or this bound are returned. Results are then ordered by updated ascending, then id ascending; no ordering is guaranteed otherwise.

typestring

A comma-separated list of time off type IDs to filter by. If omitted, requests of all types are included.

statusstring

A comma-separated list of request status values to filter by. Accepted values are approved, denied, superceded, requested, and canceled. If omitted, requests of all statuses are included.

excludeNotestring

When set to any truthy value, omits the notes object from each request in the response.

Headers

AcceptHeaderParameter'application/xml' | 'application/json'

This endpoint can produce either JSON or XML.

Response

A list of time off requests matching the specified filters.

idstring

The time off request ID.

employeeIdstring

The internal employee ID.

namestring

The employee's full name.

startstring date

The start date of the request in YYYY-MM-DD format.

endstring date

The end date of the request in YYYY-MM-DD format.

createdstring date

The date the request was created in YYYY-MM-DD format (company timezone).

updatedstring date-time nullable

When the request was created or last changed, as an ISO 8601 UTC date-time, for example 2026-01-05T20:45:00Z. The same instant as status.lastChanged, which reports only the date in the company timezone. This is the value updatedSince filters on. null only for legacy records with no recorded change time.

datesobject

A map of dates (YYYY-MM-DD) to daily amounts.

Example response

[
  {
    "id": "1348",
    "employeeId": "5"
  }
]

Changes

  • 922fc15f43a7Revision changes
    • info

      added the new optional query request parameter updatedSince

    • info

      the query request parameter end became optional

    • info

      the query request parameter start became optional

    • info

      added the optional property / to the response with the status