Getting Started With The API

Our open API makes it easy to integrate other applications into BambooHR. Use this guide to get started sharing your data 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.

What will you need to get started?

If you are a customer or are building an integration for a single BambooHR customer:

  • An account with BambooHR
  • The subdomain used to access your account (If you access BambooHR at, then the subdomain is "mycompany")
  • An API key (See Authentication below for instructions on getting an API key)

If you are building an integration for multiple customers:

  • Apply here to get a client ID and secret
  • Ask the mutual customer for a BambooHR subdomain
  • Use OpenId Connect to get an API key for a BambooHR user


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 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 generate an API key, users should log in and click their name in the upper right-hand corner of any page to get to the user context menu. If they have sufficient permissions, there will be an "API Keys" option in that menu to go to the page.

Each user may 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.

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" "{subdomain}/v1/employees/directory"

Most browsers and tools can accept a URL such as:

https://{API Key}:[email protected]/api/gateway.php/{subdomain}/v1/employees/directory

For more information about HTTP Basic Authentication, see this helpful wikipedia article.

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.

What’s Next

See more detailed information about making requests to the API standard response codes.