Time off

There are two primary entities when dealing with time off. The requests and the history.

Requests represent a request from an employee to take time off. A request needs to be approved before it will be recorded into the history. A user with sufficient permissions can create a request and mark it approved at the same time.

The history is log of all events that effect an employee's balance. The current balance of time off is the sum of all events in the history. Time off used decreases the total, while time off accruals increase it.

Get time off requests
HTTP Method:
GET
Path:
/api/gateway.php/{company}/v1/time_off/requests/
Parameters (combine as many different filters as you like):
  • id (optional) - A particular request ID to limit the response to.
  • action (optional, defaults to "view") - Limit to requests that the user has a particular level of access to. Legal values are: "view" or "approve".
  • employeeId (optional) - A particular employee ID to limit the response to.
  • start (optional) - Only show time off that occurs on/after the specified start date.
  • end (optional) - Only show time off that occurs on/before the specified end date.
  • type (optional) - A comma separated list of time off types IDs to include limit the response to. If omitted, requests of all types are included.
  • status (optional) - A comma separated list of request status values to include. If omitted, requests of all status values are included. Legal values are "approved", "denied", "superceded", "requested", "canceled".
Notes:

The response will be limited to those employees and time off types that the owner of the API key used to make the request has view access to.

When using start and/or end dates the time off will show up if any day in the time off request falls within the dates specified, even if part of time off falls outside of the time specified.

Clients should be ready for any number of "note" elements.

If there are zero notes for a request then the "notes" tag will not be included in the response.

Newer time off requests may also include details for each day of the request in a <dates> element.

Sample Request:
GET /api/gateway.php/test/v1/time_off/requests/?start=2011-09-01&end=2011-09-11&type=1&status=approved

Sample Response:

<requests>
	<request id="1">
		<employee id="1">Jon Doe</employee>
		<status lastChanged="2011-08-14" lastChangedByUserId="1">approved</status>
		<start>2001-01-01</start>
		<end>2001-01-06</end>
		<created>2011-08-13</created>
		<type id="1">Vacation</type>
		<amount unit="days">5</amount>
		<notes>
			<note from="employee">Relaxing in the country for a few days.</note>
			<note from="manager">Have fun!</note>
		</notes>
		<dates> <!-- This element may not be available for all requests -->
			<date ymd="2001-01-01" amount="1"/>
			<date ymd="2001-01-02" amount="1"/>
			<date ymd="2001-01-03" amount="1"/>
			<!-- dates with a 0 amount may not be included in the results. Included here for clarity -->
			<date ymd="2001-01-04" amount="0"/>
			<date ymd="2001-01-05" amount="1"/>
			<date ymd="2001-01-06" amount="1"/>
		</dates>
	</request>
</requests>	
Add a time off request
HTTP Method:
PUT
Path:
/api/gateway.php/{company}/v1/employees/{employee id}/time_off/request/
Description:
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.
Notes:

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 <dates></dates> 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 <amount></amount> 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.

Sample Request:
PUT /api/gateway.php/test/v1/employees/1/time_off/request/

Sample PUT data:

<request>
	<status>approved</status>
	<start>2011-10-01</start>
	<end>2011-10-02</end>
	<timeOffTypeId>1</timeOffTypeId>
	<amount>12</amount>
	<notes>
		<note from="employee">Having wisdom teeth removed.</note>
		<note from="manager">Get well soon</note>
	</notes>
	<!-- Dates section is optional, added Q1 2014 -->
	<dates>
		<date ymd="2011-10-01" amount="8" />
		<date ymd="2011-10-02" amount="4" />
	</dates>
	<previousRequest>10</previousRequest> <!-- Optional -->
</request>	
Change a request status
HTTP Method:
PUT
Path:
/api/gateway.php/{company}/v1/time_off/requests/{id}/status/
Description:
This API allows you to change the status of a request in the system. You can use this to approve, deny, or cancel a time off request.
Success Response:
200 - The status has been updated.
Failure Response:

400 - if the posted XML is invalid or the status is not "approved", "denied", "canceled", or "declined".

403 - if the current user doesn't have access to change the status in this way.

404 - if the time off request ID doesn't exist.

Notes:

Accepted status values are: "approved", "denied" (or "declined"), "canceled".

Any email alerts that would normally be triggered by the web UI will be triggered by the use of this API.

The note provided will be used as the manager's note if the status is approved or denied.

Sample Request:
PUT /api/gateway.php/test/v1/time_off/requests/10/status/

Sample POST Data:

<request>
	<status>approved</status>
	<note>Have fun!</note>
</request>	
Add a time off history entry
HTTP Method:
PUT
Path:
/api/gateway.php/{company}/v1/employees/{employee id}/time_off/history/
Description
To use this API make an HTTP PUT where the body of the request is the XML documented below. A new time off history item will be inserted into the database. On success, a 201 Created code is returned and the "Location" header of the response will contain a URL that identifies the new request.
Notes:

By convention, the date of the history item should be the first date of the time off range.

The date is specified in the form YYYY-MM-DD.

You may attach 1 note to the history item.

Sample Request:
PUT /api/gateway.php/test/v1/employees/1/time_off/history/

Sample POST Data:

<history>
	<date>2011-10-18</date>
	<eventType>used</eventType>
	<timeOffRequestId>1</timeOffRequestId>
	<note>Having wisdom teeth removed.</note>
</history>	
List assigned Time Off Policies for an Employee
HTTP Method:
GET
Path:
/api/gateway.php/{company}/v1/employees/{employee id}/time_off/policies/

Sample Response:

[
	{
		"timeOffPolicyId": 4,
		"timeOffTypeId": 1,
		"accrualStartDate": "2012-02-01"
	},
	{
		"timeOffPolicyId":5,
		"timeOffTypeId": 2,
		"accrualStartDate": "2013-02-01"
	}
]	
List assigned Time Off Policies for an Employee, Version 1.1
HTTP Method:
GET
Path:
/api/gateway.php/{company}/v1_1/employees/{employee id}/time_off/policies/
Note:
For Manual and Discretionary policies, the accrual start date will be "0000-00-00"

Sample Response:

[
	{
		"timeOffPolicyId": 4,
		"timeOffTypeId": 1,
		"accrualStartDate": "2012-02-01"
	},
	{
		"timeOffPolicyId":5,
		"timeOffTypeId": 2,
		"accrualStartDate": "0000-00-00"
	}
]	
Assign Time Off Policies for an Employee
HTTP Method:
PUT
Path:
/api/gateway.php/{company}/v1/employees/{employee id}/time_off/policies/
Description:
To use this API make an HTTP PUT where the body of the request is the JSON documented below. A time off policy will be assigned to the employee with accruals starting on the date specified. A null start date will remove the assignment. On success, a 200 Success code is returned and the content of the response will be the same as the List Time off Policies API.
Notes:

You may only assign time off policies to employees with hire dates.

The Accrual Start date must be later than the Employees PTO Hire Date.

Sample POST Data:

[
	{
		"timeOffPolicyId": 4,
		"timeOffTypeId": 2,
		"accrualStartDate": "2012-02-01"
	},
	{
		"timeOffPolicyId":5,
		"timeOffTypeId": 8,
		"accrualStartDate": null
	}
]	
Assign Time Off Policies for an Employee, Version 1.1
HTTP Method:
PUT
Path:
/api/gateway.php/{company}/v1_1/employees/{employee id}/time_off/policies/
Description:
To use this API make an HTTP PUT where the body of the request is the JSON documented below. A time off policy will be assigned to the employee with accruals starting on the date specified. On success, a 200 Success code is returned and the content of the response will be the same as the List Time off Policies API.
Notes:

You may only assign time off policies to employees with hire dates.

The Accrual Start date must be later than the Employees PTO Hire Date.

Unlike the previous version all policies must have an accrual start date.

Sample POST Data:

[
	{
		"timeOffPolicyId": 4,
		"timeOffTypeId": 2,
		"accrualStartDate": "2012-02-01"
	},
	{
		"timeOffPolicyId":5,
		"timeOffTypeId": 8,
		"accrualStartDate": "2015-12-15"
	}
]	
Add a time off history override
HTTP Method:
PUT
Path:
/api/gateway.php/{company}/v1/employees/{employee id}/time_off/history/
Description:
To use this API make an HTTP PUT where the body of the request is the XML documented below. A new time off history item will be inserted into the database. On success, a 201 Created code is returned and the "Location" header of the response will contain a url that identifies the new request.
Notes:

By convention, the date of the history item should be the first date of the time off range.

The date is specified in the form YYYY-MM-DD.

You may attach 1 note to the history item.

Sample Request:
PUT /api/gateway.php/test/v1/employees/1/time_off/history/

Sample POST Data:

<history>
	<date>2011-10-18</date>
	<eventType>override</eventType>
	<timeOffTypeId>1</timeOffTypeId>
	<amount>-5</amount>
	<note>Having wisdom teeth removed.</note>
</history>	
Estimate future time off balances
HTTP Method:
GET
Path:
/api/gateway.php/{company}/v1/employees/{employee id}/time_off/calculator/?end={end date}
Description:
This API will sum future time off accruals, scheduled time off, and carry-over events to produce estimates for the anticipated time off balance on a given date in the future.
Notes:

The results will only contain time off types that the API user is authorized to see.

The date is specified in the form YYYY-MM-DD.

Sample Request:
GET /api/gateway.php/test/v1/employees/1/time_off/requests/?end=2013-12-31

Sample Response Data:

<estimates end="2013-12-31">
 <estimate timeOffType="5" name="Bereavement" units="hours" balance="-2.5" policyType="discretionary" usedYearToDate="2.5"/>
 <estimate timeOffType="6" name="Jury duty" units="days" balance="-1.0" policyType="manual" usedYearToDate="5.0"/>
 <estimate timeOffType="2" name="Sick" units="hours" balance="16.0" policyType="accruing" usedYearToDate="24.0"/>
 <estimate timeOffType="1" name="Vacation" units="hours" balance="40.0" policyType="accruing" usedYearToDate="76.0"/>
</estimates>							
Get a list of who's out, including company holidays
HTTP Method:
GET
Path:
/api/gateway.php/{company}/v1/time_off/whos_out/
Description:
This API will return a list, sorted by date, of employees who will be out, and company holidays, for a period of time.
Parameters:
  • start (optional) - a date in the form YYYY-MM-DD - defaults to the current date.
  • end (optional) - a date in the form YYYY-MM-DD - defaults to 14 days from the start date.
Notes:

The results may contain time off elements for which the API user cannot request details.

The dates are specified in the form YYYY-MM-DD.

Sample Request:
GET /api/gateway.php/test/v1/time_off/whos_out/?start=2012-11-15

Sample Response Data:

<calendar>
 <item type="timeOff">
   <request id="559"/>
   <employee id="1608">John Smith</employee>
   <start>2012-11-16</start>
   <end>2012-11-17</end>
 </item>
 <item type="holiday">
   <holiday id="35">Thanksgiving Day</holiday>
   <start>2012-11-22</start>
   <end>2012-11-22</end>
 </item>
</calendar>	

Have more questions? We're here to help, so please contact us.