API

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:
  • 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","declined","superceded","requested","canceled"
Notes:
  • The response will be limited to those employees & 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.
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-01</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>		
	</request>
</requests>

Add a 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.
HTTP Method: PUT
Path: /api/gateway.php/{company}/v1/employees/{employee id}/time_off/request/
Sample request: PUT /api/gateway.php/test/v1/employees/1/time_off/request/
Sample post data 
<request>
	<status>approved</status>
	<start>2011-10-01</start>
	<end>2011-10-02</end>
	<timeOffTypeId>1</timeOffTypeId>	
	<amount>2</amount>	
	<notes>
		<note from="employee">Having wisdom teeth removed.</note>
		<note from="manager">Get well soon</note>
	</notes>
</request>
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.

Add a time off history entry

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.
HTTP Method: PUT
Path: /api/gateway.php/{company}/v1/employees/{employee id}/time_off/history/
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>
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.

Add a time off history override

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.
HTTP Method: PUT
Path: /api/gateway.php/{company}/v1/employees/{employee id}/time_off/history/
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>
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.

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