Extracting Employee Data with the BambooHR API: Practical Examples

Human Resource Information System (HRIS) platforms are software services that integrate HR functions and streamline HR activities. These activities may include employee data management, recruitment, onboarding and offboarding, performance management, leave and vacation tracking, processing employee feedback, analytics, and reporting. HRIS platforms also often include self-service portals for employees to access important information and track attendance.

BambooHR is a popular cloud-based HRIS platform that's pretty powerful by itself, but it also serves as a common target with which other services can integrate. To enable this, BambooHR provides 125-plus prebuilt integrations on its Marketplace. If there's no existing integration for a given service, BambooHR also provides a REST API to access and update employee data programmatically.

This article explains one possible way of using the BambooHR API to retrieve employee data using Python. Having done that, you'll be able to use your existing knowledge to route the data to a different system with which you're integrating BambooHR.

What is the BambooHR API

The BambooHR API is a RESTful API for integrating other applications into BambooHR. It focuses on synchronizing employee data and generating employee reports. The API provides a variety of endpoints that can retrieve and update employee records and files, company-wide data, benefits, job descriptions and applications, employee training types, and records.

You can access the API using a specific API key if you're developing an integration on behalf of a single customer or use OpenID Connect for authorization if you're serving multiple BambooHR customers.

BambooHR API is particularly useful when your company is a power user of BambooHR, allowing you to automate workflows and customize the platform to perfectly meet your specific needs, such as payroll or employee onboarding. You may want to use state-of-the-art payroll processing or onboarding software as a service (SaaS) that better suits your needs. In this case, if the BambooHR Marketplace doesn't provide an existing integration, your best bet is to use the BambooHR API to synchronize employee data with the other service that you're using.

What if you're working with a SaaS vendor that's not using but developing a state-of-the-art SaaS for onboarding or payroll? If so, you absolutely need to provide integrations with BambooHR and other HRIS platforms using their respective APIs.

How to Extract Employee Data with the BambooHR API

Whatever motivates you to explore the BambooHR API, chances are that your integration efforts start with getting employee information from BambooHR. Let's see how exactly you can retrieve employee data from your BambooHR instance using the BambooHR API and Python.

To follow along, you need two things:

1. The latest Python 3 installed on your machine.
2. A BambooHR account.

Signing Up for a BambooHR Account

If you don't have a BambooHR account, sign up for a free trial.

After filling out the free trial form, create a name for your BambooHR domain (it's going to be used for your instance's subdomain, as in

https://your-bamboohr-domain.bamboohr.com/

) and then log in.

Your trial BambooHR account is pre-populated with sample employee records, so you don't need to worry about coming up with data to follow this tutorial.

Getting Your API Key

To make calls to the BambooHR API, you need to create and copy an API key from your BambooHR account. Here's what you should do:

1. In BambooHR's navigation menu, click the user icon on the far right. In the pop-up menu that appears, click API Keys:

2. In the My API Keys view, click Add New Key.
3. In the Add New API Key view, enter

   bamboohr-python

   as the key name and then click Generate Key.
4. When BambooHR displays your newly generated API key, click Copy Key and then click Done.
5. When the API key is shown, copy and paste it to a safe place as BambooHR won't show it again.

Setting Up a Python Application

You need to set up some boilerplate for the Python application that grabs data from the BambooHR API.

Open the terminal and then create and go to a directory called

bamboohr

that hosts your application:

mkdir bamboohr && cd bamboohr

Inside the

bamboohr

directory, create a new Python virtual environment that is hosted in the

env

subdirectory. If you're on macOS or Linux, use the following command:

python3 -m venv env

On Windows, run this instead:

python -m venv env

Activate the new virtual environment in your terminal.

To do this on macOS or Linux, run the following:

source env/bin/activate

If you're on Windows, run the following activation script instead:

env\Scripts\activate.bat

You need Python's

requests

package to send API requests. Install it by running the following command:

pip install requests

Finally, create a Python file to host the source code that you'll write shortly:

touch main.py

Getting Employee Data from the BambooHR API

Open your newly created

main.py

file in your favorite code editor.

Once inside the file, start by adding your needed

import

statements:

from pathlib import Path
import requests
import json

These statements import the following:

