BAbamboohr
Time Off
Public API

Update Time Off Request

Changed on

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

patch/api/v1/time-off/requests/{id}

Request

Path parameters

idinteger required

The time off request ID.

Query parameters

returnActionsboolean

Set to true to include the _links block naming the state transitions available to the caller for this time off request. Also accepts 1, yes and on. Omitted from the response by default.

Request body

categoryIdinteger

The id of the time off category for the request.

startDatestring date

The date the time off starts, in ISO 8601 format (YYYY-MM-DD).

endDatestring date

The date the time off ends (inclusive), in ISO 8601 format (YYYY-MM-DD).

employeeNotestring nullable

A note from the requester. Pass null to clear it. Maximum 1024 characters.

Example request

{
  "categoryId": 22,
  "startDate": "2026-01-01",
  "endDate": "2026-01-03",
  "employeeNote": "Family vacation.",
  "dailyAmounts": [
    {
      "date": "2026-01-01",
      "amount": 8
    }
  ]
}

Response

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

idinteger

The unique identifier for the time off request.

employeeIdinteger

The id of the employee requesting time off.

categoryIdinteger

The id of the time off category for the request.

startDatestring date

The date the time off starts, in ISO 8601 format (YYYY-MM-DD).

endDatestring date

The date the time off ends, in ISO 8601 format (YYYY-MM-DD).

amountnumber

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.

requestedAtstring date-time

UTC timestamp when the time off request was requested.

employeeNotestring nullable

The free-form note left by the employee who requested the time off. Null when never set.

managerNotestring nullable

The manager's note left when the request was approved or denied. Null when never set.

statusUpdatedAtstring date-time nullable

UTC timestamp when the status was last updated. Null when the status has never changed.

statusUpdatedByinteger nullable

The id of the user who last updated the status. Null when the status has never changed.

_linksobject

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.

Example response

{
  "id": 1,
  "employeeId": 43046,
  "categoryId": 22,
  "startDate": "2026-01-01",
  "endDate": "2026-01-01",
  "amount": 3.5,
  "unit": "HOURS",
  "status": "APPROVED",
  "requestedAt": "2026-01-01T06:00:00Z",
  "dailyAmounts": [
    {
      "date": "2026-01-01",
      "amount": 8
    }
  ],
  "employeeNote": "Family trip.",
  "managerNote": "Approved. Enjoy your time off!",
  "statusUpdatedAt": "2026-01-02T17:00:00Z",
  "statusUpdatedBy": 2274,
  "_links": {
    "self": {
      "href": "/api/v1/time-off/requests/{id}"
    },
    "edit": {
      "href": "/api/v1/time-off/requests/{id}",
      "method": "PATCH"
    },
    "cancel": {
      "href": "/api/v1/time-off/requests/{id}/cancellations",
      "method": "POST"
    }
  }
}

Changes