Last Changed

The Last Changed API allows you to discover which employees have been recently added, changed, or deleted. Any change to any field inside an employee record will count as an update. Insert events are only recorded when an employee record is first created. Delete events are only recorded when an employee record is deleted.

Note: Last change timestamps are a newer feature in BambooHR. We started recording these dates on June 5th, 2011. We do not have last changed data for any changes that occurred before this date.

Changed employees
HTTP Method:
/api/gateway.php/{company}/v1/employees/changed/?since={ISO 8601 timestamp}&type={type}
Date Format:

The "since" parameter is an ISO 8601 date in one of the following formats:

  • yyyy-mm-ddThh:mm:ss+hh:mm
  • yyyy-mm-ddThh:mm:ss-hh:mm
  • yyyy-mm-ddThh:mm:ss+hhmm
  • yyyy-mm-ddThh:mm:ss-hhmm
  • yyyy-mm-ddThh:mm:ssZ


  • yyyy=four digit year
  • mm=month 01-12
  • dd=day of month 01-31
  • hh=hour 00-23
  • mm=minute 00-59
  • ss=second 00-59
  • T=literally the letter "T"
  • Z=literally the letter "Z"

The final format is for expressing a time in UTC. The other four formats are for expressing the time as an offset from UTC. In these formats the first two digits are the hours to offset and the last two digits are the minutes. So +02:00 means two hours after UTC.

Example: July 4th, 2011 at 1:05pm Mountain Standard Time would be expressed as: 2011-07-04T13:05:00-07:00

Possible Types (Optional):
Use one of these in the {type} variable in the URL: "inserted", "updated", "deleted"

The response will contain a series of "employee" tags. Each tag represents a single employee that was changed. The "id" attribute is the employee ID that can be used to make additional API calls. There is an "action" attribute that will say whether the employee was "inserted", "updated", or "deleted". There will also be a "lastChanged" attribute that specifies what time the most recent change was to the record. If an employee was updated multiple times, only the time of the most recent change will be reflected in the timestamp.

As a convenience, the outermost "changeList" tag will have a "latest" attribute that identifies the most recent change of all changes returned by the API call. You can use this timestamp as the "since" parameter in a subsequent call to get changes since that the previous call to this API method.

Sample Request:
GET /api/gateway.php/testcorp/v1/employees/changed/?since=2011-06-06T13:00:00%2B02:00

Sample Response:

<changeList latest="2011-06-02T19:26:23+00:00">
	<employee id="3" action="Inserted" lastChanged="2011-06-02T19:26:23+00:00"/>
	<employee id="4" action="Updated" lastChanged="2011-06-02T19:26:23+00:00"/>
	<employee id="5" action="Deleted" lastChanged="2011-06-02T19:26:23+00:00"/>
	<employee id="10" action="Inserted" lastChanged="2011-05-31T22:57:10+00:00"/>

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