ADP Integration Guide


ADP Workforce Now is ADP's payroll solution for mid-size businesses.  

Sapling’s integration with ADP allows you to:

  1. Collect all the information you need for all employee records, while also allowing new hires to engage with your company’s brand, mission, team and onboarding plan before they commence day one with Sapling.
  2. Automate workflows, setup triggered notifications, and reminders across multiple departments, locations and stakeholders, with detailed analytics around workflows. 
  3. Push new employee information to ADP Workforce through a Hire/ Rehire Template
  4. Ensure key employee information stays synchronized with a seamless two-way integration updated daily at 12am

The integration is available in the ADP Marketplace.

Setting up the Integration

Outlined below are the key steps to set-up the Sapling<>ADP Workforce Now integration. 

1. Request the Sapling integration in the ADP Marketplace

  • You will not be required to pay anything additional or enter payment info when going through the integration request "Buy Now" flow in ADP. 
  • After you purchase an app on the ADP Marketplace, you must give permission to the app before the app can access your organization's data. 

2. Approve Sapling in the ADP Consent Manager

You will then use Consent Manager to see which applications have requested consent to your organization's data and grant access as appropriate.

To allow or deny a pending consent in Consent Manager, go to:

You should see the Sapling integration, which by clicking allow - a number of consents for Sapling to communicate with your ADP account will be shown.

Once allowed, Sapling Technologies Data Connector should be in the Allowed Consents section.

3. Confirm Applicant Onboard Template in ADP

In ADP, confirm that the Applicant Onboard Template is active, File Numbers can be automatically set-up and a default state has been set for Payroll

Setup > Template Management > Hire/Rehire

  • Find the HR + Payroll (System) template and make sure Applicant Onboard is enabled
  • If not enabled, please create a new template named Applicant Onboard
  • You must have a Practitioner profile assigned to the Applicant Onboard template (SETUP > Template Management > Hire/Rehire)

Set Up > Payroll > Standard Options

  • Ensure that File Numbers are set to be automatically be created by going to 

Set-up > Payroll > Company Options 

  • Ensure a default state is enabled

4. Sapling will retrieve your ADP Company Code and set up the integration

This can take 1 - 2 days to complete this due to engineering team schedules.

5. Run a Test Onboarding with Sapling and ADP

Run a test onboarding with your Sapling Customer Success Manager.

Once live, it’s best to run a test onboarding with your account. Your Sapling Customer Success Manager will be able to walk you through the process

How it Works

Sapling leverages ADP’s Workers v2 API, which allows Sapling to send applicants (and key information collected by Sapling) into ADP’s New Hire Wizard within ADP Workforce Now. 

This then allows an ADP admin to login, confirm and enrich the applicants data, then complete the new hire in the ADP onboarding wizard itself.

Following the sync from Sapling to ADP, an Associate ID is created in ADP. Each employee’s ADP Associate ID is automatically fetched by Sapling and attached to the employee’s Sapling Profile. 

Sapling then uses this Associate ID to match any changes from ADP back into Sapling, ensuring key information stays in sync for all your employees. 

