Single Dimensional Data

BambooHR system is infinitely customizable. Any number of custom tables and custom fields can be added to an account. This creates some interesting challenges when exposing this data in an API. Rather than use a fixed object model for the BambooHR API, we allow each method call to specify which subset of fields are to be referenced.

Commonly used API fields are documented below. All API field names and their aliases are retrievable through the Metadata API. You are able to reference these API fields by field alias or field ID.

List of Field Names

To view more details about the types for the below fields, click here.

API Field Name Type Description
address1 text The employee's first address line.
address2 text The employee's second address line.
age integer The employee's age. To change age, update dateOfBirth field.
bestEmail email The employee's work email if set, otherwise their home email.
birthday text The employee's month and day of birth. To change birthday, update dateOfBirth field.
city text The employee's city.
country country The employee's country.
dateOfBirth date The date the employee was born.
department list The employee's CURRENT department.
division list The employee's CURRENT division.
eeo list The employee's EEO job category. These are defined by the U.S. Equal Employment Opportunity Commission.
employeeNumber text Employee number (assigned by your company).
employmentHistoryStatus list The employee's CURRENT employment status. Options are customized by account. Read-only starting with version 1.1; update using the employmentStatus table.
ethnicity list The employee's ethnicity.
exempt list The FLSA Overtime Status (Exempt or Non-exempt).
overtimeRate currency The Overtime Rate
firstName text The employee's first name.
flsaCode list Deprecated please use 'exempt'
fullName1 text The employee's first and last name. (e.g., John Doe). Read only.
fullName2 text The employee's last and first name. (e.g., Doe, John). Read only.
fullName3 text The employee's full name and their preferred name. (e.g., Doe, John Quentin (JDog)). Read only.
fullName4 text The employee's full name without their preferred name, last name first. (e.g., Doe, John Quentin). Read only.
fullName5 text The employee's full name without their preferred name, first name first. (e.g., John Quentin Doe). Read only.
displayName text The employee's name displayed in a format configured by the user. Read only.
gender gender The employee's gender (Male or Female).
hireDate date The date the employee was hired.
originalHireDate date The date the employee was originally hired. Available starting with version 1.1.
homeEmail email The employee's home email address.
homePhone phone The employee's home phone number.
id integer The employee ID automatically assigned by BambooHR. Read only.
jobTitle list The CURRENT value of the employee's job title, updating this field will create a new row in position history.
lastChanged timestamp The date and time that the employee record was last changed.
lastName text The employee's last name.
location list The employee's CURRENT location.
maritalStatus list The employee's marital status (Single, Married, or Domestic Partnership).
middleName text The employee's middle name.
mobilePhone phone The employee's mobile phone number.
payChangeReason list The reason for the employee's last pay rate change.
payGroup list The custom pay group that the employee belongs to.
payGroupId integer The ID value corresponding to the pay group that an employee belongs to.
payRate currency The employee's CURRENT pay rate (e.g., $8.25).
payRateEffectiveDate date The day the most recent change was made.
payType pay_type The employee's CURRENT pay type. ie: "hourly","salary","commission","exception hourly","monthly","weekly","piece rate","contract","daily","pro rata".
payPer paid_per The employee's CURRENT pay per. ie: "Hour", "Day", "Week", "Month", "Quarter", "Year".
paidPer paid_per The employee's CURRENT pay per. ie: "Hour", "Day", "Week", "Month", "Quarter", "Year".
paySchedule list The employee's CURRENT pay schedule.
payScheduleId integer The ID value corresponding to the pay schedule that an employee belongs to.
payFrequency list The employee's CURRENT pay frequency. ie: "Weekly", "Every other week", "Twice a month", "Monthly", "Quarterly", "Twice a year", or "Yearly"
includeInPayroll bool Should employee be included in payroll (Yes or No)
timeTrackingEnabled bool Should time tracking be enabled for the employee (Yes or No)
preferredName text The employee's preferred name.
ssn ssn The employee's Social Security number.
sin sin The employee's Canadian Social Insurance Number.
state state The employee's state/province.
stateCode text The 2 character abbreviation for the employee's state (US only). Read only.
status status The employee's employee status (Active or Inactive).
supervisor employee The employee’s CURRENT supervisor. Read only.
supervisorId integer The 'employeeNumber' of the employee's CURRENT supervisor. Read only.
supervisorEmail integer The email address of the employee's CURRENT supervisor. Read only.
supervisorEId integer The ID of the employee's CURRENT supervisor. Read only.
terminationDate date The date the employee was terminated. Read-only starting with version 1.1; update using the employmentStatus table.
workEmail email The employee's work email address.
workPhone phone The employee's work phone number, without extension.
workPhonePlusExtension text The employee's work phone and extension. Read only.
workPhoneExtension text The employee's work phone extension (if any).
zipcode text The employee's ZIP code.
isPhotoUploaded bool Whether a photo has been uploaded for the employee. Read only.
acaStatus text The employee's ACA (Affordable Care Act) Full-Time status. Options are yes, no, non-assessment
acaStatusCategory text The employee's ACA (Affordable Care Act) status.
standardHoursPerWeek integer The number of hours the employee works in a standard week.
bonusDate date The date of the last bonus.
bonusAmount currency The amount of the most recent bonus.
bonusReason list The reason for the most recent bonus.
bonusComment text Comment about the most recent bonus.
commissionDate date The date of the last commission.
commisionDate date This field name contains a typo, and exists for backwards compatibility.
commissionAmount currency The amount of the most recent commission.
commissionComment text Comment about the most recent commission.
employmentStatus status DEPRECATED. Please use "status" instead. The employee's employee status (Active or Inactive).
nickname text DEPRECATED. Please use "preferredName" instead. The employee's preferred name.
payPeriod pay_period DEPRECATED. Please use paySchedule or payFrequency instead. The employee's CURRENT pay period. ie: "Daily", "Weekly", "Every other week", "Twice a month", "Monthly", "Quarterly", "Twice a year", "Yearly".
photoUploaded bool DEPRECATED. Please use "isPhotoUploaded" instead. The employee has uploaded a photo. Read only.
nin nin The employee's NIN number
nationalId national_id The employee's National ID number
nationality list The employee's nationality
employeeStatusDate date The effective date on the employment status table
employeeTaxType text The employee's tax type on the employment status table
allergies text The employee's allergies
dietaryRestrictions text The employee's dietary restrictions
birthplace text The employee's birthplace
secondaryLanguage text The employee's secondary language
probationEndDate date The employee's probation end date
contractEndDate date The employee's contract end date
citizenship country The employee's citizenship
shirtSize list The employee's shirt size
tShirtSize list The employee's t-shirt size
jacketSize list The employee's jacket size
noticePeriod list The employee's notice period
team list The employee's team

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

