BambooHR API

We think sharing is a good thing. Our open API makes it easy to integrate other applications into BambooHR so data can be shared across systems.

Easy to access. Easy to modify.

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

  • Single Dimensional Data

    The BambooHR system is infinitely customizable. Add as many custom tables and fields as you like.

  • Tabular Data

    The Tables API allows you to grab tabular data for the various tables in BambooHR.

  • Photos

    BambooHR has a standard API-based mechanism for retrieving the photo binary data.

  • Last Change Information

    The Last Changed API allows you to discover which employees have recently been added, changed or deleted.

  • Webhooks

    Webhooks allow you to monitor changes made in the BambooHR system.

  • Field Types

    The BambooHR system supports several field types while requiring as few API lookup calls as possible.

  • Time Off

    There are two primary entries when dealing with time off: employee requests and history (a log of all events that affect an employee’s balance).

  • Metadata

    The Metadata API allows you to get data about data so you can learn what is being used and what values the account supports.

  • Login

    The Login API is an alternative method to get an API key that identifies a particular user.

  • Language Bindings

    While our RESTful interface requires very little in the way of application bindings, BambooHR bindings are open sourced.

Authentication

Each API request sent from a 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 which 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, users should log in and 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 to go to the page.

If an unknown API key is used repeatedly, the API will disable access for a period of time. Users will still be able to log in to the BambooHR website during this time. When the API is disabled, it will send back an HTTP 403 Forbidden response 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.

To use curl to make an API request, try:

curl -i -u '{API Key}:x' https://api.bamboohr.com/api/gateway.php/{subdomain}/v1/employees/directory
					

Making Requests

  • All requests made to our APIs must be sent over HTTPS. The SSL certificate used for the HTTPS connection is signed and all 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.

HTTP Status Codes

Every request includes an HTTP status code with the result. The status code should be examined before the response.

Successful status codes (2xx)
  • 200 OK - The request was successful.
  • 201 Created - The resource was successfully created. Confirms a success when creating a new employee, time off request, etc.
Client error status codes (4xx)
  • 400 Bad Request - The request was invalid or could not be understood by the server. Resubmitting the request will likely result in the same error.
  • 401 Unauthorized - Your API key is missing.
  • 403 Forbidden - The application is attempting to perform an action it does not have privileges to access. Verify your API key belongs to an enabled user with the required permissions.
  • 404 Not Found - The resource was not found with the given identifier. Either the URL given is not a valid API, or the ID of the object specified in the request is invalid.
  • 406 Not Acceptable - The request contains references to non-existent fields.
  • 409 Conflict - The request attempts to create a duplicate. For employees, duplicate emails are not allowed. For lists, duplicate values are not allowed.
  • 429 Limit Exceeded - The account has reached its employee limit. No additional employees could be added.
Server error status codes (5xx)
  • 500 Internal Server Error - The server encountered an error while processing your request and failed.
  • 502 Gateway Error - The load balancer or web server had trouble connecting to the Bamboo app. Please try the request again.
  • 503 Service Unavailable - The service is temporarily unavailable. Please try the request again.
You can future proof your code by using the following ranges:
  • 200–299 as success
  • 400–499 as client request errors
  • 500–599 as server errors

Employees & Users

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. Each employee is identified by an immutable unique ID. This entity is where information such as hire dates, addresses and contacts are stored.

Users are the people who have been authorized to access BambooHR in some capacity. A user may or may not be an employee. When the user is an employee, you can link the user record to the employee record so that they can take action with their data—like 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.

Compatibility 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 not recognize.

The API will support multiple major version numbers of the API. Currently the only version is "v1". If a major API change becomes necessary, we’ll create a new major version number and communicate the change to our partners. We’ll maintain the existing "v1" API for a reasonable period of time.

API mailing list

You can use the form below to sign up for our API mailing list. Traffic is light, but all changes to the API are announced here.

Your time is valuable.

Thanks for spending some of it with us.

Schedule Demo