About the ADP Workforce Now API Integration

Maxwell’s API integration with ADP Workforce Now will automatically send benefit deductions over to ADP in real-time as they are updated in Maxwell Health. This article includes:

Quick video overview

This three-minute video will give you a high-level overview of the Maxwell/ADP API integration:


The ADP API integration costs $1 per employee that has an active payroll deduction per month. Maxwell will bill the employer on a monthly basis. If you need to change your billing information at any time, please email your updated information to support@maxwellhealth.com.

Getting started with the integration

Note: If you currently use the ADP Workforce Now Compatible Payroll Report in Maxwell (visible under Settings > Integrations), please submit this form to request the integration.

Adding and setting up the integration is self-service and can be completed by the employer at any time. You just need to make sure that you’re already an ADP Workforce Now customer and have credentials to log into ADP and the ADP Marketplace. Follow the steps below!

Step One: 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. Here are a few things to keep in mind before getting started:

  • There are complex deduction code overrides that we cannot support today with the API integration. If possible, you should work with ADP to update your deduction codes in their system so that you can use the integration. This includes:
    • Override any product by a custom field in Maxwell
    • Override a commuter product with a separate deduction code for biking, parking, and transit amounts
    • Override a voluntary product with a different deduction code for the insured individual: employee, spouse, or child
  • The ADP API integration costs $1 per connected employee per month. This is the standard fee that ADP charges.
  • The integration sends benefit deductions to ADP Workforce Now. It does not also sync demographic or compensation information between the two systems.

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

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

  1. Confirm that the employee contributions you have set up for each applicable product in Maxwell are correct. Best practice is to run the Enrolled Cost Report under Tools > Reports > Library and make sure all employee per pay period amounts look correct. If you don’t think the product has been set up correctly, talk to your Advisor. They can help you get the product corrected.

  2. Log into the ADP system and confirm that all at least partially employee-paid benefits in ADP that also exist in Maxwell have deduction codes associated with them. If you need to set up deduction codes in ADP, you should do so using their Validation Tables (select Setup > Tools > Validation Tables > Deductions & Deposits > Deductions).

Please note: If you already have active payroll deductions in ADP, you must first suspend the deductions in ADP that you will be managing in Maxwell.

To suspend deductions in ADP you can do one of the following:

  • Contact your ADP Account Representative (or the ADP Service Center).
  • If you have Universal Access mode in ADP, navigate to Setup > Benefits > Plan Setup. Then you can find the plan, select Actions, and click Suspend Payroll Deductions.


Step Three: Add the Maxwell app in ADP and provide consent

  1. Log into Maxwell and click Payroll > Payroll Integration on the navigation. Then click Set Up.

  2. Click Generate Code. This is the Activation Code you’ll use to connect Maxwell in the ADP Marketplace. This code will be valid for two hours. You can generate another code if this code expires before you get a chance to enter it.

  3. Follow this link to find Maxwell Health in the ADP Marketplace. Log into the Marketplace (if you aren’t logged in already) and click Try the Free Edition or Try Now.

  4. After agreeing to the Terms of Service of the app, click Continue on the next screen. While the activation of the integration is “Free,” remember that you'll be billed $1 per connected employee per month for this integration.

  5. Enter the Activation Code you generated in Maxwell and provide your billing information. Maxwell will bill you on a monthly basis $1 per employee that has an active payroll deduction per month (this is the fee that ADP charges). 

  6. Next, skip billing details and head straight to confirm your order. Check the box acknowledging the Terms of Service and click Place Order.

  7. Return to the Payroll > Payroll Integration screen in Maxwell and follow the link back to ADP where you’ll provide your consent for Maxwell to send and update data in ADP. This is also where you’ll accept the terms & conditions for billing. Note: You also received an email from ADP Marketplace Support with the subject line “Connection Request” with a link to provide your consent for your data to be shared. You can also click that link to provide consent.

Step Four: Return to Maxwell to map employees
This is how you’ll make sure everyone is lined up 1:1 between the two systems. Follow these steps:
  1. On the Payroll Dashboard, click Edit Mappings.

  2. At first, all active employees will appear on the “Not mapped” tab. Here, Maxwell has already automatically suggested matches based on key demographics. The suggested match first looks for employees with the same SSN in both systems. If they don’t have matching SSNs, then it looks to match on the combination of First Name, Last Name, and Date of Birth. If all employees have a suggested match, click Select All and Save.

    No suggested match? Most of your employees in Maxwell should already have a suggested match. If they don’t, then the “Employee in ADP” column will say “No employee selected” and you’ll be able to choose from a list of unmapped employees in ADP. If you don’t see a matching employee, you probably need to add them to ADP. If they’re listed in ADP, review the employee’s record in each system and determine which has incorrect information (compare SSN, DOB, First Name, Last Name) and update accordingly.