Add an employee
HTTP Method:
POST
Path:
/api/gateway.php/{company}/v1/employees/
Minimum Required Fields:
firstName, lastName
Success Response:
201 - Additionally, an HTTP Location: header that points to the new API URL for the new employee will be returned.
Failure Responses:
400 - if the posted XML is invalid or the firstName/lastName fields are not provided.

Sample Request:

<employee>
	<field id="firstName">John</field>
	<field id="lastName">Doe</field>
</employee>
Get an employee
HTTP Method:
GET
Path:
/api/gateway.php/{company}/v1/employees/{number}?fields={fieldList}
Parameters:
The {fieldList} is a comma separated list of values taken from the official list of field names. {number} is an employee ID. The special employee ID of zero (0) means to use the employee ID associated with the API key (if any).
Response Format:
The response for this resource is available in XML or JSON format. XML is the default. To request JSON data, set the HTTP header "Accept" to "application/json".
Compatibility Note:
For backwards compatibility reasons the state field has an inconsistent behavior for just this API call. It will not return the full name of a state. Rather, it returns the two character US state abbreviation. For international addresses, the state will either be the plain text name if the user hand entered it, or the 2-3 character state/province abbreviation if they selected it from a drop down.
Success Response:
200 - The response content will be an XML document with the requested information. Any fields that the API user does not have permission to see will be empty in the response.
Failure Responses:

403 - if the API user does not have permission to see the requested employee.

404 - if the employee does not exist.

Sample URL:
https://api.bamboohr.com/api/gateway.php/testcorp/v1/employees/123?fields=firstName,lastName

Sample Response:

<employee id="123">
	<field id="firstName">John</field>
	<field id="lastName">Doe</field>
</employee>
Update an employee
HTTP Method:
POST
Path:
/api/gateway.php/{company}/v1/employees/{number}
Success Response:
200 - A successful response is possible even if one or more updates were dis-allowed because of permissions. As long as a single field is updated a 200 response will be returned.
Failure Responses:

400 - if the provided XML is bad.

403 - if the user doesn't have perms to see the employee.

403 - if the user doesn't have perms to update ANY of the requested fields.