This document contains a step-by-step process of the integration:

  1. Provision new accounts in ADP from Sapling (Steps #1 - #6)
  2. Push changes made in Sapling to ADP (Step #7)
  3. Pull changes made on employee records in ADP to Sapling (Step #7)

Step #1 - A New Hire is invited to onboard by a Sapling Admin

When onboarding a new employee, a Sapling Super Admin or Admin will confirm a new hire's Start Date and Personal Email address

Sapling requires the collection of certain information to provision new accounts in ADP. For a new hires record, new employees will be required to complete the following:

  • Birthday
  • Gender
  • SSN
  • Address
  • Legal Name

In order to provision the new-employee record in ADP Workforce, the following information is required in Sapling:

  1. Name (typically pushed into Sapling from your company’s ATS)
  2. Personal Email (required input)
  3. SSN (collected from new hire)
  4. Gender (collected from new hire)
  5. Birthday (collected from new hire)
  6. Start Date (typically from your ATS)

*Always confirm the start date matches what your ATS reflects, if not, manually update it in Sapling.

Learn more about Onboarding a New Hire

Step #2 - The New Hire completes their employee record

Sapling's Preboarding portal is designed to provide a consistent and informative introduction in your new organization, and collect the data that your team needs for your first day.

The About You section collects all the data and paperwork you need for your employee record. Front-loading this administration is essential work for preboarding and enables Program Leads to ensure day one is exciting and strategically engaging.

A couple of minutes after new hires submit their preboarding, then ADP will process the new hire’s data and create a profile within ADP’s In-Progress Hires. As an admin in Sapling, you, and other team members, have the ability to be alerted via email when new hires have completed their preboarding. The advantage to this is keeping all your employee data aligned between Sapling and ADP. The screenshot below will show you how to create this ‘Preboarding Complete’ email alert.

Step #3 - The New Hire data is sent to ADP’s Hire/ Rehire

Sapling is continually expanding the number of fields that sync between Sapling<>ADP based on those that become available on ADP’s APIs. 

A full list of Sapling<>ADP Integration Fields are available here

Step #4 - An ADP Admin selects the New Hire from ‘In Progress’ 

Navigate to Process → HR → Hire/Rehire  to access your new hires sent from Sapling.

Step #5 - The New Hire information is populated and confirmed

Step #6 - The New Hire account is created in ADP

Step #7 - Changes in ADP are synchronized to Sapling daily 

Any changes that are made in ADP to the available fields will sync over from ADP and be reflected in Sapling. Changes are synchronized daily at 12:00am.

Sapling will also push changes to the following fields automatically to ADP.

  • Personal email
  • Federal Marital Status
  • Race/Ethnicity
  • Home address
  • Home phone number
  • Mobile phone number

Data Syncing between Sapling and ADP 

Sapling will sync daily with ADP based on the available fields, and you can also re-sync your ADP information to Sapling at any time by pressing “Sync ADP Changes” in the integration settings. This will update your employee information in Sapling by pulling from ADP.

You are able to turn off automatic syncing in both directions: from Sapling to ADP and/or ADP to Sapling. This can be done through the integrations page in Sapling. When clicking on the ADP toggle, there will be two toggles to make these changes.

Time Off with Sapling and ADP

Sapling customers can import their time off accruals and balances into Workforce Now through ADP’s Time Off import function. The workflow takes approximately 5 minutes each pay cycle when completed with batch processing.

In ADP, navigate to Process>Import.

From here, the Time Off Accruals importer allows you to import your time off requests from Sapling. Your Sapling Customer Success manager will help configure this template for you, and here is an example of the export.

Benefits with Sapling and ADP

For customers using the Sapling and ADP integration, employees complete their benefits elections in the ADP platform.

The workflow is typically a task in the new hire Onboarding Workflow providing background, details and a timeline about their enrollment. Once enrollment has been completed, they mark the task as completed in Sapling, ensuring Program Leads have visibility of the process.

Offboarding with Sapling and ADP

While Sapling could offboard employees in ADP, offboarding from Payroll systems involves a number of assumptions and should be managed separated by Payroll and HR professionals. 

The best practice workflow for customers using the Sapling<>ADP integration for offboarding is to utilize an offboarding workflow in Sapling, with ADP offboarding being a subtask of that workflow. Sapling does not update any information in ADP for an offboarding event.

For example - the Offboarding Workflow in Sapling would be comprised of 20 tasks across multiple stakeholders (including Exiting Employees, Managers, IT and Payroll teams) that are notified of the offboarding. 

The task ‘Offboard in ADP’ would be assigned to one of these stakeholders including the new hires information (including termination dates, last day worked, termination type etc.)  

ADP stated limitations of the integration

Like all software, there are some known limitations of the ADP Workforce API.

The key ones for Sapling customers to be aware of are:

  • US879795: Custom Templates (Except the Applicant Onboard Template) are not Supported
  • US978650: Error During Processing when Using the International Template
  • US1238045: Issue with Posting Details of an Employee Who has been Previously Terminated
  • US905487: Fields not Supported through API, most importantly
  • Supervisor Position
  • Reports To
  • Benefits Eligibility Class
  • Standard Hours


Job Titles in Sapling & ADP

To ensure a consistent data flow between Sapling and ADP, Job Titles are pulled from ADP into Sapling. 

This syncing of data is used to ensure that Program Leads assign the appropriate Job Title to new hires. To achieve data accuracy of Job Titles, the Job Title must be listed in ADP for it to be reflected in Sapling. 

Once reflected in Sapling, it will be made an option and Program Leads will be able to select it during the onboarding flow. Any new job titles that are later added into ADP will be sync’d into Sapling in 12 - 24 hours depending on the ADP data tables.

You can also add new job titles in Sapling, however, due to the above - these will not be sync’d with ADP.

Multiple Company Codes

If you have multiple ADP company codes, you’ll need to use a unique Sapling account for each company code. This is because of the unique department, location and employment status IDs across company codes.

For onboarding only customers, Sapling can only send news hires to the single company code. Employees with the different company codes must be using the same onboarding template. We understand that this is a limitation that ADP is working on to improve in Summer 2019.

When this feature is released by ADP, we understand the following

  • Sapling will be able to send to multiple company codes provided the company codes are available on the list returned by code list API "/codelists/hr/v3/worker-management/company-code-values").
  • When onboarding an employee, the company code would then be selected and the ADP instance will be selected based on the values inputted. 
  • This would require additional implementation services and can be completed during a standard 2 - 4 week implementation process.

Custom Fields

ADP supports custom fields with two current constraints. They must be:

  • Text field type (not numbers, multi-choice etc.)
  • Set up in the Employment Custom Fields section (not profile or other sections)

This requires custom development work from the Sapling Solutions team and is subject to additional charges. 

Managing Locations, Teams and Business Units

Often partners are managing multiple field categories in their ATS and seek to understand how Teams, Locations and Commitments map to ADP. Sapling commonly sees:

  1. Employment Status = Worker Category 
  2. Team = Home Department
  3. Location = Location

Business Unit is not commonly captures in the ATS, however it can be entered in Sapling.

Sapling will:

  1. Fetch departments, locations and business units when the ADP integration is initiated
  2. Fetch departments, locations and business units when the Sync ADP Changes is selected

Sapling does not sync new departments, locations and business units each night, however sync’s the specific changes for team members that have changed departments, locations and business units. If the team member has changed to a department, location or business that is not in Sapling - it will sync as nil.

For fields not matching from your ATS to ADP, this can be updated in Sapling to ensure the correct information is sent to ADP.

For these to sync correctly, the naming conventions must matched between Sapling and ADP.

Tax IDs and Types

Sapling can send a number of tax fields to your Workforce Now Account and is compatible with your local settings covering:

  • Tax ID Type * worker > person > governmentIDs > nameCode > codeValue
  • Tax ID * worker > person > governmentIDs > idValue

This information is displayed on step #1 of the ADP onboarding flow shown below.


Multiple Applicant Onboard Templates (coming in Q3 2019)

ADP WFN offers templates for practitioners to start the new hire process. The Applicant Onboard API supports the following templates:

  • HR + Payroll (System)
  • HR + Payroll + Time (System)
  • HR + Time (System)
  • HR Only (System)

In addition, the Applicant Onboard API supports one custom template as long as the name is Applicant Onboard. You can learn more about the template management in the guide available here.

Applicant Onboard Template Permissions for Sapling

Permissions for Sapling

Q- How can I ensure the ADP integration is enabled correctly?

A- Please review and confirm the following:

To ensure the integration is enabled correctly, confirm that the key steps to set-up the Sapling<>ADP Workforce Now integration have been completed. Steps #1 through Step #4 are outlined above.

Key Factors to be aware of:

  • Confirm that the template is titled Applicant Onboard (must match exactly)
  • Confirm that the template is enabled
  • Confirm that the following user is enabled in the template: Profile for system users established by Marketplace Data Connector applications, if unchecked, common error = forbidden

Permissions for ADP Admins

To ensure ADP admins can onboard the new hires, the template permissions must be set-up for the ADP admin as well.

This is done on the same step as above, and requires that any ADP user that needs access to the in-progress hires also has access to the template.

ADP Consent Manager

Sometimes an ADP Marketplace subscription does not trigger the correct flow in the ADP consent manager.

If this happens, simply unsubscribe from the Sapling Data Connector and then re-subscribe. You should then be able to see the new consent request in the consent manager.

The consent manager is available here -

Employment Status Options

The ADP API does not currently support fetching the Employment Status fieId options.

As such, its important customers are aware that the options in Sapling and ADP must match perfectly. 

For example Full Time Canada would not sync to FCAN - Full Time Canada.

Employment information in ADP for existing employees

Work Assignment fields in ADP contain things like Job Title, Department, Location etc. 

While ADP expects to release these soon, their system does not currently have any APIs for updating the work assignment fields, meaning Sapling is unable to update these fields for existing employees.

New Hire Visibility in the Hire/Rehire bay

Ensure that admin functions are enabled. 

You can enable Admin functions by traversing through the following path at WFN Setup->Security->Access Permissions->Menu Access-> Marketplace Data connector(template)->members->Technologies,Sapling(profile)->Process->HR->Admin Functions.

Sending Company Email to ADP

Sapling can only add company emails to the employees that are retrieved in the hr/v2/workers API call. 

This means that if we want to add an email to a newly created employee using the applicant.onboard API, you would need to hire them completely in the WFN UI and then add their email. 

Unable to see pending hires (July 2019)

ADP released an update in July 2019 that can sometimes impact visibility of new hires in the pending hire bay. If this occurs, switching to the ADP Classic View solves the issue.

Rehiring in Sapling and ADP

Individual users in your Sapling account are linked with an Associate ID in ADP. 

For rehires, these should be managed directly in ADP, and Sapling will then pull the changes back from ADP. For example - Location, Departments or Managers.

You'll still be able to assign them documents/ workflows directly on their profile (and track them through your transitions dashboard).

Still no luck? We are here to help!

People Operations can be complex - contact our customer success team to get in touch with you.

Contact Us