--- title: "Create Time Off Request" method: PUT path: "/api/v1/employees/{employeeId}/time_off/request" tags: ["Time Off", "Public API"] --- # Create Time Off Request `PUT /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. OAuth Scopes: time_off.write ## Path parameters - `employeeId` string, required ## Request body - TimeOffRequest - `status` 'approved' | 'denied' | 'declined' | 'requested', required — The initial status of the request. - `start` string, date, required — Start date in YYYY-MM-DD format. - `end` string, date, required — End date in YYYY-MM-DD format. Must be on or after the start date. - `timeOffTypeId` string, 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` string — The ID of a previous time off request to supersede. The previous request will be cancelled. - `notes` object[] — Optional notes from the employee or manager. - `from` 'employee' | 'manager' — Who the note is from. - `note` string — The note text. - `dates` object[] — Optional per-day breakdown. When provided, the top-level `amount` is ignored and the sum of daily amounts is used. - `ymd` string, date — Date in YYYY-MM-DD format. - `amount` number — Hours or days for this date. ## Response `201` Request 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. - object - `id` integer — The newly created time off request ID. Use this to chain follow-up operations such as approving, canceling, or superseding the request. - `employeeId` integer — The internal employee ID of the employee the request was created for. - `name` string — The employee's full name. Only present when the employee record could be loaded. - `start` string, date — The start date of the request in YYYY-MM-DD format. - `end` string, date — The end date of the request in YYYY-MM-DD format. - `created` string, date — The date the request was created in YYYY-MM-DD format (company timezone). - `status` object — The current status of the request. - `status` string — The current status value (e.g. `approved`, `denied`, `requested`). - `lastChanged` string — The date and time the status was last changed, formatted as `YYYY-MM-DD HH:MM:SS` in the company timezone. - `lastChangedByUserId` integer — The user ID who last changed the status. - `type` object — The time off type for this request. Only present when the underlying time off type record could be loaded. - `id` integer — The time off type ID. - `name` string — The time off type name. - `amount` object — The amount of time off requested. Only present when the underlying time off type record could be loaded. - `unit` 'hours' | 'days' — The unit of measurement. - `amount` number — The total amount requested. - `dates` object — A map of dates (YYYY-MM-DD) to daily amounts. Only present when daily details were attached to the request. - `notes` object — Notes from employee and/or manager. The object is always present; the `employee` and `manager` keys are each included only when a non-empty note was provided. - `employee` string — Note from the employee. - `manager` string — Note from the manager. - `comments` object[] — Comments attached to the request. Always present; empty array when no comments exist. - `approvers` EmployeeTimeOffRequestApproverResponse[] — The approval chain for this request. Only present when the request has approvers. - object[] — List of time off request approvers - `userId` integer, required — User ID of the approver - `displayName` string, required — Display name of the approver - `employeeId` integer, required — Employee ID of the approver - `photoUrl` string, nullable — URL to the approver's photo - `actions` object — Actions the current user can perform on this request. Only present when PTO action permissions are available. Keys are restricted to `view`, `edit`, `cancel`, `approve`, `deny`, `bypass`; values are booleans. - `overlappingRequests` object[] — Other existing time off requests whose date ranges overlap this request. Only present when overlap data was loaded with the request. - `policyType` string — The policy type backing this request (e.g. accruing, manual, unlimited). - `usedYearToDate` number, nullable — Amount of this time off type the employee has used year-to-date as of the request date. - `balanceOnDateOfRequest` number, nullable — The employee's balance for this time off type on the date of the request. ## Other responses - `400` — Malformed JSON or XML, an invalid time off type, an invalid previous request ID, or other invalid request data. - `401` — Unauthorized. Invalid API credentials. - `403` — Forbidden. The caller does not have permission to create or record this request for the employee, time off type, or requested status. - `404` — Employee not found. - `422` — Unprocessable entity. Returned when a remote/EOR time off request cannot be created for the requested action. --- [API](https://skmtc.net/bamboohr/apis/bamboohr-api.md) · [All operations](https://skmtc.net/bamboohr/apis/bamboohr-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/bamboohr/bamboohr-api/revisions/19ebf391a399/schema)