404 - if the employee to be updated doesn't exist.

Sample Request:

<employee>
	<field id="firstName">John</field>
	<field id="lastName">Doe</field>
</employee>
Get a directory of employees
HTTP Method:
GET
Path:
/api/gateway.php/{company}/v1/employees/directory
Response Format:
The response for this resource is available in XML or JSON format. XML is the default. To request JSON data, set the HTTP header "Accept" to "application/json".
Success Response:
200 - The response content will be an XML document with the directory information. Only configured fields will be included in the directory. This directory bypasses normal permissions, and shows information for all employees in the company.
Failure Responses:
403 - if the directory has not been shared company-wide.
Sample URL:
https://api.bamboohr.com/api/gateway.php/testcorp/v1/employees/directory

Sample Response:

<directory>
	<fieldset>
		<field id="displayName">Display name</field>
		<field id="firstName">First name</field>
		<field id="lastName">Last name</field>
		<field id="gender">Gender</field>
		<field id="jobTitle">Job title</field>
		<field id="workPhone">Work Phone</field>
		<field id="workPhoneExtension">Work Extension</field>
		<field id="skypeUsername">Skype Username</field>
		<field id="facebook">Facebook URL</field>
	</fieldset>
	<employees>
		<employee id="123">
			<field id="displayName">John Doe</field>
			<field id="firstName">John</field>
			<field id="lastName">Doe</field>
			<field id="gender">Male</field>
			<field id="jobTitle">Customer Service Representative</field>
			<field id="workPhone">555-555-5555</field>
			<field id="workPhoneExtension"/>
			<field id="skypeUsername">JohnDoe</field>
			<field id="facebook">JohnDoeFacebook</field>
		</employee>
	</employees>
</directory>
Request a company report
HTTP Method:
GET
Path:
/api/gateway.php/{company}/v1/reports/{number}?format={format}&fd={yes|no}
Parameters:
format - the output format for the report. Supported formats: CSV, PDF, XLS, XML, JSON
fd (optional) - yes=apply standard duplicate field filtering, no=return the raw results with no duplicate filtering. Default value is "yes".
Description:
Use this resource to request one of your pre-existing company reports from the reporting section. You can get the report number by hovering over the report name on the reports page and grabbing the ID. At present, only reports from the Company Reports section are supported. In the future we may implement reports from the Report Library section if there is enough demand for it. The report numbers used in this request are different in each company.
Success Response:
200 - The report will be generated in the requested format. The HTTP Content-type header will be set with the mime type for the response.
Failure Response:
404 - if you request a nonexistent report number.

Sample Response:

<report>
	<title>This is my report</title>
	<!-- The "fields" section provides some metadata about the result set -->
	<fields>
		<field id="firstName" type="text" />
		<field id="lastName" type="text" />
	</fields>
	<data>
		<row>
			<!-- See the "fields" section above to determine field order -->
			<field>Jane</field>
			<field>Doe</field>
		</row>
		<row>
			<field>John</field>
			<field>Doe</field>
		</row>
	</data>
</report>
Request a custom report
HTTP Method:
POST
Path:
/api/gateway.php/{company}/v1/reports/custom?format={format}
Supported Formats:
CSV, PDF, XLS, XML, JSON
Description:
Use this resource to request BambooHR generate a report. You must specify a type of either "PDF", "XLS", "CSV", "JSON", or "XML". You must specify a list of fields to show on the report. The list of fields is available here. The custom report will return employees regardless of their status, "Active" or "Inactive". This differs from the UI, which by default applies a quick filter to display only "Active" employees.
Last Changed Filter:

You may specify a filter section with a tag (see below). If you add a filter, then you must provide a date in ISO 8601 format and the report will only include those employees whose records have changed since that time.

Note: Prior to June 2011, last change information was not tracked. Employees who have not changed since that time will always be returned in this API, unless you specify that the filter not include null changed dates. To hide null change dates set includeNull="no", as demonstrated in the example below.

Success Response:
200 - The report will be generated in the requested format. The HTTP Content-type header will be set with the mime type for the response.

Sample Request:

<report>
	<title>This is my report</title>
	<!-- The filters section is optional -->
	<filters>
		<lastChanged includeNull="no">2012-10-17T16:00:00Z</lastChanged>
	</filters>
	<!-- End optional section -->
	<fields>
		<field id="firstName" />
		<field id="lastName" />
	</fields>
</report>

Sample Response: (for XML output)

