API

Metadata

The Metadata API allows you to retrieve "data about data" for a given BambooHR account. You can determine what fields a customer is using. You can determine what options are available in a list. You can determine what users are able to access the system.

Metadata is important because BambooHR is highly configurable. A given customer's account may have drastically settings from another customer. Using this API you can determine what values the account supports.

Read only access to metadata does not require any special permissions. When write access to metadata is supported then the user will need the appropriate permissions to create new users, for example.

Get a list of fields

HTTP Method: GET
Path: /api/gateway.php/{company}/v1/meta/fields/
Sample request: GET /api/gateway.php/test/v1/meta/fields/
Sample response: 
<fields>
	<field id="1" type="text" alias="firstName">First name</field>
	<field id="2" type="text" alias="lastName">Last name</field>
	<field id="3" type="list">My custom list</field>
</fields>

Get the details for "list" fields in an account

HTTP Method: GET
Path: /api/gateway.php/{company}/v1/meta/lists/
Sample response: 
<lists>
	<list fieldId="17" alias="department">
		<name>Department</name>
		<options>
			<option value="1">ABC</option>
			<option value="2">DEF</option>
		</options>
	</list>
</lists>

Get a list of time off types

HTTP Method: GET
Path: /api/gateway.php/{company}/v1/meta/time_off/types/
Sample response: 
<timeOffTypes>
	<timeOffType id="1">
		<name>Vacation</name>
		<units>Days</units>
	</timeOffType>
</timeOffTypes>

Get a list of users

HTTP Method: GET
Path: /api/gateway.php/{company}/v1/meta/users/
Notes:
  • The "employeeId" attribute will only be set if the user record is linked to an employee record.
  • The last login date/time is formatted according to ISO 8601
Sample response: 
<users>
	<user id="1" employeeId="1">
		<firstName>John</firstName>
		<lastName>Doe</lastName>
		<email>john.doe@bamboohr.com</email>
		<lastLogin>2011-03-19T10:16:00+00:00</lastLogin>		
	</user>
	<user id="2">
		<firstName>Jane</firstName>
		<lastName>Doe</lastName>
		<email>jane.doe@bamboohr.com</email>
		<lastLogin>2011-08-29T11:17:43+00:00</lastLogin>
	</user>
</users>

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