A Comprehensive Guide to Integrating the Bamboo HR API Into Your HR System

Bamboo HR produces human resource information systems. Its developer API provides several methods to pull employee data.

It fully accesses your employee database to access the Bamboo HR API. It means that the user that logs into Bamboo must be an admin.

Getting Started

The first step in using Bamboo HR API is setting up a service account with your user id. You can do this by logging in to BambooHR, clicking the image of your user profile in the top right corner, and then selecting “API Keys.” Then, select the ‘add API key’ and give it a name. Once the key is generated, copy it and save it somewhere you can find it.

Next, it needs to match employees between both systems. For this, it needs to ensure that there is an employee in each system with the same first and last name. It also needs to ensure that employees have jobs in both systems and that their pay type is the same. Finally, it must ensure the standard hours per week field is filled in for hourly employees.

Once the matches are made, it can sync the data between the two systems. The sync will run in the background and may take up to a few minutes to complete.

Authentication

You will need a unique application programming interface (API) key to use the Bamboo HR API. This key will authenticate any requests you make to the server. The key is generated by logging into BambooHR as an admin with a company domain and selecting the ‘API Keys’ option from the user context menu.

Once you have an API key, you can access your data using built-in R functions, such as getting employees and their files, reports, and tables. The ‘bamboohr-api-key’ config setup function takes the API key and company domain and sets it up to call the BambooHR API.

Whenever you want to access your employee data, make an API request with the ‘/employees’ endpoint and pass in the ‘id’ of the desired employee; this will return their details as JSON. When requesting employee data, the employee ID in your API request must match the employee ID in minor improvements. Otherwise, there may be issues syncing the data between the two systems.

Permissions

Before using the Bamboo HR API, you must set up a new application programming interface (API) key. To do this:

• Log in to your registered or trial Bamboo HR environment as a user with admin-level access.
• Go to the account, click ‘API Keys,’ and generate an API key.
• Give the key a name that will help you identify it and save it in a secure location.
• Choose the access level that you want this key to have.

It will determine what data you can get through the API.

The data you can synchronize between minor improvements and Bamboo HR includes high-level employee information like first name, last name, work email, active status, manager assignments, reviews, and objectives. However, you may encounter errors if your access levels need to be appropriately configured.

For example, suppose you try to retrieve employees’ salaries through the API, but your account only has permission to retrieve data about the organization. In that case, you will receive a 403 Forbidden error. To correct this, you will need to ask your system administrator to grant you more permissions in Bamboo HR so that you can retrieve the information you need.

API Keys

It would be best to generate an API key before using this integration to sync data. It is best done from a service account (or a user with only integration/service access) rather than an employee account, as this will ensure that the key will not be tied to any employee accounts and can still be used for future integrations should the need arise.

When you create a new API key, note it and keep it in a secure location so that it can be used in the future should you need to use it again. Once you have this key, run the sync preview report before activating the integration.

It will also help you understand if any information cannot sync between systems, such as an employee’s email address that does not match their BambooHR ID or a terminated status in the system that differs from the termination date.

Syncing

Upon successfully creating a BambooHR API key, the user will be sent to the sync preview page. This page reviews the syncs that will occur throughout the day and ensures the correct data is imported from each source. This screen will display a list of the last successfully processed syncs and any errors encountered during those processes.

If any errors are discovered, the user can select a date in the future to re-run the synchronization process and update any incorrect information. It is recommended to run a synchronization once per hour.

Once the syncing is complete, any new employees will be added to small improvements and will begin receiving recognition on the platform. Employees will receive notifications via their email that they have been recognized and rewarded.

Note that if an employee’s pay type is set to something other than “employee” in BambooHR, this will not push through to Pento. To resolve this, the user must edit the employee and reselect the appropriate pay type.