1. The

   requests

   package that you've recently installed to make requests to the BambooHR API.
2. The built-in

   json

   module to parse the data you are getting from the API. Write it into a file.
3. The

   Path

   class from the built-in

   pathlib

   module that helps you create a directory to save the file to.

Next, let's define the base URL that you'll be reusing in your API calls. Paste the following code into your Python file:

domain = 'your-bamboohr-domain'
base_url = f'https://api.bamboohr.com/api/gateway.php/{domain}/v1'

Make sure to replace

your-bamboohr-domain

with the actual BambooHR domain that you specified when creating your BambooHR account. It's used as the subdomain in the URL of your BambooHR instance:

https://your-bamboohr-domain.bamboohr.com/

.

The

base_url

uses your domain name to form your individual base BambooHR API URL that you need to make specific API requests later on.

Let's now save your BambooHR API key to the

api_key

constant. You also define another constant for authentication in the format that the

requests

package needs it to be in:

api_key = 'your-api-key'
auth = (api_key, '')

Remember to replace

your-api-key

with your actual BambooHR API key that you generated and stashed earlier. Note that in the

auth

tuple, the second value is an empty string: the BambooHR API uses basic HTTP authentication where the API key is used as the username and the password can be any string, including an empty string.

The last thing you do to prepare for sending API requests is to declare a

headers

object that sets the

Accept

HTTP header to JSON. If you don't do this, BambooHR will return the results as XML by default:

headers = {
    'Accept': 'application/json'
}

Now, let's add stubs for the three functions that perform the main steps of your program:

def get_all_employees():
    pass

def print_all_employees(employees_json):
    pass

def save_all_employees_to_file(employees_json):
    pass

all_employees = get_all_employees()

get_all_employees()

makes an API call and returns text data.

print_all_employees()

displays formatted data in the console output.

save_all_employees_to_file()

saves the data to a file.

You're also calling the first of these functions and saving whatever it returns to the

all_employees

variable.

Let's now fill the stub of the

get_all_employees()

function with code that makes an API request for the list of employees in the BambooHR directory. Update

get_all_employees()

to read the following:

def get_all_employees():
    try:
        response_all_employees = requests.request('GET', f'{base_url}/employees/directory', headers=headers, auth=auth)
        if response_all_employees.status_code == 200:
            return response_all_employees.text
        else:
            print(
                f'Something went wrong when trying to get the requested info from the API server. Status code: {response_all_employees.status_code}. Message: {response_all_employees.reason}')
    except Exception as e:
        print("An error occurred while performing the API call: ", e)

Here's what happens inside the updated function:

1. The

   request

   function from the

   requests

   package makes a GET HTTP request to the BambooHR API's Get Employee Directory endpoint. It uses string interpolation to combine the base URL that you've defined earlier with the path of the endpoint. The

   headers

   and

   auth

   constants are passed as respective arguments. The result of the call is saved into the

   response_all_employees

   variable.
2. The

   response_all_employees

   is a

   Response

   object. The

   request

   function returning this object may throw several exceptions, so the code in the function is wrapped into a

   try…except

   block to provide basic handling for these.
3. The check for status code

   200

   verifies if your request has been successfully fulfilled, provided that no exceptions occur. If it's successful, then you return the textual employee data that arrived from the API, which is available through the

   text

   property of the

   response_all_employees

   object.
4. The status code and error message that the API has returned are simply printed if the status code of the response is anything other than

   200

   .

The employee directory data that the API returns looks something like this:

