Tabular Data

Some data in the BambooHR system is stored as a two dimensional grid for each employee. The tables API allows you to grab tabular data for the various tables in BambooHR. For standard tables, a series of fields will be outlined below. API support for custom tables will be added in a future release.

Supported standard tables

The following standard tables can be used with the Tables API:

Job Info Table

Table reference name: jobInfo

Columns Type
date date
location list
division list
department list
jobTitle list
reportsTo employee
Employment Status Table

Table reference name: employmentStatus

Columns Type
date date
employmentStatus list
terminationTypeId list
terminationReasonId list
terminationRehireId list
comment* text
Version 1.1 Notes

The employment status table will be used to track the employment history going forward. In addition, this is where termination information is now tracked.

Terminating and rehiring an employee can be done through updating the employment status table. This table will recognize these events at the appropriate effective date when v1.1 is used.

When an employee is rehired we will move the hire date to a new field called original hire date, and the hire date will be updated to the rehire date.

Note: There are two employment status list values that are permanent and can’t be edited: Terminated and Contractor.

The date and employmentStatus fields are now required.

The terminationTypeId, terminationReasonId, and terminationRehireId fields are now required whenever employmentStatus contains a terminated status.

Compensation Table

Table reference name: compensation

Columns Type
startDate date
endDate date (only used for TRAX enabled accounts)
rate currency
type "hourly","salary","commission","exception hourly","monthly","weekly","piece rate","contract","daily","pro rata"
reason list
comment* text
paidPer "Hour", "Day", "Week", "Month", "Quarter", "Year"
payPeriod "Daily", "Weekly", "Every other week", "Twice a month", "Monthly", "Quarterly", "Twice a year", "Yearly"
Dependents Table

Table reference name: dependents

Columns Type
firstName text
middleName text
lastName text
relationship "spouse","child","domestic partner"
gender "male","female"
ssn ssn
sin sin (only used in accounts where Social Insurance Number is enabled)
dateOfBirth date
country country
addressLine1 text
addressLine2 text
city text
state state
zipcode text
homePhone phone
Emergency Contacts Table

Table reference name: emergencyContacts or contacts

Columns Type
name text
relationship list
homePhone phone
mobilePhone phone
workPhone phone
workPhoneExtension text
email email
country country
addressLine1 text
addressline2 text
city text
state text
zipcode text
Custom Tables

In addition, custom tables are now accessible by an alias. In general, an alias for a custom table will be "customTableName" if the custom table's name is "Table Name". In the case of duplicate table names, a numeric suffix will be appended: "customTableName", "customTableName1", etc. These aliases are stable, and can be discovered through the Metadata API.

Comment Fields

* Comment fields bypass the normal permissions system. They are never accessible to self-service users. They are always accessible to full users as long as those users are allowed to see a given employee.

Get a table
HTTP Method:
GET
Path:
/api/gateway.php/{company}/v1/employees/{employee id}/tables/{table name}
Description:

Returns a data structure representing all the table rows for a given employee and table combination. The result is not sorted in any particular order.

New feature: You may now specify a special employee ID of "all", which will cause the API to return all rows for all employees in the table. When specifying "all" employees, the result will include inactive and terminated employees. As with all other API methods, the list of employees shown is still filtered based on the permissions of the user that makes the API request. To get a list of all table data for all employees, make sure to use the API key of a user that has permission to view all the data.

Sample URL:
GET https://api.bamboohr.com/api/gateway.php/testcorp/v1/employees/100/tables/jobInfo/

Sample Response:

<table>
	<row id="1" employeeId="100">
		<field id="date">2010-06-01</field>
		<field id="location">New York Office</field>
		<field id="division">Sprockets</field>
		<field id="department">Research and Development</field>
		<field id="jobTitle">Machinist</field>
		<field id="reportsTo">John Smith</field>
	</row>
	<row id="2" employeeId="100">
		<field id="date">2009-03-01</field>
		<field id="location">New York Office</field>
		<field id="division">Sprockets</field>
		<field id="department">Sales</field>
		<field id="jobTitle">Salesman</field>
		<field id="reportsTo">Jane Doe</field>
	</row>