Notes and Tips:

  • Hover over the employee’s name to quickly see their relevant demographic information.

  • Inactive employees are not mapped
  • If you have any employees you’d like to disconnect from the integration for any reason, head to the “Connected” tab, uncheck the employee’s “Connected” checkbox, and click Save. They’ll now be listed under “Not connected.”

Step Five: Map product deduction codes

Now, you’ll head back to the Payroll Integration dashboard and click Edit Mappings in the Product row. This will take you to a screen where you’ll map deduction codes for each Maxwell product with employee deductions. Please read this article for everything you need to know about mapping deduction codes.

Step Six: Resolve any Deduction Discrepancies
Once you’ve mapped employees and products, head back to the Payroll Integration dashboard to run a discrepancy report to identify any current mismatches in deduction amounts between the two systems. That way, you’ll know everything’s all set before turning on the integration. Follow these steps:
  1. Click Run Compare. The Deductions Discrepancy Report may take a few minutes to generate as the system is calling information from ADP.

  2. View the number of employees who are “in sync” and the number with “discrepancies.” Click Download Excel File to view the report.

    ”In sync” means that, for these employees, the deduction code amounts match in Maxwell and ADP Workforce Now. “Discrepancies” means that, for these employees, there’s a discrepancy between the deduction amount in ADP and the deduction amount in Maxwell.

    The report lists a row for each product with a deduction amount discrepancy. That means there may be multiple rows for one employee, if they have more than one product with a discrepancy. Here are a few tips on how to interpret results:

    • Blank ADP Deduction Amount

      There’s an employee enrollment mapping to this deduction code in Maxwell, but there's no active deduction in ADP. When the sync is active, Maxwell will start a deduction in ADP.
    • Blank Maxwell Deduction Amount

      There’s an active deduction in ADP for this deduction code, but there's no active employee enrollment in Maxwell. When the sync is active, Maxwell will stop the deduction in ADP. In the above example, MED3 is the name of the product in ADP. Note: if you don’t want to stop the deduction in ADP, you may want to remove the deduction code mapping between these two products. That will prevent the sync from happening.
    • Different Deduction Amounts Between ADP & Maxwell

      There’s an active enrollment in Maxwell and an active deduction in ADP for this deduction code, but the deduction amounts are different. When the sync is active, Maxwell will change the deduction amount in ADP to the Maxwell deduction amount.

      Tips on resolving discrepancies:

      • If the deduction amount in ADP is correct, a manual adjustment will need to be made in Maxwell to update the deduction amount, as Maxwell is the system of record for deductions. Please contact your Advisor to help you get this updated.
      • If the deduction amount in Maxwell is correct, the amount in ADP will update automatically when you turn on the integration. If you do make any changes in ADP, please wait at least 30 minutes before running the Deductions Discrepancy Report again. This will allow enough time for the updates to register.
      • As a general rule, the deduction amount in Maxwell will replace what’s in ADP once you turn the sync on. If you don’t want what’s in Maxwell to send over to ADP, you should fix your products in Maxwell (the system of record for deductions), or disconnect the employee. Please contact your Advisor to help you update deductions in Maxwell.

Note: The report only looks for discrepancies in deduction amounts. It does not check for discrepancies in deduction codes, demographic information, or any other product information.

Step Seven: Review your Payroll Calendar in Maxwell

If you haven’t already, you should check that the correct pay frequency is set for each eligibility group and add your payroll calendar into Maxwell. This is important as the pay frequency is used to calculate employee contribution towards benefits with a monthly premium such as medical, dental, disability, and life insurance products. If your company offers financial products such as an FSA or HSA, entering your company’s pay dates is key to make sure Maxwell has the information needed to calculate accurate payroll deductions. Learn how to set up your pay calendar here >


Step Eight: Begin the sync!

Once you’re satisfied with the Deductions Discrepancy Report results, head back to the Payroll Integration dashboard and click Begin Sync! This will activate the integration and deduction amounts in Maxwell will start sending to ADP for the employees and products you’ve connected.
About the integration

Benefit deductions will be started, changed, or stopped in ADP based on the enrollment information in Maxwell compared to the information in ADP. Once a benefit deduction change happens in Maxwell, it will sync over to ADP in less than one hour.

Maxwell displays all transactions for deductions synced to ADP via the Sync Activity Log, which you can get to from the Payroll Integration dashboard. Activity is sorted listing the most recent at the top. You can view key employee demographic information and corresponding deduction level detail indicating if a deduction was started, changed or stopped by deduction code, the deduction amount and the corresponding effective date of the change.

Starting a Deduction

