---
title: "Create Time Off Request"
method: POST
path: "/api/v1/time-off/requests"
tags: ["Time Off", "Public API"]
---

# Create Time Off Request

`POST /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.write`
- TypeScript: <https://skmtc.dev/bamboohr/apis/bamboohr-api/docs/api/v1/time-off/requests/post.ts> (a function with typed inputs; its response is checked against the schema)

Creates a time off request on behalf of an employee. The request is created with status REQUESTED and enters the approval workflow.

OAuth Scopes: time_off:requests.write

## Query parameters

- `returnActions` boolean

## Request body

- TimeOffCreateRequestV1: Data contract for creating a time off request on behalf of an employee. Exactly one of 'amount' or 'dailyAmounts' must be supplied.
  - `employeeId` integer, required: The id of the employee the time off is requested for.
  - `categoryId` integer, required: The id of the time off category for the request.
  - `startDate` string, date, required: The date the time off starts, in ISO 8601 format (YYYY-MM-DD).
  - `endDate` string, date, required: The date the time off ends (inclusive), in ISO 8601 format (YYYY-MM-DD).
  - `employeeNote` string, nullable: An optional note from the requester. Maximum 1024 characters.
  - `amount` number, nullable: The total amount of time off requested for the whole range, in the category's unit, with at most 2 decimal places. It is split evenly across the days from startDate to endDate (inclusive) that have default hours for the employee, the same days the request form prefills. Holidays and days with no default hours (usually weekends) get no amount; if no day in the range has default hours, the request is rejected. When the amount does not divide evenly, the remainder is added 0.01 at a time to the last days, so the per-day amounts sum to amount (for example, 10 over 3 days is 3.33, 3.33, 3.34). Supply dailyAmounts instead to set each day's amount. Supply exactly one of 'amount' or 'dailyAmounts'.
  - `dailyAmounts` TimeOffRequestDailyAmountV1[], nullable: The per-day amounts of time off requested, each within the request date range. Supply exactly one of 'amount' or 'dailyAmounts'.
    - `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.

## Response `201`

The time off request was created.

- TimeOffRequestV1: A request of time off to be taken by an employee.
  - `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.

## Other responses

- `400`: Malformed request body.
- `401`: Unauthorized. Missing or invalid authentication.
- `403`: Forbidden. The caller cannot record time off for this employee.
- `404`: The employee or category does not exist.
- `422`: Invalid request data (e.g. invalid dates, out-of-range daily amounts, inactive/unenrolled category, or an overlapping request).

## Changes

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

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