Getting Started With The API

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.

Never miss a thing!

Sign up for our mailing list to receive updates when there is a planned change or addition to the API.  We might occasionally reach out for your input on what we're up to!

Sign up here: https://www.bamboohr.com/api-mailing-list/

What will you need to get started?

• A software developer to write code
• An HTTP client:
  • This library may help you get started: https://documentation.bamboohr.com/docs/language-bindings
  • Postman.

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 https://mycompany.bamboohr.com, 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

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 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" "https://api.bamboohr.com/api/gateway.php/{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.

Note on OAuth with specific permissions (Limited availability)

We are rolling out OAuth with restricted permissions, allowing limited data access based on scope. This feature will have limited availability.

Use this information to generate a token via a browser or curl:

https://<company domain>.bamboohr.com/authorize.php?request=authorize&state=new&response_type=code&scope=[multiple scopes separated by plus +]&client_id=<your App's client id>&redirect_uri=<your App's redirect URI as defined while creating your App>

Your browser will redirect to the URI specified in 'redirect_url', with additional information &code=.

https://<company domain>.bamboohr.com/token.php?request=token
Body
{
   "client_secret":"<your App's client secret>",
   "client_id":"<your App's client ID>",
   "code":"<A temporary code>",
   "grant_type":"authorization_code",
   "redirect_uri":"<Redirect URI mentioned in your App>"
}

{  
    "access_token": "<Temporary access token>",  
    "expires_in": 3600,  
    "token_type": "Bearer",  
    "scope": "<scopes separated by space>",  
    "id_token": "<unique ID>",  
    "companyDomain": "<your company domain>"  
}