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
- Employees
- Reports
- Employee Files
- Company Files
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 | 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 | 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 | 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 |
createdByUserId | integer | The user id of who created the employee |
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.
We use cookies to improve your browsing experience. By continuing to use this website, you agree to our use of cookies in accordance with our privacy policy.