Skip to content


BambooHR is an HCM application for storing and managing Employees. Hire2Retire supports BambooHR API to retrieve employee data from user's instance.

Getting Your HR Data

Hire2Retire will use OpenID Connect to get an API key for BambooHR employees. For API Key generation users must have a BambooHR account.

Create a Connection

Hire2Retire requires the following details to create a connection to your BambooHR.

  • Connection Name - A user defined nomenclature for your connection. By default, the connection name is "Connection-Directory Service", you can change the name as per your preferences.
  • API Key - The BambooHR API key assigned to the user that you noted in the API Provider Setup.
  • Company Domain - The BambooHR Domain Name. The Domain Name appears in the url of your account. For example, in the Domain Name is the company_name.

Connection page

Figure 1. BambooHR Connection Set Up Page

To authenticate a BambooHR connection, you must use your API Key and the BambooHR Domain that you use to log in to BambooHR.

How to Generate API Key

Steps for Generating API Key:

  1. Log into the BambooHR ( using your BambooHR account.
  2. Enter your BambooHR Domain.
  3. Enter login details to login.
  4. From the right profile navigation select API keys.
  5. Click on Add New Key to add a new API key.

    Connection page

    Figure 2 Adding New API Key

  6. Give a name to the API key and then click on “Generate key” after that an API key will be generated.

    Connection page

    Figure 2.1 New API Key Name

    Connection page

    Figure 2.2 New API Key Name

Access Level in BambooHR

To utilize Hire2Retire, a user with an API key must possess a specific set of permissions granting read access to data fields, enabling to view details for all employees.
Additionally, if a user chooses to activate the Write to HR feature, user should also have write permissions specifically for modifying work email addresses.

To grant the permissions, please follow these steps:

Step 1: Choose Custom Access Level from Settings >> Access Levels >> Click on “Add” symbol right to “Levels”.

Connection page

Figure 3.1. Choose Custom Access level

Step 2: Fill in the “Access Level Name” and “Description” and click on “Next Step”.

Connection page

Figure 3.2. Fill the details and click on "Next Step"

Step 3: Choose the operations that people assigned to this access level can perform, then click "Next Step".

Connection page

Figure 3.3. Select the permissions to grant the access level

Step 4: Select what people with this access level can see or edit about other employees or about themselves. Here, we can customize single fields accordingly and click on “Save and Finish” after making all the required changes.

Connection page

Figure 3.4. Customize permissions field-wise and click on "Save and Finish"

Step 5: After creating the Access Level, add the employees we want to give access according to the access level created. Click on “Add Employees” and select the employee to put under this custom level.

Connection page

Figure 3.5. Assign people to the newly created custom access level

Connection page

Figure 3.6. Select the user to assign to the custom access level.

Connection page

Figure 3.7. The user “Marrisa Mellon” is added to the custom access level we created.

BambooHR provides different access levels to determine the user's access to information. To know about different access levels, refer Different Access Level in BambooHR

Getting Your Company Domain Name in BambooHR

The domain name appears in the url of your account. Take a look at the address bar when you are logged in to BambooHR. The text just before is your domain. For example, in the domain name is 'company'.

Company domain name

Figure 5. Company domain name in BambooHR


Once you have successfully configured the connections, you can continue with the Design section to configure the rest of the workflow following these steps in order.

  1. HR Data Definition (BambooHR API Integration)
  2. Lifecycle Business Rules
  3. Employment Status
  4. HR to AD Profile Map
  5. Organizational Unit Assignment - Only defined in on-premise Active Directory
  6. Security Group Assignment
  7. Distribution List Assignment


Once your workflow has been setup, you have two optional features you can setup before deploying it.

Otherwise, you can proceed to deploy and test it on the Hire2Retire platform, see Deploy and Test Flow