How to Pull Employee Data from the BambooHR API (with examples)

Editor's note: This is a series on API-based integrations. Check out Merge if you're looking to add 40+ HRIS integrations with one HR API.

‍

BambooHR is a cloud-hosted solution for human resources (HR). It enables management, monitoring, and optimization across various HR functions, such as employee performance, employee satisfaction, recruitment, onboarding, payment, benefits, and employee vacation periods. It provides a holistic solution for typical HR challenges and helps HR professionals manage their work by providing a single source for employee data.

BambooHR provides an API for its services, allowing users to programmatically access and update records on the platform.

The BambooHR API can be used to retrieve and amend employee and company data, generate files and reports from these data points, as well as to manage time tracking, goals, and tasks in the workspace.

This article provides a demonstration of how to pull employee data from the BambooHR API, using Python code, Postman requests, and the functionality available from Merge.dev.

{{blog-cta-100+}}

BambooHR Developer API

The BambooHR developer API is a RESTful API that utilizes HTTPS requests to access or modify all the available resources on the platform, such as employee data or company reports. Each request you make to the BambooHR API goes through authentication and authorization: the former checks to see if you have the necessary credentials to access the BambooHR domain, while the latter checks to see your permission level, which determines the data you are allowed to view and edit.

Your API requests will be made to a URL that begins with

<code class="blog_inline-code">https://api.bamboohr.com/api/gateway.php/{company subdomain name}/</code>, with further additions made depending on the data being queried. The domain/subdomain name is your self-input tag for your BambooHR environment. 

For the purposes of this article, a trial BambooHR account environment was created by registering on the BambooHR platform.

BambooHR authentication is easily done. Simply log in to your registered/created BambooHR environment and go to the Account option under Settings, then API Keys, where you can generate and delete keys.

Using the Access Levels option under Settings, you can set permission levels for your users to full access, no access, or some preset permission levels: employee, manager, or custom. Remember that the API key inherits the permission set of the user. If a user doesn’t have access to X field, then the API key they generate won’t have access to that field either.

Requests to the BambooHR developer API can return responses in JSON or XML; BambooHR provides functionality to choose the specific response format needed.

Note: BambooHR restricts access to the API if an unknown API key is repeatedly used in a request. While the API is restricted, all requests will return a “403 Forbidden” response.

Utilizing the BambooHR developer API, users can query and update employee data and files, company files and reports, time off and benefits, time and goal tracking, and training, among other services.

Want to use OAuth Bamboo allows for this if you have a partnership.

Related: Examples of HR APIs

Employee Data and Files

You can access and update your employee records, either in bulk or by individual employee. BambooHR has various API endpoints for its services; use the endpoint <code class="blog_inline-code">https://api.bamboohr.com/api/gateway.php/{companyDomain}/v1/employees/{id}/</code> for querying a specific employee. Your self-input company name is the domain (for example, Touchstone), and the id is the unique numerical value for the specific employee. The particular data output from this request is dependent on the self-input query parameters based on the BambooHR API fields. 

For example, sending a request to the endpoint <code class="blog_inline-code">https://api.bamboohr.com/api/gateway.php/{companyDomain}/v1/employees/{id}/?fields=firstName%2ClastName</code> outputs the specific employee’s first name and last name, while the endpoint <code class="blog_inline-code">https://api.bamboohr.com/api/gateway.php/{companyDomain}/v1/employees/{id}/?fields=firstName%2ClastName%2C%20birthday</code> adds in the employee’s birth date. You can also make use of the list of field names for valid query parameters.

The API endpoint <code class="blog_inline-code">https://api.bamboohr.com/api/gateway.php/{companyDomain}/v1/employees/{id}/files/{fileId}</code> retrieves specific employee files, where the added <code class="blog_inline-code">fileId</code> corresponds to the specific employee file needed.

There are two methods to retrieve employee data in bulk from the API. The first method, getting the employee directory, can be restricted in the user account settings, leading to a “403 Forbidden” response. So it’s recommended instead to generate a custom report when bulk employee data is needed. 

You can explore the mechanics of other use cases for the BambooHR API in the documentation. The page showcases the endpoints needed for the requests, the required parameters for those requests, and sample code in Shell, as well as four other software languages.

Related: An example of an employee API

Pulling Employee Data from the BambooHR API

Your employee data is arguably your most important resource on the BambooHR platform, and you might need to connect, aggregate, or visualize this data for better analysis. This article demonstrates pulling employee data from the BambooHR developer API using the following three methods: Python, Postman, and Merge. 

Authentication on BambooHR is a requirement common to all methods. At this point, you should have your registered BambooHR domain and an authenticated BambooHR API key for this domain.

Python