<report>
	<title>This is my report</title>
	<!-- The "fields" section provides some metadata about the result set -->
	<fields>
		<field id="firstName" type="text" />
		<field id="lastName" type="text" />
	</fields>
	<data>
		<row>
			<!-- See the "fields" section above to determine field order -->
			<field>Jane</field>
			<field>Doe</field>
		</row>
		<row>
			<field>John</field>
			<field>Doe</field>
		</row>
	</data>
</report>
List employee files and categories
HTTP Method:
GET
Path:
/api/gateway.php/{company}/v1/employees/{number}/files/view/
Success Response:
200 - The response content will be an XML document with the requested information. The files will be contained within their category's XML wrapper.
Failure Response:

404 - if no files are found for this employee.

403 - if the API user does not have permission to see the requested employee or the employee's files.

Sample Response:

<employee id="123">
	<category id="1">
		<name>New Hire Docs</name>
		<file id="1234">
			<name>Employee handbook</name>
			<originalFileName>employee_handbook.doc</originalFileName>
			<size>23552</size>
			<dateCreated>2011-06-28 16:50:52</dateCreated>
			<createdBy>John Doe</createdBy>
			<shareWithEmployee>yes</shareWithEmployee>
		</file>
	</category>
	<category id="112">
		<name>Training Docs</name>
	</category>
</employee>
Add an employee file category
HTTP Method:
POST
Path:
/api/gateway.php/{company}/v1/employees/files/categories/
Success Response:
201 - The category was created.
Failure Response:

403 - if the API user does not have permission to create employee categories.

400 - if the posted XML is invalid or there was no category name given.

500 - there was an unknown server error.

Sample Request:

<employee>
    <category>A new category</category>
</employee>
Update an employee file
HTTP Method:
POST
Path:
/api/gateway.php/{company}/v1/employees/{number}/files/{fileId}/
File Attributes That Can Be Updated:
  • name - rename the file
  • categoryId - move the file to a different category
  • shareWithEmployee - update whether this file is shared or not
Success Response:
200 if the file was updated.
Failure Response:

403 - if the API user does not have permission to see the requested employee or the employee's files.

400 - if the posted XML is invalid.

404 - if the employee file or category was not found.

Sample Request:

<file>
	<name>This is a new name for the file</name>
	<categoryId>4</categoryId>
	<shareWithEmployee>no</shareWithEmployee>
</file>
Delete an employee file
HTTP Method:
DELETE
Path:
/api/gateway.php/{company}/v1/employees/{number}/files/{fileId}/
Success Response:
200 if the file was deleted.
Failure Response:

403 - if the API user does not have permission to see the requested employee or the employee's files.

404 - if the employee file was not found.

Sample Request:
DELETE /api/gateway.php/test/v1/employees/40458/files/33
Download an employee file
HTTP Method:
GET
Path:
/api/gateway.php/{company}/v1/employees/{number}/files/{fileId}/
Success Response:
200 - if the file was successfully retrieved. Additionally, HTTP headers are sent that provide the Content-Type, Content-Length, and Content-Disposition for the file. The file contents will be contained in the response contents.
Failure Response:

403 - if the API user does not have permission to see the requested employee or the employee's files.

404 - if the employee file was not found.

Upload an employee file
HTTP Method:
POST
Path:
/api/gateway.php/{company}/v1/employees/{number}/files/
Submission Fields:
  • category - the category ID to place the new file in.
  • fileName - the file name to associate with the file.
  • share - whether to make the file available to the employee (options are "yes" and "no").
  • file - the file to upload. Note that the field must be named "file".
Success Response:
201 - if the file was successfully uploaded.
Failure Response:

403 - if the API user does not have permission to see the requested employee or the employee's files.

404 - if the category ID was not found.

413 - if the file size exceeds 20MB or the storage limit for the company.

Special Notes:
The file upload methods accept multi-part forms. To build a multi-part form concatenate the individual sections together separated by a boundary. Then take the length of the resulting body and use that as the Content-Length for the submission. (See here, here, and here.)

Sample Request: (with HTTP headers shown)

POST /api/gateway.php/sample/v1/employees/1/files/ HTTP/1.0
Host: api.bamboohr.com
Content-Type: multipart/form-data; boundary=----BambooHR-MultiPart-Mime-Boundary----
Content-Length: 520

------BambooHR-MultiPart-Mime-Boundary----
Content-Disposition: form-data; name="category"

112
------BambooHR-MultiPart-Mime-Boundary----
Content-Disposition: form-data; name="fileName"