{
  "fields": [
    {
      "id": "displayName",
      "type": "text",
      "name": "Display name"
    },
    {
      "id": "firstName",
      "type": "text",
      "name": "First name"
    },
    // more field definitions
  ],
  "employees": [
    {
      "id": "4",
      "displayName": "Charlotte Abbott",
      "firstName": "Charlotte",
      "lastName": "Abbott",
      "preferredName": null,
      "jobTitle": "Sr. HR Administrator",
      "workPhone": "801-724-6600",
      "mobilePhone": "801-724-6600",
      "workEmail": "cabbott@efficientoffice.com",
      "department": "Human Resources",
      "location": "Lindon, Utah",
      "division": "North America",
      "linkedIn": "www.linkedin.com",
      "instagram": "@instagram",
      "pronouns": null,
      "workPhoneExtension": "1272",
      "supervisor": "Jennifer Caldwell",
      "photoUploaded": true,
      "photoUrl": "https:\/\/images7.bamboohr.com\/619596\/photos\/4-6-4.jpg?Policy=eyJTdGF0ZW1lbnQiOlt7IlJlc291cmNlIjoiaHR0cHM6Ly9pbWFnZXM3LmJhbWJvb2hyLmNvbS82MTk1OTYvKiIsIkNvbmRpdGlvbiI6eyJEYXRlR3JlYXRlclRoYW4iOnsiQVdTOkVwb2NoVGltZSI6MTcyMDAxMTM2MH0sIkRhdGVMZXNzVGhhbiI6eyJBV1M6RXBvY2hUaW1lIjoxNzIyNjAzMzcwfX19XX0_&Signature=Ewi31wP5h7aoUEQSEmWEj7vAvo7GTVNXIjk4iJQ9XKGiczzwlUR~EJLrtaClvCxxsvxq0~cdVQ1yJO1fLe0loSP1t5BE48bOZQ0biOqawfMToqTmCBEV7ADxdvqs0rMnGVm9cV6F~p7LewXfp51lgW7u6A2TTudkWCbJN5btsJVp~1UaVyMBsZFwujYvFgrXxXLYxfb4WsvW3bVsnfnmMO8eHq5SIZw~joaII7sEJdzHKaMdsNaMP9GCUY-Mrs~~Gt9JcV3rt8M-YxXH8Rxmo18xmqCqePDML8ETWDWkhzjrDSNv6shU9PjuxhujxDJ6e0BVZ8XYKMn5sTUf9tlltQ__&Key-Pair-Id=APKAIZ7QQNDH4DJY7K4Q",
      "canUploadPhoto": 1
    },
    {
      "id": "5",
      "displayName": "Ashley Adams",
      "firstName": "Ashley",
      "lastName": "Adams",
      "preferredName": null,
      "jobTitle": "HR Administrator",
      "workPhone": "+44 207 555 4730",
      "mobilePhone": "+44 207 555 6671",
      "workEmail": "aadams@efficientoffice.com",
      "department": "Human Resources",
      "location": "London, UK",
      "division": "Europe",
      "linkedIn": "www.linkedin.com",
      "instagram": "@instagram",
      "pronouns": null,
      "workPhoneExtension": "130",
      "supervisor": "Jennifer Caldwell",
      "photoUploaded": true,
      "photoUrl": "https:\/\/images7.bamboohr.com\/619596\/photos\/5-6-4.jpg?Policy=eyJTdGF0ZW1lbnQiOlt7IlJlc291cmNlIjoiaHR0cHM6Ly9pbWFnZXM3LmJhbWJvb2hyLmNvbS82MTk1OTYvKiIsIkNvbmRpdGlvbiI6eyJEYXRlR3JlYXRlclRoYW4iOnsiQVdTOkVwb2NoVGltZSI6MTcyMDAxMTM2MH0sIkRhdGVMZXNzVGhhbiI6eyJBV1M6RXBvY2hUaW1lIjoxNzIyNjAzMzcwfX19XX0_&Signature=Ewi31wP5h7aoUEQSEmWEj7vAvo7GTVNXIjk4iJQ9XKGiczzwlUR~EJLrtaClvCxxsvxq0~cdVQ1yJO1fLe0loSP1t5BE48bOZQ0biOqawfMToqTmCBEV7ADxdvqs0rMnGVm9cV6F~p7LewXfp51lgW7u6A2TTudkWCbJN5btsJVp~1UaVyMBsZFwujYvFgrXxXLYxfb4WsvW3bVsnfnmMO8eHq5SIZw~joaII7sEJdzHKaMdsNaMP9GCUY-Mrs~~Gt9JcV3rt8M-YxXH8Rxmo18xmqCqePDML8ETWDWkhzjrDSNv6shU9PjuxhujxDJ6e0BVZ8XYKMn5sTUf9tlltQ__&Key-Pair-Id=APKAIZ7QQNDH4DJY7K4Q",
      "canUploadPhoto": 1
    },
    // more employee records
  ]
}

