ADP Workforce Now is the payroll system of record for millions of companies. But their API is complex, uses mutual TLS authentication, and has a learning curve that most HR software vendors avoid entirely — opting instead for CSV exports and manual data entry.
We built a full bidirectional integration. Here's everything we learned.
Authentication: mTLS
ADP uses mutual TLS (mTLS) — both the client and server present certificates. This means:
- You need a client certificate and private key issued by ADP
- Every API request must present these credentials
- Certificates expire and need rotation
We store certificates encrypted in AWS S3 using Fernet symmetric encryption. The encryption key lives in environment variables. For each API call, we download the certificates to a temporary directory, use them for the request, then clean up. This keeps credentials out of the filesystem permanently.
The Onboarding Flow
When a new hire completes onboarding in Sluble, we call ADP's /hcm/v2/applicant.onboard endpoint. This requires:
- Onboarding template code (fetched from ADP meta API)
- Payroll group code
- Employee name and hire date
- Up to 50+ optional field mappings (address, SIN, job code, work location, etc.)
The response includes an AssociateOID — ADP's unique identifier for the employee. We store this and use it for all subsequent API calls. The action is marked as "pending" until HR completes the process in ADP WFN and the employee becomes "Active."
Field Mappings
One of the most powerful features is our field mapping system. Admins configure which Sluble employee fields map to which ADP fields — through a visual UI that fetches the available fields directly from ADP's meta endpoint. We support system fields (name, email, phone, address), custom employee fields, expiry dates, and fixed values.
Post-Hire Actions
After the employee is activated in ADP, we trigger post-hire actions automatically:
- Add deductions (union dues, benefits, garnishments)
- Set license expiry dates for compliance tracking
- Configure organizational units and work locations
Bidirectional Sync
The sync worker runs on a configurable schedule with pause windows to avoid peak hours. It pulls employee data from ADP and updates our database — keeping names, addresses, and employment status in sync. Each sync run is logged with employee count, entries upserted, and any errors.
Lessons Learned
- Test with real credentials early — the sandbox environment doesn't behave like production
- Cache tokens aggressively — ADP token requests are slow; cache with a 60-second buffer before expiry
- Handle partial failures gracefully — some fields may fail while others succeed; log each field individually
- Log everything — ADP errors are cryptic; detailed request/response logs are essential for debugging
- Respect the meta endpoint — always fetch available fields from ADP's meta API rather than hardcoding field paths