1. Support
  2. Data Connections
  3. Integrations

BambooHR API Integration - Setting up the Integration

Avatar
Kaylie Bryslawskyj

Before you begin, make sure this integration will fit your company’s needs. We’d hate for you to jump into the setup process just to realize that the integration isn’t a great fit for your company today.

>> Read more about the integration here.

Adding and setting up the integration is self-service and can be completed at any time. As long as you are already a BambooHR customer, you’re ready to get started. Follow the steps below!

  1. Confirm your BambooHR API Key is set up with proper permissions
  2. Confirm all data in Maxwell & BambooHR is accurate
  3. Establish the connection between Maxwell and BambooHR
  4. Configure your data sync settings
  5. Preview your data sync settings
  6. Activate and Sync

Step One: Confirm your BambooHR API Key is set up with proper permissions

Check that your BambooHR API Key has the necessary permissions and is not tied to an individual BambooHR user. This ensures that you experience full API and webhook support.

You can find detailed instructions on creating an API key here in BambooHR’s Help Center. When you set up your custom access level, be sure it provides access to the connected fields; otherwise, the integration won’t work and you will receive error messages.

Also, be sure to have these fields in the Job Tab in your BambooHR account:

  1. Standard Hours per Week
  2. Benefit Group

You only need to fill out Standard Hours per Week for hourly employees. Please note, the Benefit Group field is different from the Benefit Groups used in the BambooHR Benefits feature. This is important to understand because this field determines which Eligibility Group your employees are synced to Maxwell Health.


Step Two: Confirm all data in Maxwell & BambooHR is accurate

Before going any further, you should feel confident in the accuracy of data that you have in Maxwell and BambooHR. The integration will be most successful when you know you’re starting off with accurate information!

  1. Review Employee ID field for your employees
    • Before you sync information, you may want to review your employee data to make sure there is enough information to match employees across systems. Employees that exist in both portals will initially be matched based on Social Security Number (SSN). If SSN does not exist to match, First Name, Last Name, and Date of Birth will be used to match employees.
    • When you activate the integration, the BambooHR employee ID field will be used to match your employees in Maxwell with your employees in BambooHR. The BambooHR employee ID field will display on Maxwell employee profiles once you successfully connect to BambooHR in the next step.
  2. Review Eligibility Group setup
    • The Benefit Group field options setup in BambooHR must match the Eligibility Group options in Maxwell. This will determine which Eligibility Group your employees are synced into inside of Maxwell. The Eligibility Group in Maxwell also determines what benefits the employee is eligible to enroll in.
  3. Enable notifications
    • It is strongly recommended that you enable all BambooHR integration notifications in Maxwell so you can easily monitor any issues or changes that come from BambooHR into Maxwell and take action if necessary. You can review information on notifications here.

Step Three: Establish the connection between Maxwell and BambooHR

  1. Log into Maxwell and click Settings > EDI and Integrations > All Integrations on the navigation. Then select the BambooHR API Integration.
    • Integrations-BambooHR.png
  2. Confirm you have reviewed all the details to get started and click Next: Connect.
    • MH-Bamboo-NextConnect.png
  3. Enter your BambooHR Subdomain and BambooHR API Key to establish the connection.
    • Subdomain Tip: To find the subdomain for your BambooHR account, look for the name between “https://” and “.bamboohr.com”. So if the login URL is https://company.bamboohr.com, then “company” is the subdomain.
    • Before you can sync, you need to create an API key in BambooHR. You’ll enter the API key you created in BambooHR here.
      • API Key Tip: Check that your BambooHR API Key has the necessary permissions and is not tied to an individual BambooHR user.
  4. After you enter your BambooHR details select ‘Connect’.
    • MH-Bamboo-Connect_copy__1_.png
  5. You can then move on to step four to configure your sync settings by selecting Next: Configure.

Step Four: Configure your data sync settings

