---
title: "Update Time Off Request"
method: PATCH
path: "/api/v1/time-off/requests/{id}"
tags: ["Time Off", "Public API"]
---

# Update Time Off Request

`PATCH /api/v1/time-off/requests/{id}`

## Request

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

Updates an existing time off request using JSON Merge Patch semantics: only the fields present in the body are changed, and `employeeNote` may be set to null to clear it. Accepts both `application/merge-patch+json` and `application/json`. 

Editing a request whose status is REQUESTED replaces the stored request and restarts its approval workflow, so the `id` in the response differs from the id in the path. That `id` is authoritative and should replace any id the client is holding; the id that was replaced returns 410 from then on. `requestedAt` is carried over from the replaced request, and editing a request whose status is APPROVED updates it in place, so `id` and `requestedAt` are both unchanged in that case.

Changing `startDate` or `endDate` requires sending `dailyAmounts` in the same request, so the per-day breakdown always covers the stored range. Omitting it returns 422; the server does not redistribute amounts on the caller's behalf.

OAuth Scopes: time_off:requests.write

## Path parameters

- `id` integer, required

## Query parameters

- `returnActions` boolean

## Request body

- TimeOffUpdateRequestV1: Data contract for partially updating a time off request. All fields are optional; only fields present in the request body are updated. Supplying `employeeNote` as null clears it.
  - `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 (inclusive), in ISO 8601 format (YYYY-MM-DD).
  - `employeeNote` string, nullable: A note from the requester. Pass null to clear it. Maximum 1024 characters.
  - `dailyAmounts` TimeOffRequestDailyAmountV1[]: The per-day amounts of time off requested, each within the request date range. Replaces the existing breakdown entirely, and restates the total amount with it. Required whenever `startDate` or `endDate` changes.
    - `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 `200`

The updated time off request. Its `id` may differ from the id in the path.

- 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 edit time off for this employee.
- `404`: The time off request, or a newly supplied category, does not exist.
- `409`: The request is DENIED or CANCELED, or is APPROVED with a past start date and the caller lacks the edit-past-requests permission.
- `410`: The id refers to a request that a later edit replaced. Use the id returned by that edit.
- `422`: Invalid request data (e.g. invalid dates, an end date before the start date, or daily amounts outside the range).

## Changes

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

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