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 different 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 a list of tabular fields
HTTP Method:
GET
Path:
/api/gateway.php/{company}/v1/meta/tables/
Sample Request:
GET /api/gateway.php/test/v1/meta/tables/

Sample Response:

<tables>
<table alias="jobInfo">
<field id="4028" alias="date" type="date">Job Information: Date</field>
<field id="18" alias="location" type="list">Location</field>
<field id="4" alias="department" type="list">Department</field>
<field id="1355" alias="division" type="list">Division</field>
<field id="17" alias="jobTitle" type="list">Job title</field>
<field id="91" alias="reportsTo" type="employee">Reporting to</field>
</table>
</fields>
Get the details for "list" fields in an account
HTTP Method:
GET
Path:
/api/gateway.php/{company}/v1/meta/lists/
Description:
This resource will return details for all list fields. Lists that can be edited will have the "manageable" attribute set to yes. Lists with the "multiple" attribute set to yes are fields that can have multiple values. Options with the "archived" attribute set to yes should not appear as current options, but are included so that historical data can reference the value.

Sample Response:

<lists>
<list fieldId="17" alias="department" manageable="yes" multiple="no">
	<name>Department</name>
	<options>
		<option id="1" archived="no">ABC</option>
		<option id="2" archived="no">DEF</option>
	</options>
</list>
</lists>							
Add or update values for "list" fields in an account
HTTP Method:
PUT
Path:
/api/gateway.php/{company}/v1/meta/lists/{number}
Description:
This resource accepts one or more options. To update an option, specify an ID. You may also remove an option from the list of current values by archiving the value. To create a new option, do not specify an "id" attribute.
Successful Response:
200 - A successful response indicates that all the requested changes were made. The content of the response will be the full list of options for the specified listId.
Failure Responses:

400 - if the posted XML is invalid.

404 - if a non-existent list or option ID specified.

409 - if a duplicate value would be created.

In case of an error, no changes to the list are made.

Sample Request:

<!-- Sample request that creates a new option called New Value and archives second value. -->
<options>
<option>New Value</option>
<option id="11412" archived="yes">Updated Value</option>
</options>

Sample Response:

<list fieldId="17" alias="department" manageable="yes" multiple="no">
<name>Department</name>
<options>
	<option id="11412" archived="yes">Updated Value</option>
	<option id="11422" archived="no">New Value</option>
</options>
</list>
Get a list of time off types
HTTP Method:
GET
Path:
/api/gateway.php/{company}/v1/meta/time_off/types/
GET Variables:
  • mode (optional) - set to "request" to get a list of all time off types with which this user can create a time off request. The default is to return the list of time off types the user has permissions on. This distinction is important, as employees can request time off for types that they don't have permission to view balances and requests for.

Sample Response:

<timeOffTypes>
	<timeOffType id="1">
		<name>Vacation</name>
		<units>days</units>
		<color>4aada4</color>
		<icon>time-off-luggage</icon>
	</timeOffType>
	<defaultHours>
		<weekDay name="Saturday" amount="0"/>
		<weekDay name="Sunday" amount="0"/>
		<weekDay name="default" amount="8"/>
	</defaultHours>
</timeOffTypes>
Get a list of time off Policies
HTTP Method:
GET
Path:
/api/gateway.php/{company}/v1/meta/time_off/policies/

Sample Response:

<timeOffPolicies>
	<timeOffPolicy id="1">
		<timeOffTypeId>4</timeOffTypeId>
		<name>Vacation</name>
		<effectiveDate>2012-02-01</effectiveDate>
		<type>accruing</type>
	</timeOffPolicy>
	<timeOffPolicy id="2">
		<timeOffTypeId>10</timeOffTypeId>
		<name>Sick Time</name>
		<effectiveDate>2012-02-01</effectiveDate>
		<type>manual</type>
	</timeOffPolicy>
	<timeOffPolicy id="3">
		<timeOffTypeId>10</timeOffTypeId>
		<name>Executive Sick Time</name>
		<effectiveDate>2012-02-01</effectiveDate>
		<type>discretionary</type>
	</timeOffPolicy>
</timeOffPolicies>
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>[email protected]</email>
		<lastLogin>2011-03-19T10:16:00+00:00</lastLogin>
	</user>
	<user id="2">
		<firstName>Jane</firstName>
		<lastName>Doe</lastName>
		<email>[email protected]</email>
		<lastLogin>2011-08-29T11:17:43+00:00</lastLogin>
	</user>
</users>

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