Sign in

v1

latestOpenAPI 3.1.02026-07-26294215839.4 KB
Time Off
Public API

Create 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

put/api/v1/employees/{employeeId}/time_off/request

Path parameters

employeeIdstring required

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

Request body

status'approved' | 'denied' | 'declined' | 'requested' required

The initial status of the request.

startstring date required

Start date in YYYY-MM-DD format.

endstring date required

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

timeOffTypeIdstring required

The ID of the time off type for this request.

amountnumber

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

previousRequeststring

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

Response

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.

idinteger

The newly created time off request ID. Use this to chain follow-up operations such as approving, canceling, or superseding the request.

employeeIdinteger

The internal employee ID of the employee the request was created for.

namestring

The employee's full name. Only present when the employee record could be loaded.

startstring date

The start date of the request in YYYY-MM-DD format.

endstring date

The end date of the request in YYYY-MM-DD format.

createdstring date

The date the request was created in YYYY-MM-DD format (company timezone).

datesobject

A map of dates (YYYY-MM-DD) to daily amounts. Only present when daily details were attached to the request.

commentsobject[]

Comments attached to the request. Always present; empty array when no comments exist.

actionsobject

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.

overlappingRequestsobject[]

Other existing time off requests whose date ranges overlap this request. Only present when overlap data was loaded with the request.

policyTypestring

The policy type backing this request (e.g. accruing, manual, unlimited).

usedYearToDatenumber nullable

Amount of this time off type the employee has used year-to-date as of the request date.

balanceOnDateOfRequestnumber nullable

The employee's balance for this time off type on the date of the request.

Example response

{
  "id": 1668
}