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.

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 lower left-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"

To use Postman to make an API request using basic authentication, look at this documentation.

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= a temporary code.

Use this information to generate a token using the following call:

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>"
}

The API will return following response:

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

You can now use the <Temporary access token> in subsequent calls. In Postman, select 'Bearer Token' and enter the <Temporary access token> in the Token field.

NOTE: the refresh_token field will only be returned if you provided the offline_access scope in your original request to authorize.php. If you want to refresh your access token then you can use the refresh token in a call that looks like this:

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

OAuth is available in many APIs and requires configuring an application through BambooHR Team. Companies and developers can work with BambooHR to set this up. You will need a BambooHR Application that includes Client ID and Client secret.

For more information about HTTP Basic Authentication, see Basic Authentication and for OAuth see OAuth.