Using the requests library in Python, you can make API calls to BambooHR. As mentioned earlier, the BambooHR API utilizes a basic HTTPS authentication using the user API keys. This means that the API key needs to be encoded in base64 before being sent in the API call. The requests library has functionality for basic authentication encoding.

Here’s the code for pulling a single employee’s data from the BambooHR developer API:

This will show you results similar to the following. 

The same methodology can be used to pull bulk employee data from BambooHR using custom reports:

This will show you results similar to the following. 

Postman

Postman is an API platform for building and using APIs. It provides an easy interface to interact with APIs. You can pull employee data with Postman using the same information you used earlier with Python: the endpoints, API key, and various parameters.

First, you can create a new collection to categorize the requests you will be making. This helps ease authentication when requests use the same authorizations.

Next, click on your created Collection and select the Basic Auth option in the authorization pane, then input your API key in the username space.

Create a request within your Collection. Your first API call with Postman will involve pulling data for a single employee. Select the Basic Auth option under Authorization in your request, and it should inherit the inputted key from your collection. Then, input the API endpoint in the request URL space. As before, the standard endpoint for this call is <code class="blog_inline-code">https://api.bamboohr.com/api/gateway.php/{companyDomain}/v1/employees/{id}</code>.

Our last step for this call is to go to the Params tab and fill out the necessary query parameters. The key is fields, and the value is all the needed field names separated by commas. Sending this request should give similar results to the following.

The response is XML formatted by default, but this can be changed by editing the Accept parameter under the Headers tab, changing the default <code class="blog_inline-code">/</code> for <code class="blog_inline-code">application/json</code>.

The same steps can be undertaken for pulling bulk employee data from BambooHR using custom reports in Postman.

Create a new request under your created collection, select the basic auth option, input the needed endpoint, <code class="blog_inline-code">https://api.bamboohr.com/api/gateway.php/{companyDomain}/v1/reports/custom</code>, which utilizes the HTTPS Post method instead of the GET, and select the right method (POST) from the dropdown.

Next, add in the format variable under the Params tab.

Add a Content-Type parameter under the Headers tab.

Finally, add in the BambooHR API fields needed under the Body tab. You can input these variables in the raw JSON format as below.

This will show you results similar to the following.

How To Pull Employees with Merge

Merge is an API integration platform that eases the process of collating data from several API sources, allowing for querying and updating using a central API link. 

To pull data from the BambooHR API using Merge, your first step is to register on the Merge platform, then connect BambooHR to the Merge platform. Merge provides an easy process to integrate other platforms on the website. 

From your Merge homepage, go to Linked Accounts, then Test Linked Accounts, and add a “Test Account”. Choose BambooHR under Human Resource Information System.

Log in to your BambooHR domain, and it should be integrated under your Merge linked accounts.

Test Linked Accounts is useful for trying out the Merge functionalities and looking for connection bugs. You can elevate your test linked account to a production account by checking the option on your test linked account settings.

Merge shows its utility when collating data from multiple integrations and domains. This collated data can be accessed from one API: the Merge Unified API. To utilize the Merge Unified API, you will need an account token and an API key. You can get your account token by clicking your created linked account. The Account Token can be found below.

The API key can be found by clicking the Configuration option on the menu and then the API Keys tab.

Note: A test API key was created for the test linked accounts demonstrated in this article. Test linked accounts require manual synchronization of your data, but their usage is not billed by Merge.

You can use the endpoint <code class="blog_inline-code">https://api.merge.dev/api/hris/v1/employees</code> to pull bulk employee data from your integrated BambooHR domain on Merge, with request headers for the authentication key <code class="blog_inline-code">Authorization: Bearer YOUR_API_KEY</code> and your account token <code class="blog_inline-code">X-Account-Token: END_USER_ACCOUNT_TOKEN</code>.

This utilizes the Merge Common Model for employee data; this is a default configuration of data parameters that showcases the data available on employees across platforms. This model can be edited according to your needs and queried from a single endpoint without any additional parameters or editing.

If you want to pull custom fields that your customer has set up, you’re able to use Merge’s GET <code class="blog_inline-code">/meta/fields</code> endpoint to pull.

This endpoint and all others are well documented in the Merge API documentation, where you can explore the common data models across the human resources, accounting, and recruiting categories as well as information on getting additional data.

Merge helps you integrate data from multiple sources feeding into a single API link for the eventual user.

Conclusion

In this article, you learned how to query and access BambooHR’s API using Python, Postman, and Merge, exploring the mechanics of each method and how they work.

Merge is a single RESTful API platform that allows easy integration of clients across human resources, applicant tracking, accounting, CRM, file storage, and ticketing system categories. It provides a unified platform link for seamless management of your company’s assets and data resources.

And check out our Guide to ATS Integrations if you're looking to add integrations to BambooHR, Workday, Taleo, SuccessFactors, and more.

Learn more about Merge by scheduling a demo with one of our integration experts.