--- 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` ## Request - Base URL: `https://companySubDomain.bamboohr.com` - URL: `https://companySubDomain.bamboohr.com/api/v1/employees/{employeeId}/time_off/request` - Auth: one of: - HTTP basic - OAuth 2 - Authorization code: `/authorize.php` - Token URL: `/token.php` scopes: `time_off.write` - TypeScript: (a function with typed inputs; its response is checked against the schema) 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.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)