ADP Workforce Now API Integration - Setting up the 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. Adding and setting up the integration is self-service and can be completed at any time.

As long as you are already an ADP WorkforceNow client, you’re ready to get started. Follow the steps below!

  1. Make sure this integration will fit your company’s needs
  2. Confirm all data in Maxwell & ADP is accurate
  3. Add the Maxwell app in ADP and provide consent
  4. Return to Maxwell to map employees
  5. Map product deduction codes
  6. Resolve any Deduction Discrepancies
  7. Review your Payroll Calendar in Maxwell
  8. Begin the sync!

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.

Step One: Make sure this integration will fit your company’s needs

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 and pricing here.

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.


Maxwell_Ribbon.png Notes and Quick 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.


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