About the BambooHR API Integration

Maxwell Health and BambooHR have built out an integration that allows your employees’ demographic information to sync between BambooHR and Maxwell Health automatically. The integration also notifies you when specific changes have been made, such as a new employee being added, or an employee being terminated. The notifications will guide you to complete the necessary workflow for benefit updates in Maxwell Health to reflect any changes made in BambooHR.

Maxwell offers the following options for the BambooHR API integration. We recommend using the 360° API two-way sync option in most cases, but we do offer a 180° API one-way sync as well.

• 360° API two-way sync
• 180° API one-way sync (from BambooHR to Maxwell)

In this article, you'll learn about: 

• How the integration works
• Setting up Your BambooHR Integration
• Managing Employee Changes with your BambooHR integration
• Troubleshooting 

How the integration works

Once your BambooHR 360° API integration has been set up and turned on, employee demographic information changes will sync between Maxwell Health and BambooHR. A notification will be sent to the Administrator and/or Advisor set up to receive notifications when demographic changes, new hires, and terminations sync from BambooHR to Maxwell.

• Note: If you choose to set up the 180° API, then demographic information will only sync one way - from BambooHR to Maxwell Health. In this case, employee demographic information will change in Maxwell every time it's changed in BambooHR. BambooHR is the system of record for all employee demographic information, while Maxwell Health is the system of record for all benefit/election information.

Please note that Maxwell Health will remain the system of record for all benefit/election information and all dependents’ information.

Please note:

• If you’re adding a new employee or terminating an existing employee, the changes need to be made in BambooHR first. 
• If you add a new employee to BambooHR whose email address matches an employee’s email address in the Maxwell Health system, the new user will not be able to be created in Maxwell Health. This is because email address is a unique value across Maxwell Health.
• The BambooHR integration will update the following fields for employees:
  • First Name & Last Name
  • Job Title
  • Work Phone & Mobile Phone
  • Address (Line 1 & 2), City, State, Zip Code
  • Email Address
  • SSN
  • Date of Birth
  • Gender (BambooHR is the source of truth and will override Maxwell)
  • Employment Status (Active vs. Inactive)
  • Date of Hire
  • Rehire Date (if applicable)
  • Termination Date
  • Compensation, (if syncing salary) this includes: 
    • Pay Rate (e.g. “$20” for hourly or “$65,000” for salary)
    • Pay Type (Please note this integration only supports “Hourly” or “Salary” as the Pay Type).
      • If you have an “Hourly” Pay Type set for an employee in BambooHR, you’ll need to make sure the “Standard Hours Per Week” field in the employee’s “Job” tab is filled out.
      • The integration works on the assumption that this rate is applicable for 52 weeks of the year. This means that if you have an employee who works variable hours throughout the year, this calculation may be affected. Their benefits may rely on the salary being re-calculated, which will need to be done manually.

Set up your BambooHR integration 

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. Below is some basic information to review or confirm before getting started.

To get started and see more details, see the steps you'll take when Setting up the integration >>

1. Know your BambooHR SubDomain
   • Your SubDomain is the beginning of the URL you use to get to your BambooHR portal. For example, Dunder Mifflin gets to their BambooHR portal by going to dunder.bambooHR.com. Therefore, their SubDomain is “dunder”.
2. Get your BambooHR API key, which is generated out of BambooHR
   • Be sure the API key you create in BambooHR is not user-specific.
3. Create or update “Benefit Group” names in BambooHR to be exactly as you have them set up in Maxwell. Please note:
   • Spaces, special characters, and case must all be consistent.
   • In BambooHR, use the employee field editor to place all employees in a “Benefit Group,” including those not eligible for benefits.
   • Note for large groups, use the power editor in BambooHR to add employees in bulk.
   • Create a Benefit Group called “Ineligible Employees” for all non-benefit eligible employees.
   • If you do not have the “Benefit Group” custom field, you’ll need to submit a request to BambooHR Support to add it. Call 801-724-6600, or email support@bamboohr.com. For more information, visit BambooHR’s support website.
4. Confirm your employee data in BambooHR is updated and accurate, and that it matches the information in Maxwell Health.
   • Correct any missing or incorrect baseline information (first name, last name, SSN, email) in your BambooHR portal.
   • Confirm that the "Benefit Group" field(s) in your BambooHR portal match the "Group" settings in your Maxwell Health portal, and that all employees are in the correct Benefit Group in BambooHR.

After your BambooHR integration has been set up and turned on, you'll be able to see the basic sync settings under Settings > EDI & Integrations > BambooHR.

Next Steps:

1. You should follow the steps outlined in this PDF to ensure that everything is set up correctly in BambooHR.
2. You should also make sure to set up notifications in Maxwell.

Manage employee changes with your BambooHR integration 

Once you've set up and turned on your BambooHR 360° API integration, after a change is made to an employee's information, it will automatically sync between the BambooHR and Maxwell Health systems.

• Note: If you choose to set up the 180° API, then demographic information will only sync one way - from BambooHR to Maxwell Health. In this case, employee demographic information will change in Maxwell every time it's changed in BambooHR.

If there’s a major change to employee information on a sync, you’ll be notified with the information necessary to then manually kick off an event in Maxwell.

• Read how to process new hires with your BambooHR integration
• Read how to process terminations with your BambooHR integration
• Read how to process change requests with your BambooHR integration 

Troubleshooting