Help Center Home > HR Directories > Integrate with BambooHR (Custom API Connector)

Integrate with BambooHR (Custom API Connector)

The current SCIM integration is configured in BambooHR and is one-way - the employee identities are sent from BambooHR to JumpCloud. A custom API integration can be used to import and update attributes that are available in BambooHR, but not in JumpCloud, e.g., manager, alternate email, and employee type.

This integration is configured in JumpCloud and should be considered as a complement to an existing BambooHR SCIM integration, not a replacement.

Prerequisites

  • A JumpCloud administrator account
  • JumpCloud SSO Package or higher or SSO à la carte option
  • A BambooHR user account with full administrator permissions
  • Your BambooHR company subdomain name
  • An existing BambooHR integration

Considerations

Warning:

This option should not be used if the custom report returns more than 1200 rows.

  • The /report endpoint generates a custom report and can manage the user lifecycle.
  • Configuring JumpCloud SSO for BambooHR is recommended, but not required.

Configuring the BambooHR API Authentication

Note:

Per the Authentication section of the BambooHR Getting Started with the API, "the API key is sent over HTTP Basic Authentication. Use the secret key as the username and any random string for the password".

To generate the BambooHR API token

  1. Sign in to your BambooHR instance with administrator permissions.
  2. On the Home page, navigate to Account > API Keys > Add New Key.
  3. Enter a name for the API key in the API Key Name field and click Generate Key.
  4. Click COPY KEY to copy the key to your clipboard.
  5. Click Done.

Warning:

Copy the API Key to a secure location, like the JumpCloud Password Manager, for future reference.

To encode the BambooHR credentials

  1. Access the API Key.
  2. Use a tool or commands to base64 encode the credentials:
    • Command in a mac terminal:
      base64 <<< 1208934bba29wa123492879873:x
    • <BambooHR API key>:<random string with 1 or more characters>
      • Example: 1208934bba29wa123492879873:x
  3. Securely store the encoded credentials, like in the JumpCloud Password Manager.

Configuring Custom Settings for /report endpoint

If you want to manage the lifecycle and avoid creating inactive users, use this option, use the /report endpoint, specifically the GET /report/<id> request.

Important:

You cannot use this option if more than 1200 rows return in the report as it will timeout. Use the /directory endpoint.

To configure BambooHR

A custom report with the attributes you want for the integration, including status, will need to be created in BambooHR. The id for the report is found in the URL shown when viewing the report in BambooHR. 

  1. Log in to BambooHR.
  2. Click the Reports tab from the top navigation bar.
  3. Click +New Report and give the report a name
  4. Add the attributes you want to sync to JumpCloud. 
    • Be sure to include status
    • If you want to import manager, be sure to include supervisor email
  5. Complete the rest of the form and click Save.
  6. Note the id from the URL once the report loads.

To configure JumpCloud

To learn more about the JumpCloud Custom API integration connector, see Import Users with a Custom API Integration.

  1. From the Identity Management tab of your BambooHR application connector, select or enter the following under Service Provider Configuration:
    • API Type – Custom API 
    • Authentication method – API key
    • Base URL – https://api.bamboohr.com/api/gateway.php/<your BambooHR company subdomain>/v1/reports
    • Header name – Authorization
    • Header value – Basic <base64 encoded “API key:random-string”>
  2. In the Endpoint Configuration section, select or enter the following:
    • Resource location – employees
    • Endpoint path – /<report id from section above>
    • Response Parameter Location – Body
    • Response Body JSON Path – na
    • Limit name – leave blank
    • Offset name – leave blank
  3. Click Test Connection.
  1. In the User Schema Attribute Mapping section, enter the following:
    • Unique ID – id
    • User Status – status
    • Inactive Status Values – Inactive

Important:
  • You must include the status value in your report if you want to manage the lifecycle and avoid creating inactive users
  • The Inactive Status Values field is case sensitive, ensure that Inactive is capitalized
  1. Complete all required and desired optional mappings.

Tip:

If you only want this integration for populating manager, the only optional mapping that will need to be included is the one for manager email. All others can be deleted.

Note:

If your company always populates the preferred name field in BambooHR, you can map that to First Name in JumpCloud. If it doesn’t, then mapping firstname will ensure that value is always populated in JumpCloud. However, mapping to firstname may result in users not having the first name they want. 

  1. Scroll back up to the top of the attributes and click Preview.

Warning:

Do not click Save before clicking Activate. You will lose all of your configuration settings.

  1. If the attributes are mapping correctly, click Activate.
  2. If successful, you will receive a message saying the Identity Management has been successfully verified.
  1. Perform your initial manual import.
  2. If the initial import is correct, enable a scheduled sync.
Back to Top

List IconIn this Article

Notebook IconLearn More

Integrate with BambooHR

Import Users with a Custom API Integration

Troubleshoot: Custom API Integrations

Still Have Questions?

If you cannot find an answer to your question in our FAQ, you can always contact us.

Submit a Case