API

Overview

The BambooHR API is a RESTful Internet protocol built around making semantically meaningful HTTPS requests to access or modify a resource (usually an employee). The API can be used to manipulate employee data and to generate reports in several formats.

You can build your own HTTPS requests or you can use the language bindings to get you started.

Authentication

Each API request sent from your third party application to the BambooHR website will be authenticated and permissioned as if a real user were using the software. The group permissions of the user associated with the API request will determine what fields and employees each API request is allowed to view and/or edit.

To use the API each user should have one or more secret API keys that identify that user to the API. The API secret key is a 160-bit number expressed in hexadecimal form. This is an astronomically large number of unique keys which means that guessing an API key is nearly impossible.

To generate an API key for a given user, that user should log in and then click their name in the upper right hand corner of any page to get to the user context menu. There will be an "API keys" option in that menu they can click to go to the page.

Using an unknown API key repeatedly will result in the API disabling access to a given company for a period of time. Users will still be able to log into the BambooHR website during this time. When the API is disabled it will send back an HTTP 403 Forbidden reponse to any requests it receives.

At the HTTP level, the API key is sent over HTTP Basic Authentication. Use the secret key as the username and any random string for the password.

Making Requests

  • All requests must be sent over HTTPS. The SSL certificate used for the HTTPS connection is signed and implementations should configure their SSL layer to verify it.
  • API requests are made to a URL that begins with:
    https://api.bamboohr.com/api/gateway.php/{company subdomain name}/.
  • API requests can be throttled if BambooHR deems them to be too frequent. Implementations should always be ready for a 503 Service Unavailable response.
  • Implementations should also always be ready for general Internet packet loss resulting in broken connections with no HTTP response
  • Each employee has an immutable employee id that is unique within a single company that you can use to reference the employee
  • All requests should be in UTF-8.

Understanding users and employees

There are two main entities that you will be concerned about when interacting with BambooHR: Employees and Users

Employees are the core data object in BambooHR. Employees represent the individual employees of a your company. This is where things such us hire dates, addresses, contacts, etc are stored. Employees are identified by an immutable unique employee id.

Users are the people that have been authorized to access BambooHR in some capacity. A user may or may not be an employee. If the user is an employee then you can link the user record to the employee record so that the user can take actions on behalf of themselves. (Such as requesting time off.)

Users are identified by an immutable unique user id. Each user can also have one or more unique API keys. Individual API keys belonging to a user can be revoked while leaving the other keys active.

Compatability Between Versions

Every attempt will be made to make only forward compatible changes to the API. To assist this effort, API consumers should ignore any XML tags and attributes they do no recognize.

The API will support multiple major version numbers of the API. Currently the only version is "v1". Should a major API change be necessary, BambooHR will create a new major version number and do our best to communicate the change to our partners and maintain the existing "v1" API for a reasonable period of time.

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