Add a Time Off Request

A time off request is an entity that describes the decision making process for approving time off. Once a request has been created, a history entry can be created documenting the actual use of time off.

Sample Request

   "status": "approved",
   "start": "2011-10-01",
   "end": "2011-10-02",
   "timeOffTypeId": "1",
   "amount": "12",
   "notes": [
         "from": "employee",
         "note": "Having wisdom teeth removed."
         "from": "manager",
         "note": "Get well soon"
   "dates": [
         "ymd": "2011-10-01",
         "amount": "8"
         "ymd": "2011-10-02",
         "amount": "4"
   "previousRequest": "10"


The "type" parameter is there to allow for future additions to the API. At present the only valid value for this field is "used".

The time off type IDs in a given company can be looked up using the Metadata API.

The date of the history item should be in the form YYYY-MM-DD.

The amount is a decimal number indicating the number of days/hours to update the employee's balance by. You can not specify the units to add. The unit will be whatever the time off type is configured for.

You may attach one note from the manager and one note from the employee to the history item. In the future additional notes may be supported.

The possible status values are: "approved", "denied" (or "declined"), "requested".

If you supply the "previousRequest" parameter with a valid "time off request ID" then the original request will be canceled and the new request will be marked as its successor. This allows you to change a request that has already been approved. A request can be changed any time before the start date of the time off. The new request must list the same employee ID as the original request.

The section is optional. If you don't provide it then all of the time off for the request will be deducted on the first day of the request.

If you do provide details for the dates, then the section for the overall request is ignored and the total amount of time requested is simply the sum of the amounts for each day.

A successful request will get an empty response with a 201 HTTP status code.

Click Try It! to start a request and see the response here!