The response data consists of two arrays:

fields

and

employees

. The former lists the fields that the response data contains, along with their types. Fields are important as you can use them in API calls to exactly define what kind of data you want to be returned. However, in this simple scenario, you don't need them: what you're after is the

employees

array.

Printing and Saving Employee Data

You'll save the entire

employees

array to a file later on. For now, let's display basic information about each employee in the console.

Start by replacing the stub of the

print_all_employees()

function with the following:

def print_all_employees(employees_json):
    for entry in employees_json:
        print(
            f'{entry["displayName"]}: {entry["jobTitle"]} at {entry["department"]}, based in {entry["location"]} ({entry["division"]})')

This function now goes over all employee entries and prints a quick summary that includes each employee's full name, job title, department, location, and division.

Now, at the end of the file, following the

all_employees

declaration, add this piece of code:

if all_employees is not None:
    all_employees_json = json.loads(all_employees)['employees']
    print_all_employees(all_employees_json)

Initially, you're checking whether

all_employees

is null, which is possible if the prior API call has returned an error. If it's not null, you parse employee data as JSON and save the

employees

array from the resulting JSON object, thus stripping away the

fields

array. You then pass the JSON object to the

print_all_employees()

function.

If you call your program now by running

python main.py

in the terminal, you'll see something like this:

Charlotte Abbott: Sr. HR Administrator at Human Resources, based in Lindon, Utah (North America)
Ashley Adams: HR Administrator at Human Resources, based in London, UK (Europe)
Christina Agluinda: HR Administrator at Human Resources, based in Sydney, Australia (Asia-Pacific)
Shannon Anderson: HR Administrator at Human Resources, based in Vancouver, Canada (North America)
Maja Andev: VP of Product at Product, based in Lindon, Utah (North America)
Eric Asture: VP of IT at IT, based in Lindon, Utah (North America)
Cheryl Barnet: VP of Customer Success at Customer Success, based in Lindon, Utah (North America)
Jake Bryan: VP Learning and Development at Operations, based in Lindon, Utah (North America)

Finally, let's save the full set of employee data to a JSON file. At the end of

main.py

, following the call to

print_all_employees

, add a call to

save_all_employees_to_file

:

save_all_employees_to_file(all_employees_json)

Then replace the stub of the

save_all_employees_to_file

function with the following:

def save_all_employees_to_file(employees_json):
    destination_dir = 'data'
    Path(destination_dir).mkdir(parents=True, exist_ok=True)
    json_file = f'{destination_dir}/all_employees.json'
    with open(json_file, 'w', encoding='utf-8') as target_file:
        json.dump(employees_json, target_file, ensure_ascii=False, indent=4)
    print(f"Data saved to {json_file}.")

This function now creates the

data

directory if it doesn't exist, writes employee data to a JSON file in this directory, and reports a status update to the console.

If you want to see what your

main.py

file should look like by the end of this exercise, check out this "Extracting Employee Data with the BambooHR API" example.

If you're developing a product that relies on integrations with many different HRIS systems, you need to create and maintain multiple integrations that are going to be more sophisticated than the one shown earlier. The product would probably include authentication and authorization that are more advanced than those that use a single API key, handle error codes and retries, have a database layer instead of employee data dumped into JSON files, and more. After working through a few, chances are you'll realize that's probably not what you want to spend your development resources on.

Instead, consider using a unified HRIS API like the one that Apideck provides. The unified HRIS API is a single API that enables pulling and pushing employee data from and to more than fifty HRIS platforms in real time. You can save valuable development time and resources instead of spending them on developing and maintaining all the integrations in-house.

Summary

After reading this article, you now know how to write a proof-of-concept Python application that gets basic employee information from a BambooHR instance using the BambooHR API. See the "Extracting Employee Data with the BambooHR API" example for the source code of

main.py

that results from performing the instructions given earlier.

In a real-life integration, you need to worry about many other things, such as managing authentication and authorization, handling client- and server-side error codes, implementing retry policies, and monitoring API versions to prevent service interruptions.

Doing this for one HRIS service is fine, but if you're integrating with dozens of them, your development team can get overwhelmed quickly. If you don't want this to happen, start simplifying your HRIS integrations today by signing up to Apideck.