This is where you’ll confirm which employees should sync and how you want to handle any existing differences in employee information to make sure everything is lined up between the two systems. Follow these steps:

  1. If the 360 API integration is selected, you’ll then set the system that will serve as the source of truth for employee demographic data upon the initial sync when you activate the integration. This is to resolve any existing discrepancies between employee records.
    • Any employee demographic data that exists in the portal you set as the source of truth will sync over and replace information in the other portal.
    • BHR-ConfigureSyncType.png
      • Example: If you select BambooHR as the source of truth, and an employee has a different address in BambooHR than what appears in Maxwell, the address information in BambooHR will sync and replace the information in Maxwell upon the initial activation of the integration.
      • Please note: This setting only applies to the initial sync of information to resolve any existing differences in employee records. Once the integration is active, the demographic fields supported with this integration will immediately sync bi-directionally, so the records will automatically match.
  2. Determine if any employees should be excluded from syncing from BambooHR to Maxwell.
    • Most employers will want to sync all employee records from BambooHR to Maxwell, but you can exclude employee records from syncing by setting filters based on employee information.
    • Example: If you have a group of international employees, you should set filters to exclude that group of employees (Maxwell does not support international employees).
    • MH-Bamboo-SyncConfigpng_copy__1_.png
    • Please note:This filter will continue to remain in effect as long as the integration is active. To change after activation, you will need to pause the integration.
  3. Select if you would like the integration to sync employee salary information from BambooHR.
    • Most employers will choose to have salaries synced from BambooHR to Maxwell. However, if you offer salary-based benefits that use a salary calculation other than the employee’s ‘annual gross salary’, you’ll want to select “Do not sync salary data” below.
    • Please note: If you choose not to sync salary data, any new employees you add to BambooHR who are eligible for salary-based benefits will not be created in Maxwell automatically. You will need to add them directly into Maxwell to manage their salary-based benefits.
    • Once added to Maxwell, demographic information will then be able to sync from BambooHR.
  4. Select the email address field that will be mapped into Maxwell.
    • Only one email can be used as the employee’s login to access their Maxwell Health account. Choose the email field from BambooHR that will be used as the Maxwell account login.

Step Five: Preview your data sync settings

Use the Generate Preview to review how information will update in Maxwell upon your initial sync based on the sync settings you applied. This will give you an opportunity to confirm that your settings are correct before you activate the integration.

  1. Click Generate Preview.
  2. Select to download the Sync Preview Report excel file that is generated.
  3. Review the Sync Preview Report. (See below for tips on reviewing the report >)
  4. Resolve any discrepancies.
    • As you review the report, if there are differences in information between BambooHR and Maxwell that you would like to resolve before activating the integration, you should do that now and confirm those updates are completed by re-running the Sync Preview Report.
    • Example: If your preview report includes a row where the summary is “Cannot Sync”, and it is due to missing information inside of BambooHR, then you should review the fields that require information and make that update in your BambooHR portal.
  5. When you have reviewed and approved your sync settings, click Review and Activate.

Tips for the Sync Preview Report

Here are a few tips on how to interpret results based on the summary for each employee row on the Sync Preview Report you will run prior to activating your integration. The report lists a row for each employee in BambooHR or Maxwell, along with how the current data exists in each system.

Results can include:

  • Employee Filtered
    • Employee will be excluded from the sync from BambooHR due to a filter you added in your sync settings.
  • Cannot Sync
    • Employee can’t sync due to invalid or missing data. The invalid fields will be listed in the details column of the preview report.
    • Employee does not exist in BambooHR, but does appear in Maxwell. This employee cannot be synced, since that would mean deleting the employee and neither Maxwell nor BambooHR supports automatic deletion through the sync.
      • Note: will say “Employee cannot be deleted”
    • Employee exists only in BambooHR, and cannot be added as a new employee in the other system.
      • An employee cannot be added to Maxwell from BambooHR if they are eligible for salary-based benefits and you chose not to sync salary. You will need to add the employee into Maxwell first, and then other information can sync between the systems.
  • Employee Create
    • If the employee does not currently exist in Maxwell, it will be created in Maxwell.
  • Employee Terminate
    • Employee in BambooHR has a terminated status but is not showing as terminated in Maxwell. Upon activation of the integration, the employee will be updated with the termination date and reason in order to match across both systems.
  • Employee Update
    • Employee in Maxwell will have one or more fields updated based on their demographic information in BambooHR. The updated fields will be listed in the Details column in addition to being highlighted.

Step Six: Activate and Sync

Now, you’ll have one final opportunity to review your sync settings.

  1. Review and Confirm:
    • how demographic discrepancies should be handled for the initial sync
    • if any employees will be excluded from the sync ongoing
    • how salary data will sync ongoing
  2. When you’re ready, the final step to setting up your BambooHR 180° API Integration is to click Activate and Sync.
    • Note: The initial sync can take several minutes, especially if there are a lot of changes. However, you are free to navigate away or leave the app and come back while the initial sync is running.

Congratulations on activating the BambooHR API integration! Going forward, any matched employees (based on your ongoing sync settings) will be synced from BambooHR to Maxwell.

Support

If you have a question about the API Integration functionality, setup, billing, or your sync, please contact Maxwell Customer Support at support@maxwellhealth.com. You can also learn more about how the integration works in this article.

If you have a question about BambooHR functionality or product offering, contact your BambooHR representative or visit their site.

Was this article helpful?
0 out of 0 found this helpful

Related articles