​Integrating with BambooHR

Integrating with BambooHR using a Custom User Report and API Key

This article will guide you through the necessary steps on the BambooHR side to set up the integration with TeamMaven. After setting it up on BambooHR, you can then proceed with the required steps on the TeamMaven side, as mentioned in the subsequent section.

Prerequisites:

• An active BambooHR account with admin privileges.
• TeamMaven account for integration.

Step 1: Create a Custom User Report in BambooHR

1. From the BambooHR dashboard, navigate to the Reports tab.
2. Select Custom Reports on the left sidebar.
3. Click on the + Create New Report button.
4. Give your report a name. For ease of identification, you may want to call it "TeamMaven Integration Report" or a similar name.
5. You can choose the fields you'd like to include in the report that will be shared with TeamMaven. We require the following:
   1. First name
   2. Lastname
   3. Work Email
6. Once you have selected the necessary fields, click Save.

We highly recommend adding the ‘Supervisor Email’ attribute to create your hierarchy in TeamMaven. See the optional hierarchy step below for further guidance.

Finding your report ID

To set up your integration, you’ll need the report identifier for your custom report. This can be found by accessing your custom report as normal. In the browser URL bar, you'll see something similar to https://acme.bamboohr.com/reports/report.php?id=123. The Report ID number is the '123' at the end.

Step 2: Generate an API Key in BambooHR

1. Log in to your BambooHR account.
2. Hover over your profile picture in the top right corner, and select API Keys from the dropdown menu.
3. Click the Add New API Key button.
4. You'll be prompted to give this API key a name, which can be helpful for future reference. Name it something recognisable, like "TeamMaven Integration."
5. Click Generate. The API Key will be displayed. Copy this key and save it securely, as you'll need it to integrate with TeamMaven. It will be in the form of: 333e42ef58a08755f84aa4877399ca355639829d

Note: For security reasons, BambooHR displays the API key only once. If you lose your API key, you will need to generate a new one.

Note: Always keep your API key confidential. Do not share it with unauthorised persons or expose it in unsecured locations. If you believe your API key has been compromised, revoke it immediately in BambooHR and generate a new one.

Step 3: Ensure Proper Permissions

To ensure TeamMaven can access the data from the custom report, you'll need to set the appropriate permissions.

1. Navigate to Settings.
2. Under Permissions, ensure that the API key you generated has access to the data fields in the custom report you've created. You might need to adjust user or group permissions, depending on your organisation's setup.

Note: For security reasons, it's best to create this API Key from a user account that only has access to the data fields you wish to sync with TeamMaven. You'll need to share the custom report with this user, too. Please ensure that this user has access to the Personal & Job categories within BambooHR and no restrictions on certain employees or employee types. For more information on creating an API key, please refer to the BambooHR Documentation.

Step 4: Add the integration on TeamMaven

The TeamMaven Customer Success Team handles this on your behalf. Please reach out to us at success@teammaven.io.

Step 5: Run the Integration

Go to Admin > Integrations on the sidebar and click the run button on the BambooHR integration that we will have created for you:

Now click the Dry Run button. This will run a test and show the changes that will be made.

Once you're happy with the proposed changes, click Finish to effect them.

Optional: Add hierarchy

Every employee must have a Manager designated under ‘Reports To’. This field can be found in Person > Job Information table > Reports to

In BambooHR, navigate to 'Report > Edit (pencil icon) > Calculated fields' and ensure the ‘Supervisor email’ field is included. This field will add the email of the ‘Reports to’ selection to the report.

Let the TeamMaven Customer Success Team know to update the mappings on your integration. Then you'll be able to run the integration and pull in your hierarchy.