For customers of our ADP Workforce Now integration.
To enable the ADP Workforce Now bidirectional API:
Note: Only Company Admins and HR Admins can manage company settings and send data from Built to ADP. To learn more, refer to: Understanding User Roles & Permissions.
Contact our Customer Success Team to activate the ADP bidirectional API setting in your account.
Click your company name at the top of the main navigation, then click Company Settings.
Click the Imports tab.
Locate the ADP Integration Settings section and click the Edit button.
Click Yes to enable the ADP bidirectional API, then click Save.
Ensuring Built and ADP are Updated
Once you’ve enabled the bidirectional API, an indicator badge visible to Company Admins and HR Admins will appear on the Org Chart, People, and Position Management pages, displaying the number of changes ready to send to ADP.
To ensure unsent changes are not overwritten with conflicting data, Built disables imports until all changes are sent to ADP. We recommend following these best practices when sending changes to ADP to keep Built and ADP up to date:
Import data from ADP before making changes in Built to ensure data consistency and reduce the likelihood of errors.
Make the needed changes in Built, and send changes to ADP immediately to avoid import disruption.
To send changes from Built to ADP:
From the main menu, navigate to the Org Chart page and click the indicator badge in the upper right corner.
Choose an option:
•Review Changes: The batch will open, allowing you to review the changes before clicking Send to ADP.
Note: You can access the ADP change log by clicking the back arrow in the upper left corner of the batch page. The log will summarize your organization’s batch history, including current statuses (Unsent, Sending, Sent with Errors, or Sent). To return to the batch page, click the appropriate View Details button.
•Send to ADP: Your batch of unsent changes will be pushed to ADP. The indicator badge will provide progress updates (e.g., 50% of Changes Sent to ADP/Sending in Progress). Once sending is complete, the indicator badge will update to display No Unsent Changes if all changes were sent successfully or, if any errors occurred, the number of changes sent will be displayed (e.g., 10/20 Changes Sent to ADP).
Notes about sending changes to ADP:
The effective date for changes sent to ADP will be the date the change was made in Built, regardless of when the change was sent.
Changes reverted before they’re sent to ADP will be removed from the batch.
Changes made in Built while the batch is sending will be added to a new batch and displayed on the indicator badge once all changes have been sent.
Changes to secondary positions (dotted line relationships) cannot be sent to ADP.
In Built, when a person is added to a position filled by other occupants, the position, direct reports, and associated data are shared. Because position IDs cannot be shared in ADP, when changes are sent to ADP and the person’s work assignment is updated, they will not be added as a manager for their new direct reports. Learn more about managing shared positions in Built.
When sending changes to ADP for a shared position that is primary for all occupants, only the individual associated with the work assignment in Built’s External ID field will be updated. The following error message will be displayed for all other occupants: “The request failed due to a mismatch between the worker and work assignment. Verify the external ID for the employee's current position matches their Position ID in ADP”.
If a manager is removed from their position and not moved to another position in Built, when changes are sent to ADP, the individual will be maintained as the manager for the direct reports. If the manager for the direct report(s) is not updated manually in ADP or Built, future ADP imports may result in the following changes in Built:
If the manager’s previous position remains open, the direct reports will be removed from the chart. Once the open position is filled and changes are sent to ADP, the direct reports will be assigned to the new manager.
In the case the original manager is moved to another position but changes are NOT sent to ADP, the direct reports will be placed under the manager’s new position, whether or not the manager’s previous position is open or filled.
Handling Errors
In the case that all changes were not sent successfully (e.g., 10/20 Changes Sent to ADP), you can review any errors by clicking the badge and then View Details. When the batch opens, choose how to handle the errors by clicking the desired option:
Resume Imports from ADP: When selecting this option, changes that failed to be sent to ADP will persist in Built but will not be sent to ADP in future batches. Changes not updated manually in ADP before the next import will be overwritten in Built.
Copy Changes to New Batch: This option allows you to attempt fixes in ADP and send changes at a later time. In this case, imports would be disabled in Built until all changes are sent successfully.
Once you’ve confirmed how Built will handle the errors, you can review the change details at any time by navigating to the appropriate batch:
When there are unsent changes, click the indicator badge to view the current batch, then click the back arrow to access the ADP change log. On the ADP change log, click View Details to review a batch.
When there are no unsent changes, click the indicator badge to access the ADP change log directly before clicking View Details to review a batch.
Please contact our Customer Success Team for additional assistance.