BAbamboohr
Time Off
Public API

Create Time Off Request

Changed on

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

post/api/v1/time-off/requests

Request

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

employeeIdinteger required

The id of the employee the time off is requested for.

categoryIdinteger required

The id of the time off category for the request.

startDatestring date required

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

endDatestring date required

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

employeeNotestring nullable

An optional note from the requester. Maximum 1024 characters.

amountnumber 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'.

Example request

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

Response

The time off request was created.

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