</table>	
Update a row
HTTP Method:
POST
Path:
/api/gateway.php/{company}/v1/employees/{employee id}/tables/{table name}/{row id}

Sample POST Data:

<row>
	<field id="date">2010-06-01</field>
	<field id="location">New York Office</field>
	<field id="division">Sprockets</field>
	<field id="department">Research and Development</field>
	<field id="jobTitle">Machinist</field>
	<field id="reportsTo">John Smith</field>
</row>
Update a row, Version 1.1
Note:
You'll notice the interface for updating a row is the same in version 1.1 as in version 1.0, but the behavior of some fields will be different. See the table sections above for details.
HTTP Method:
POST
Path:
/api/gateway.php/{company}/v1_1/employees/{employee id}/tables/{table name}/{row id}

Sample POST Data:

<row>
	<field id="date">2010-06-01</field>
	<field id="location">New York Office</field>
	<field id="division">Sprockets</field>
	<field id="department">Research and Development</field>
	<field id="jobTitle">Machinist</field>
	<field id="reportsTo">John Smith</field>
</row>
Add a row
HTTP Method:
POST
Path:
/api/gateway.php/{company}/v1/employees/{employee id}/tables/{table name}

Sample POST Data:

<row>
	<field id="date">2010-06-01</field>
	<field id="location">New York Office</field>
	<field id="division">Sprockets</field>
	<field id="department">Research and Development</field>
	<field id="jobTitle">Machinist</field>
	<field id="reportsTo">John Smith</field>
</row>
Add a row, Version 1.1
Note:
You'll notice the interface for adding a row is the same in version 1.1 as in version 1.0, but the behavior of some fields will be different. See the table sections above for details.
HTTP Method:
POST
Path:
/api/gateway.php/{company}/v1_1/employees/{employee id}/tables/{table name}

Sample POST Data:

<row>
	<field id="date">2010-06-01</field>
	<field id="location">New York Office</field>
	<field id="division">Sprockets</field>
	<field id="department">Research and Development</field>
	<field id="jobTitle">Machinist</field>
	<field id="reportsTo">John Smith</field>
</row>
Get tables for changed employees
HTTP Method:
GET
Path:
/api/gateway.php/{company}/v1/employees/changed/tables/{table name}?since={url encoded iso8601 timestamp}
Sample URL (Unencoded):
https://api.bamboohr.com/api/gateway.php/testcorp/v1/employees/changed/tables/jobInfo?since=2012-19-29T11:53:05Z
Sample URL (After URL Encoding):
https://api.bamboohr.com/api/gateway.php/testcorp/v1/employees/changed/tables/jobInfo?since=2012-19-29T11%3A53%3A05Z
Note:
This API is merely an optimization to avoid downloading all table data for all employees. When you use this API you will provide a timestamp and the results will be limited to just the employees that have changed since the time you provided. This API operates on an employee-last-changed-timestamp, which means that a change in ANY field in the employee record will cause ALL of that employee's table rows to show up via this API.

Sample Response:

<table id="jobInfo">
	<employee id="123" lastChanged="2012-10-29T11:54:00Z">
		<row>
			<field id="date">2010-06-01</field>
			<field id="location">New York Office</field>
			<field id="division">Sprockets</field>
			<field id="department">Research and Development</field>
			<field id="jobTitle">Machinist</field>
			<field id="reportsTo">John Smith</field>
		</row>
		<row>
			<field id="date">2009-06-01</field>
			<field id="location">New York Office</field>
			<field id="division">Sprockets</field>
			<field id="department">Research and Development</field>
			<field id="jobTitle">Shop hand</field>
			<field id="reportsTo">John Smith</field>
		</row>
	</employee>
	<employee id="456">
		<row>
			<field id="date">2005-03-01</field>
			<field id="location">Los Angelos Office</field>
			<field id="division">Marketing</field>
			<field id="department">Creative</field>
			<field id="jobTitle">Designer</field>
			<field id="reportsTo">Jane Doe</field>
		</row>
	</employee>
</table>

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