An employee’s benefit deduction amount is started in ADP when there is an active enrollment in Maxwell, yet there is no matching deduction in ADP. The sync will go over on the product’s effective date in Maxwell.

In Maxwell’s Sync Activity Log, a start will look like this:

Changing a Deduction
An employee’s benefit deduction amount is changed in ADP when the deduction amount in Maxwell does not match the amount in ADP.

In Maxwell’s Sync Activity Log, a change will look like this. The Maxwell amount and ADP amount are displayed under “Deduction Amount.”

Stopping a Deduction
An employee’s benefit deduction amount in ADP is stopped when there is no longer an active enrollment in Maxwell. For example, if an employee is terminated on 10/5/18 and their plan is effective until 10/31/18, then the stop deduction will send to ADP on 11/1/18.

Here are some other examples as to why a deduction may be stopped:
  • Individual product was terminated
  • Employee waived a product they were previously enrolled in during a qualifying life event
  • Employee changes a coverage level and now has zero cost when there was previously a cost
  • Employee changed eligibility group (for example, because they moved to another state) and is now no longer eligible for the product
  • Employee decides not to enroll in the product again at renewal, or the employer stops offering the product
  • The deduction does not exist in Maxwell for any reason (those will list the product name in ADP)

In Maxwell’s Sync Activity Log, a stop will look like this:

If a Sync Errors

In the unexpected event that a sync errors, it will be clearly marked in the Sync Activity Log with a message explaining the reason for the failure.

  • Please note: If you are experiencing deduction update failures, you may want to confirm that you suspended any active payroll deductions in ADP so the deduction can be updated with the Maxwell API.

The system will continue to attempt to sync every 60 minutes, even if there was an error with the last attempt. For that reason, if you encounter an error, the best practice is to wait to see if it errors again the next hour. If the employee still does not sync, contact Maxwell Customer Support at support@maxwellhealth.com or (866) 629-7445.

If you ever want to double-check that things sent over to ADP correctly as stated in the log, you can see deduction amounts in ADP on the individual employee’s record:

Pausing the sync

If you’d like to pause the sync for any reason, click the "Syncing" button on the Payroll Integration dashboard. This will only temporarily disable the sync, and you can turn it back on at any time. If you pause the sync for a long time, it’s best practice to run another Deductions Discrepancy Report to identify any differences that will now be synced when you turn it back on. Any enrollments which have occurred while the integration was paused will be picked up and synced over to ADP.
What to be mindful of ongoing
  • You should always add new hires in ADP first, and Maxwell second. After adding to Maxwell, you’ll need to map the record from ADP over to Maxwell like you did with all employees when you first set up the integration. Head to the Payroll Integration dashboard and click Edit Mappings. You should see the employee listed under “Not mapped." Once you connect them, their deduction information should sync after 60 minutes.
  • When you terminate an employee in Maxwell, they'll stay connected to the integration, and a stop deduction will be sent over to ADP the day after the last effective date of the product.
  • You can add and disconnect an employee at any time without needing to pause the integration. If you need to edit deduction codes, please pause the integration and begin the sync again when you’re done.
  • If you start offering a new product in Maxwell, you'll need to map its deduction code over to the product in ADP. Deduction codes will also need to be updated at renewal. You do not need to pause the sync when you add a deduction code to a new product.

Not supported by the integration

The following is not supported:

  • Syncing demographic information or work events such as new hires, salary changes or terminations.
  • Manual or one-time adjustments, such as prorating the employee’s contribution for a partial pay period or catching up and doubling the contributions for a missed pay period and not supported in Maxwell (and therefore the integration). Maxwell handles recurring deductions, as in the same amount for each paycheck. You’ll make these types of adjustments in the ADP system after the recurring deduction is synced over from Maxwell. Learn more about per pay period amounts in Maxwell >
  • Scheduling future effective deductions. While Maxwell allows enrollments with a future effective/change/termination date to be entered into the system, these starts/changes/stops will not be sent over to ADP until the date the deduction update becomes effective (the product effective date in Maxwell).

Canceling the integration

If you’d like to cancel the integration, log into ADP Workforce Now and go the Maxwell Health App to cancel. This action will notify the Maxwell system and the ADP integration will be disabled and removed from your Maxwell account. Should you wish to turn on the Maxwell-ADP integration in the future, follow the steps as if you were setting up the integration for the first time.

Additionally, you can explicitly revoke your consent for Maxwell to transmit data with ADP here. If you weren’t satisfied with the integration, we’d love to know if there’s anything we can do to improve it! Email us at feedback@maxwellhealth.com.


If you have a question about the API Integration functionality, setup, billing, or your employer’s sync, please contact Maxwell Customer Support at support@maxwellhealth.com.

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

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