readme.txt
------BambooHR-MultiPart-Mime-Boundary----
Content-Disposition: form-data; name="share"

yes
------BambooHR-MultiPart-Mime-Boundary----
Content-Disposition: form-data; name="file"; filename="readme.txt"
Content-Type: text/plain

This is a sample text file.

------BambooHR-MultiPart-Mime-Boundary------
List company files and categories
HTTP Method:
GET
Path:
/api/gateway.php/{company}/v1/files/view/
Success Response:
200 - The response content will be an XML document with the requested information. The files will be contained within their category's XML wrapper.
Failure Response:

404 - if no files or categories are found.

403 - if the API user does not have permission to see the company files.

Sample Response:

<files>
 <category id="20">
  <name>New Employee Docs</name>
  <file id="387">
   <name>Direct Deposit Form</name>
   <originalFileName>Direct Deposit Form.rtf</originalFileName>
   <size>57028</size>
   <dateCreated>2009-08-28 15:56:58</dateCreated>
   <createdBy></createdBy>
   <shareWithEmployee>no</shareWithEmployee>
  </file>
 </category>
</files>
Add a company file category
HTTP Method:
POST
Path:
/api/gateway.php/{company}/v1/files/categories/
Success Response:
201 - The category was created.
Failure Response:

403 - if the API user does not have permission to see the company files.

400 - if the posted XML is invalid or there was no category name given.

500 - there was an unknown server error.

Sample Request:

<files>
    <category>A new category</category>
</files>
Update a company file
HTTP Method:
POST
Path:
/api/gateway.php/{company}/v1/files/{fileId}/
File Attributes That Can Be Updated:
  • name - rename the file.
  • categoryId - move the file to a different category.
  • shareWithEmployees - update whether this file is shared or not.
Success Response:
200 - if the file was updated.
Failure Response:

403 - if the API user does not have permission to see the company files.

400 - if the posted XML is invalid.

404 - if the file or category was not found.

Sample Request:

<file>
	<name>This is a new name for the file</name>
	<categoryId>4</categoryId>
	<shareWithEmployees>no</shareWithEmployees>
</file>
Delete a company file
HTTP Method:
DELETE
Path:
/api/gateway.php/{company}/v1/files/{fileId}/
Success Response:
200 if the file was deleted.
Failure Response:

403 - if the API user does not have permission to see the requested file.

404 - if the file was not found.

Sample Request:
DELETE /api/gateway.php/test/v1/files/33
Download a company file
HTTP Method:
GET
Path:
/api/gateway.php/{company}/v1/files/{fileId}/
Success Response:
200 - if the file was successfully retrieved. Additionally, HTTP headers are sent that provide the Content-Type, Content-Length, and Content-Disposition for the file. The file contents will be contained in the response contents.
Failure Response:

403 - if the API user does not have permission to see the company files.

404 - if the file was not found.

Upload a company file
HTTP Method:
POST
Path:
/api/gateway.php/{company}/v1/files/
Submission Fields:
  • category - the category ID to place the new file in.
  • fileName - the file name to associate with the file.
  • share - whether to make the file available to employees (options are "yes" and "no").
  • file - the file to upload. Note that the field must be named "file".
Success Response:
201 - if the file was successfully uploaded.
Failure Response:

403 - if the API user does not have permission to see the company files.

404 - if the category ID was not found.

413 - if the file size exceeds 20MB or the storage limit for the company.

Special Notes:
The file upload methods accept multi-part forms. To build a multi-part form concatenate the individual sections together separated by a boundary. Then take the length of the resulting body and use that as the Content-Length for the submission. (See here, here, and here.)

Sample Request: (with HTTP headers shown)

POST /api/gateway.php/sample/v1/files/ HTTP/1.0
Host: api.bamboohr.com
Content-Type: multipart/form-data; boundary=----BambooHR-MultiPart-Mime-Boundary----
Content-Length: 520

------BambooHR-MultiPart-Mime-Boundary----
Content-Disposition: form-data; name="category"

112
------BambooHR-MultiPart-Mime-Boundary----
Content-Disposition: form-data; name="fileName"

readme.txt
------BambooHR-MultiPart-Mime-Boundary----
Content-Disposition: form-data; name="share"

yes
------BambooHR-MultiPart-Mime-Boundary----
Content-Disposition: form-data; name="file"; filename="readme.txt"
Content-Type: text/plain

This is a sample text file.

------BambooHR-MultiPart-Mime-Boundary------

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