Overview of ADP
Automatic Data Processing (ADP) is a cloud-based software that provides services that cover all needs in human resource information systems (HRIS). Whether your company needs to manage payroll, hire new employees, track employee performance, calculate taxes, manage benefit information such as health insurance and retirement plans, or attract your employees to complete training on time, it has everything covered. The ADP system remains updated with all the latest HR regulations, so outdated information is not an issue here.
Managing payroll and HR manually can lead to many issues, such as high probability of manual data entry errors, issues due to duplicate data entry, difficulty of keeping up with changing labor laws and regulations is time-consuming and difficult which may also lead to compliance issues. Handling consistent payroll accurately for the employees can be challenging at times.
ADP API integration not just tackles these issues, but makes the process efficient so you can work on tasks that are more important.
Importance of ADP Integration
- Improved Efficiency and Automation: Automating tasks such as onboarding, offboarding, and status changes eliminates manual data entry errors, saving HR teams significant time.
- Real Time Data Sync & Streamlined Processes : Connecting ADP with other applications can automate workflows like payroll and benefits administration, and data flows between ADP and other systems reduce inconsistency by providing access to accurate employee information.
- Ensure Compliance : ADP takes care of latest labor laws. By integrating with ADP, you can ensure that you are HR practices are complaint.
- Simplify Complex Processes : Some processes are tedious and challenging like consistent payroll management, ADP automates payroll calculations ensuring accuracy and timely payments for all employees.
Developer Primer
This guide gets you started with the entire process of ADP API integration covering prerequisites, authentication, use case for this guide, operations, testing, deployment and troubleshooting—all the essentials.
You will find more about ADP API, use cases, endpoints in ADP API Events and Endpoints.
There are various modules for which ADP provides APIs for integration, you can find your specific use case for integration in ADP API Documentation.
In case you are looking for a quick and easy way to build your ADP API integration along with multiple other HRIS an payroll systems in one go, checkout Knit. Knit provides a unified HRIS API covering the ADP API along with 40+ other HRIS & Payroll connectors.
Prerequisites & Initial Steps
Setting Up ADP Developer Account
- As a developer, you will register for a developer account. Your employer will have to provide you access for that.
- You will get your self-service registration code from your HR department or payroll administrator.
- You can now enter your registration code ADP registration page. If you already have an account with ADP, you can directly log in with your user ID and password login page.
Prerequisites for Obtaining Credentials & Setting Up Authentication
It is important that we establish a secure connection before we start our ADP API integration process. It involves the following:
- Obtain Credentials: You will need credentials like client ID, client secret and CSR.
- Authentication: Understanding authentication process for API Integration is essential.
Use of Sandbox & Postman
It’s important to test your integration before making it live. You can use sandbox and postman.
The safe environment of sandbox will allow you to refine your integration wherever changes are needed, with sample data and thus not affecting your real data without risking security.
Important Terminology & Use Case for This Guide
ADP Workforce Now API
- ADP Workforce Now is a cloud based Human Capital Management (HCM) platform that streamlines HR processes from comprehensive reporting and analytics to payroll, benefits administration, payroll and much more. It works on a monthly subscription model.
- ADP Workforce Now subscribers benefit from streamlined data flow between payroll and other HR functions, reducing manual data entry errors.
- Another benefit of ADP Workforce Now, is it integrates with other HR business applications and has flexible service options.
- Being in the market from past 70 years and serving more than 90,000 clients, ADP has its strong base when it comes to needs related to overall HR management.
- For this guide, we will focus on API integration with ADP Workforce Now subscription.
All About ADP REST API
- REST (Representational State Transfer) API is standardized software architecture style, which is used for communication between client and server. A few benefits of REST APIs are: some text
- They are simple and standardized
- They are scalable and stateless
- The performance stays very high, and it supports caching.
- ADP REST API uses event-based pattern for resource management. Retrieving resources (GET API), modifying resources (POST API) and staying informed by setting up alerts whenever there is a change in GET/POST requests.
API Integration Methods
There are three methods to integrate ADP Payroll Integration API:
- Pre-built Data Connector: It is an available solution that can reduce development time, providing pre-configured settings and user-friendly interface ensuring faster setup.
- Customized Integration: If integration needs are very specific, requiring complete control over functionality and data, and have very specific security requirements, then customized integration is the best choice.
- Building own Integration for Workforce Now From Scratch: In this integration, you will directly integrate ADP Payroll API (likely the Payroll Data Input API v1) with your system. It requires higher development expertise.
Getting Started With ADP Payroll API
For this guide, we will work on building our own integration for ADP Workforce Now APIs for payroll. You will find several solutions under the Payroll Management section. ADP offers APIs for Earnings, Deductions, Tax Withholdings, and Payroll Results.
Getting Started With ADP HR API
We will also look into integration for ADP Workforce Now APIs for HR. APIs in HR are divided into various sections such as Workers, Workers Lifecycle, Data Integration Management, Workers Demographics, Compensation Management, Business Communication Management, and additional HR modules.
Obtain API Credentials & Set Up Authentication
Client Credentials
Follow the below steps to get client credentials:
- ADP Marketplace Account: You will need to register for an ADP Marketplace account on registration page if you already don't have one.
- Application Creation : Once registered, log in to your account and create a new application for your ADP API integration.some text
- Define application name, description, target ADP Product (in our case Workforce Now), type of integration (ex: Data Integration).
- Retrieve Credentials : In the application, find development API credentials.
All About CSR (Certificate Signing Request)
- CSR is specifically required if you plan to use a client certificate for mutual TLS authentication with the ADP API server. In that case, you can generate it using OpenSSL Library. Specific commands to run on the command line, can be found OpenSSL Documentation.
- The most common authentication method for Workforce Now API integrations involves OAuth 2.0. This will require a Client ID and Client Secret, which we can get by following this section.
OAuth 2.0 Authorization Flow & Access Tokens for Authorization.
- OAuth 2.0 Authorization Flow: Get Authorization Server URL from ADP Payroll Data Input API v1 documentation. Now your application will send a request with Client ID, Client Secret (Secure), and User Consent (if applicable). Upon user consent accepted (if asked), you will be redirected to a URL with an authorization code.
- Access tokens for authorization : Now your application sends another request to Authorization Server URL with: Client ID, Client Secret (Secure), and Authorization Code (if applicable). The server responds an access token for authorized API access.
Now this token can be used while accessing API of ADP Workforce Now resource server, by including token in authorization header.
Performing Basic Operations
Response & Request Exchange
- API Endpoints: Specific endpoints for various operations (such as GET/POST) are provided in the ADP developer documentation for the Payroll Data Input API v1.
- Request Response Exchange Format: The medium for communication between application and the ADP servers is JSON (JavaScript Object Notation). Request and Response data will be exchanged using JSON format.
- You can check Sample Response JSON for [GET] /events/payroll/v1/pay-data-input.modify/meta Pay Data Input ADP Doc.
- Note : You will need to enter the access token obtained from the OAuth 2.0 flow in the authorization header.
Setting Up Development Environment for Integration
- Choose your development language: You can select any programming language and development environment as per your comfort (e.g., Python, Java, etc.).
- Install libraries: Installation of necessary libraries or frameworks for making HTTP requests and handling JSON data is a must (e.g., requests library in Python).
Implementing ADP Payroll API Integration
Get API Credentials
You can get API Credentials that are Client ID and Client Secret by following this section. Once you have the API credentials, we can move on to the next step to understand the data structure, necessary for integration.
Data Mapping and Transformation for Integration Adaption
- Review Data Structures: Review the data structures provided in the ADP API documentation and compare them to your own internal data structures.
- Transformation Logic: If there are discrepancies, implement logic to transform your data to match the ADP API format before sending requests (e.g., converting dates or formatting names).
- For Example : Pay Data Input - [Pay Data Input Modify] section
[POST] /events/payroll/v2/worker-general-deduction-instruction.changesome text- Request JSON
{
- Request JSON
"events": [
{
"data": {
"eventContext": {
"worker": {
"associateOID": "{{employeeAOID}}"
},
"payrollInstruction": {
"payrollGroupCode": {
"codeValue": "{{payrollGroupCode}}",
"shortName": "94N"
},
"payrollFileNumber": "{{payrollFileNumber}}",
"payrollAgreementID": "{{payrollAgreementID}}",
"itemID": "169749147863_1",
"generalDeductionInstruction": {
"deductionCode": {
"codeValue": "M"
}
}
}
},
"transform": {
"effectiveDateTime": "2020-05-08",
"payrollInstruction": {
"generalDeductionInstruction": {
"inactiveIndicator": true,
"deductionRate": {
"rateValue": "20"
}
}
}
}
}
}
]
}
Response JSON with status code 200
{
"events": [
{
"data": {
"eventContext": {
"worker": {
"associateOID": "G34YJ69EMRR7N4VJ"
},
"payrollInstruction": {
"payrollGroupCode": {
"codeValue": "94N",
"shortName": "94N"
},
"payrollFileNumber": "4567",
"payrollAgreementID": "CC1_169737547546",
"itemID": "169749147863_1",
"generalDeductionInstruction": {
"deductionCode": {
"codeValue": "M"
}
}
}
},
"transform": {
"effectiveDateTime": "2020-05-08",
"payrollInstruction": {
"generalDeductionInstruction": {
"inactiveIndicator": true,
"deductionRate": {
"rateValue": "20"
}
}
}
}
}
}
]
}
Basic Read, Write API Calls
- API Endpoints: In this documentation you will find various payroll management APIs. You will also get data formats for the desired operations (e.g., reading employee information, updating pay elements).
- Construct Requests: Construct HTTP requests using the provided endpoints and request formats (typically JSON). Include the access token in the authorization header.
- Parse Responses: Parse the JSON response data from the ADP API and handle it according to your needs.
- In summary of the endpoint documentation of API you want to integrate, you will find important details for writing APIs like method path, content type, token type, and required scope.
- For example : some text
- Worker Pay Distributions - [Change Pay Distribution] section has one POST & GET API.
- [GET] /events/payroll/v1/worker.pay-distribution.change/meta : some text
- Optional parameters : ADP-Acting-SessionID , Sm_transactionid, SiteMinder transaction ID, $filter
- [POST] /events/payroll/v1/worker.pay-distribution.change : some text
- Optional parameters : ADP-Acting-SessionID, sm_transactionid
Implementing ADP HR API Integration
Follow Similar Steps to Payroll
- The steps to get API Credentials : Client ID and Client Secret can be found in this section.
- After getting the API Credentials, you can check for the API you are looking for ADP API Explorer.
- For this guide, we will go ahead with Workers APIs of HR section. The worker's management section, looks into how application can manage and access information about the workers in ADP Workforce Now application.
- One section of Workers is ‘Workers Data Retrieval’ and you can use the Workers v2 API to generate a full list of workers in your organization. It contains three GET request for retrieval of either single or collection of workers.
Examples of Read, Write API Calls With Data Transformation for HR API
Below are a few endpoints and information related to them :
- [GET] /hr/v2/workers some text
- Optional parameters : $skip, $top, ADP-Acting-SessionID, $filter, $select, $count, sm_transactionid.
- [POST] /events/hr/v1/worker.photo.uploadsome text
- Optional parameters : ADP-Acting-SessionID , sm_transactionid
Response :
{
"events": [
{
"data": {
"transform": {
"worker": {
"photo": {
"nameCode": {
"shortName": "photo",
"longName": "photo"
},
"links": [
{
"href": "/hr/v2/workers/G310YGK80NSS9D2N/worker-images/photo",
"mediaType": "image/jpg",
"method": "GET"
}
]
}
},
"effectiveDateTime": null
}
},
"links": []
}
]
}
Important Last Steps: Testing and Deployment
Testing API in Sandbox.
- ADP Sandbox Environment: Testing API in sandbox before making it live is important for several reasons such as : some text
- Performance Check & Safety :When you test your integration with fake data, you ensure your real data is safe, and you can also check the performance of your API. If you find that the integration is slow, you can optimize your integration before deployment.
- Error detection: While testing in the sandbox you can easily catch bugs and other error early on, thus fixing them before deployment to the live environment.
- Simulate Scenarios: Sandbox environment very well mimic the live environment, and thus it gives a clear picture of how your integration will behave in live environment.
Testing API in Postman
- API Testing: It provides a user-friendly interface, where you can easily test your GET, POST, PUT API’s request and response exchanges. This helps you get more clear picture of what get missed in your request and response and thus can lead to quick fixes.
- Automation: One widely used feature of Postman is automated test cases, reducing repeated actions of testing API behavior and thus reducing chances of human error.
- Collaboration: Postman allows team members to access same API collections, allowing your team to test API’s ensuring everyone is on same page.
Deployment Initiation of API’s
- Deployment Strategy: Your deployment strategy depends on your environment in which you have built the integration and other needs specific to your integration.
- Configuration Management: It is always a good practice to use configuration management tools, this ensures fewer chances of bugs in production (e.g., development, staging, production).
- Security Measures: Security should not be compromised, ensure security by implementing necessary security measures during deployment, for example: restricting access to sensitive data and APIs.
Troubleshooting and Support
Common Errors and Their Resolutions
- 401 Unauthorized: You are likely to receive this error due to issues with your access token. Check the following again:some text
- Client ID and Client Secret: Chances can be that they got expired or are wrong, ensure they are correct and haven't expired.
- OAuth 2.0 Flow: If you have more than one application in your marketplace, it is easy to get access token of wrong application, verify you’ve obtained valid access token.
- Token Expiration: Access tokens are temporary and expires in minutes or hours (for security purposes). Refresh them before they expire.
- 403 Forbidden: You will face this error when your application lacks the necessary permissions to access specific data or perform actions.
- Review API Scopes: Incomplete permissions for your application are very common issues faced by developers.
- 400 Bad Request: This indicates a problem with your request structure or data.some text
- Data Validation: Most of the time you will receive specific error messages regarding the data format or missing required fields.
- API Endpoints: Ensure you're using the correct API endpoint URL for the desired operation.
- 4xx or 5xx Errors: These can indicate various issues on the ADP server side.some text
- ADP Documentation: Refer to the ADP documentation for specific error code meanings and suggested resolutions.
Common Debugging Techniques
- Logging: It is always a good idea to do logging, it captures request/response details to track integration flow.
- Breakpoints: Sometimes errors can be logical, step through code to identify such errors.
- Network Inspection: Verify requests and responses using network tools.
- Postman: Isolating and testing APIs can be very useful in finding errors when you are working with a complex integration.
- ADP Support: If any of above doesn’t work, you can seek help from ADP Developer support.
Ensure Integration Smoothness
Integration Smoothness depends upon how well you are aware of issues you are facing while integration, if the issues are standard you will mostly be able to find their resolution in this section.
If you face specific errors, you can reach out to ADP developer support for clarification on error messages encountered during testing or deployment.
Appendix
A. Key Terms
- API: Lets applications talk to Workday (RESTful or SOAP).
- Authentication: Verifies you're who you say you are (login).
- Authorization: Grants access to specific Workday data (permissions).
- Client ID & Secret: Uniquely identify your application (secure handshake).
- Endpoint: Specific URL to access Workday functions (like a door to a room).
- OAuth 2.0: Secure way to get temporary access tokens (like a one-time pass).
- REST API: Flexible API using regular commands (GET, POST, PUT, DELETE).
- Sandbox: Test environment with dummy data (safe zone for experimentation).
- Token: Temporary permission to access Workday (like a short-term pass).
- Workforce Now : HR Software suite that helps businesses with HR, time, benefits, payroll
B. References
- Login & Registration for ADP Account
- ADP Restful API
- ADP Workforce Now products
- Workforce Now ADP API Integration
- Payroll Data Input API
- Payroll Data Input API Guide for ADP Workforce Now
- Oauth documentation
- Access Tokens
- Pay Data Input
- Forbes ADP Workforce Review
.png)
