Create Time Off Request

put

https://{companyDomain}.bamboohr.com/api/v1/employees/{employeeId}/time_off/request

Creates a time off request for an employee. The request can be submitted with a status of approved, denied, or requested. Submitting approved or denied is only honored when the caller is an owner/admin or has view/edit access to the time off type field for the target employee; other callers receive 403. When honored, these statuses record the request directly and suppress approval notifications. Supplying a previousRequest ID performs a destructive supersede: the prior request's status is set to superceded, all approvals on its workflow are removed and the workflow is marked deleted, and any home-page notifications tied to that workflow are deleted. Accepts both JSON and XML request bodies.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Path Params

employeeId

integer

required

The ID of the employee to create the time off request for.

Body Params

status

string

enum

required

The initial status of the request.

Allowed:

start

date

required

Start date in YYYY-MM-DD format.

end

date

required

End date in YYYY-MM-DD format. Must be on or after the start date.

timeOffTypeId

integer

required

The ID of the time off type for this request.

amount

number

Total hours or days requested. Ignored when dates array is provided (sum of daily amounts is used instead).

previousRequest

integer

The ID of a previous time off request to supersede. The previous request will be cancelled.

notes

array of objects

Optional notes from the employee or manager.

notes

dates

array of objects

Optional per-day breakdown. When provided, the top-level amount is ignored and the sum of daily amounts is used.

dates

Headers

content-type

string

enum

Defaults to application/json

Generated from available request content types

Allowed:

Responses

401

Unauthorized. Invalid API credentials.

Language

Credentials

URL

Loading…

Response

Click Try It! to start a request and see the response here! Or choose an example:

application/json

201Request created. The Location header contains the URL of the new request. When Accept: application/json is set, the response body contains the full created request — use the id field to chain follow-up operations (e.g. approve, cancel, supersede) without a separate lookup.

400Malformed JSON or XML, an invalid time off type, an invalid previous request ID, or other invalid request data.

403Forbidden. The caller does not have permission to create or record this request for the employee, time off type, or requested status.

404Employee not found.

422Unprocessable entity. Returned when a remote/EOR time off request cannot be created for the requested action.