iCIMS UKG Pro Integration Setup: A Consultant’s Complete Guide
Getting iCIMS UKG Pro integration setup right is the single biggest lever an enterprise recruiting team has for eliminating manual data entry, double keying, and the dreaded “why did this new hire show up in UKG with the wrong location” ticket. And it is also one of the easiest integrations to break if the setup team skips the field mapping step.
This guide walks through every decision and configuration step our consultants make when we run these projects: the three integration tiers, the prerequisites on both sides of the wire, how External IDs and Integration IDs actually connect the two systems, and the five problems that cause nearly every post-go-live ticket we see.
What’s in this guide
- What iCIMS UKG Pro integration setup actually does
- The three integration types: Flat-file, Configurable, and 3rd Generation API
- UKG Pro HCM vs UKG Pro Onboarding: choose the right path
- Prerequisites before you start
- Step-by-step: External ID and Integration ID field mapping
- How rehires, transfers, and terminations flow
- The 5 most common problems and fixes
- When to bring in an iCIMS consultant
- FAQ
What iCIMS UKG Pro integration setup actually does
At its core, iCIMS UKG Pro integration setup creates a trusted pipe that sends new hire records from iCIMS Applicant Tracking into UKG Pro, keeps shared reference data (work locations, departments, component companies) in sync, and writes back the UKG employee ID to the candidate record in iCIMS so both systems share a single source of truth.
That sounds simple. The complication is that iCIMS and UKG Pro do not share the same identifiers out of the box. Your “New York Office” in iCIMS has no way of knowing it corresponds to location code NY001 in UKG. Your “Finance” department in iCIMS does not know it maps to UKG department 4872. The entire integration is built on the premise that you populate External ID fields in both systems so records can find their counterparts.
Skip that step and the integration will fail silently. Do it correctly and the integration runs for years with no tickets.
New hires created in iCIMS land in UKG Pro automatically with the right employee type, department, location, and CoID. Requisitions opened in UKG are pulled into iCIMS without double entry. Reference data stays synchronized. Rehires match back to the original person record instead of creating duplicates.
The three integration types: Flat-file, Configurable, and 3rd Generation API
Before anything gets configured, the team has to pick an integration tier. This decision shapes the timeline, the cost, and what the integration can and cannot do. There are three options and they are not interchangeable.
| Type | How it works | Typical timeline | Best for |
|---|---|---|---|
| Flat-file | Batch CSV/XML file transfers over SFTP on a scheduled cadence, usually nightly | 4 to 6 weeks | Small to mid-market teams, low hire volume, limited IT capacity |
| Configurable (iCIMS Built) | Pre-built connector with field mapping configuration, one-way from iCIMS to UKG Onboarding | 6 to 10 weeks | Teams using UKG Onboarding as the handoff destination, with some custom fields |
| 3rd Generation API (HCM) | Real-time bidirectional API integration using UKG Pro’s modern endpoints | 8 to 12 weeks | Enterprise teams, high volume, custom fields, rehire logic, requisition sync |
Here is the call our consultants make most often. If you are running UKG Pro HCM as your system of record and your recruiting volume is anything above a few dozen hires a month, go with the 3rd Generation API integration. The flat-file option is only cheaper on paper. Once you add up the batch delay, the lack of error reporting, and the manual cleanup when a file fails to deliver, the total cost of ownership is higher than the real-time option.
If you are running UKG Pro Onboarding as a structured handoff step between ATS and HRIS, the Configurable integration is often the correct choice because it is purpose-built for that flow. We cover that distinction next.
Flat-file integrations cannot return write-back fields (like the UKG employee ID) to iCIMS in real time. If your downstream reports depend on knowing the UKG employee ID at the moment of hire, flat-file will create reporting gaps. Plan the reporting compromise before you commit to the tier.
UKG Pro HCM vs UKG Pro Onboarding: choose the right path
One of the most common sources of confusion in these projects is that UKG sells two separate products, UKG Pro HCM and UKG Pro Onboarding, and iCIMS builds two separate integrations: one for each.
UKG Pro HCM is the core HR system of record. The HCM integration takes a hired candidate from iCIMS and creates the employee record directly in UKG Pro HCM. This is the path most enterprise teams run.
UKG Pro Onboarding is a separate module that runs onboarding forms, document collection, tax forms, and task assignments between offer acceptance and day one. The Onboarding integration takes the hired candidate from iCIMS, sends them into UKG Onboarding first, and then UKG Onboarding writes the completed record into UKG Pro HCM once the new hire finishes their tasks.
Some organizations run only the HCM integration, some run only Onboarding, and some run both. The combined scenario is where architecture mistakes happen. In that setup, data flows iCIMS → UKG Onboarding → UKG Pro HCM, and every handoff introduces a field mapping gap. If you are going down that road, our team has published a deep dive on iCIMS onboarding setup that covers the ATS-to-Onboarding handoff logic in detail.
If UKG Onboarding is the formal tax form and I-9 collection tool, use the Onboarding integration. If UKG Pro HCM is the only HR system in play and onboarding happens elsewhere (inside iCIMS Onboard, inside a document management tool, or manually), use the HCM integration.
Prerequisites before you start
Every integration project we run starts with a readiness checklist. The same four items cause the majority of go-live delays, and every one of them needs to be completed before iCIMS or UKG provisions the endpoint.
Pull the UKG Pro reference data
Export the complete lists of work locations, departments, component companies (CoIDs), employee types, pay groups, and job codes from UKG Pro. These are the values that have to land in iCIMS External ID fields. Without them, nothing maps.
Inventory your custom fields
Walk through every user-defined field on the Person Profile and Job Profile in iCIMS that needs to sync to UKG. Each one requires a matching field in UKG Onboarding or UKG Pro HCM. If there is no counterpart, either add the field on the UKG side or accept it will not sync.
Identify your hire triggers
Determine which workflow step in iCIMS represents the “send to UKG” event. Most teams use the Hired status or a specific Onboarding bin transition. This single decision determines what data exists on the record at the time of hand-off.
Align your rehire strategy
Decide how rehires should be handled. If a terminated employee applies and is rehired, should the integration reactivate the existing UKG record or create a new one? This call determines the matching logic (usually Social Security Number or a customer-assigned unique ID) that UKG will use on inbound records.
Step-by-step: External ID and Integration ID field mapping
This is the core of the integration. Every iCIMS UKG Pro integration setup we have audited that failed in production failed here. Walk through each step carefully and do not skip the verification pass at the end.
On the iCIMS side: populate External IDs
External IDs are the fields where iCIMS stores “the value UKG knows this thing by.” You populate them on the profiles that UKG needs to resolve.
- Location profiles. Open each Location profile in iCIMS Admin, and in the External ID field enter the matching work location Code from UKG Pro (found under the Locations business rules in UKG Pro).
- Owner profiles. For each Onboarding Owner or Hiring Manager who needs to be assignable in UKG, enter the UKG Person ID in the External ID field on their profile.
- Component companies. If your organization uses multiple CoIDs in UKG, add the CoID value to the External ID field of each location profile (or wherever your organization has standardized the CoID assignment).
- User-defined fields. For each custom Person Profile or Job Profile field that should sync, set the External ID to the field key UKG expects.
On the UKG side: populate Integration IDs
Integration IDs are the UKG-side mirror of the iCIMS External ID concept. Navigate to the Field Mappings section of the UKG Onboarding Integrations page, and for each user-defined field enter the Integration ID and select the Profile (Person or Job) where it should write.
If a Location profile in iCIMS has no External ID populated, every candidate hired at that location gets rejected by UKG with a mapping error. The candidate appears Hired in iCIMS, no one checks UKG until the Monday sync report, and by then there are 14 missing new hires. Populate External IDs on every Location profile before go-live. Every single one.
Verify before you test
Before running an end-to-end hire, do two verification passes. First, in iCIMS, pull a list view of all Location profiles and confirm every External ID field has a value. Second, in UKG, open the Field Mappings page and confirm every required field has both an Integration ID and a Profile selected. Integrations rarely fail because the logic is wrong. They fail because one of these fields is empty.
How rehires, transfers, and terminations flow
The hire path is the one everyone tests. The three edge cases that break in production are rehires, transfers between component companies, and terminations that come back inbound from UKG.
Rehires. When a former employee is hired into a new iCIMS requisition, the integration needs a way to match them back to their old UKG record. The standard match key is the Social Security Number. The integration passes the SSN to UKG, UKG searches its employee table, finds a match, and reactivates rather than creates. If SSN matching is not enabled, or if the SSN field is not populated on the iCIMS record at the time of hire, you get a duplicate employee in UKG.
Transfers. Internal mobility candidates who apply to a second requisition while still employed require explicit handling. Most integrations treat them as rehires with a re-assignment to a new location, department, or CoID. The integration cannot know which of these changed without being told. Document the rule, test it, and make sure the HRIS side accepts the update payload.
Terminations. The HCM integration typically writes terminations back to iCIMS so that former employees do not show as active candidates. This requires the UKG-to-iCIMS direction to be enabled and the iCIMS Person Profile to have the correct field mapped to receive the termination date. Teams often assume this happens automatically. It does not.
The 5 most common problems and fixes
1. New hires not landing in UKG
What’s happening: Candidates are marked Hired in iCIMS, but no record appears in UKG Pro.
Why: In 9 out of 10 cases, the Location profile, Owner profile, or CoID has an empty External ID. UKG cannot resolve the value and rejects the record. In the remaining cases, the workflow step that triggers the integration has not been set correctly.
Fix: Pull the iCIMS integration error log for the last 7 days. Every rejection names the field that failed to resolve. Populate the External ID on that profile and resubmit the failed records.
2. Duplicate employees in UKG after a rehire
What’s happening: A former employee is rehired and UKG now has two records for them, one active and one terminated.
Why: SSN matching was not enabled at go-live, or the SSN field was not populated on the iCIMS record before the Hired transition.
Fix: Enable SSN matching on the UKG side, merge the duplicate records manually, and audit the iCIMS workflow to ensure SSN is a required field before the Hired status. Do not fix duplicates one at a time without also fixing the upstream trigger or the problem recurs.
3. User-defined fields not syncing
What’s happening: A custom field (for example, a safety clearance level or an I-9 acknowledgment) is populated in iCIMS but empty in UKG.
Why: The External ID on the iCIMS side and the Integration ID on the UKG side were not aligned. Or the field was created after the initial integration configuration and was never added to the Field Mappings page.
Fix: Open the UKG Field Mappings page, confirm the Integration ID matches the iCIMS External ID exactly, and confirm the correct Profile (Person or Job) is selected. Re-run a test hire to validate.
4. Work location written to UKG as “Unknown”
What’s happening: New hires land in UKG but the location defaults to the parent organization or to an “Unknown” fallback.
Why: The Location profile in iCIMS used for the requisition has an External ID that does not match any work location Code in UKG. UKG falls back to a default instead of rejecting, which makes the problem harder to spot.
Fix: Export the UKG Locations business rules, compare the codes side by side with iCIMS External IDs, and correct mismatches. Keep the reconciliation file as a source of truth and audit it quarterly.
5. Terminations not flowing back to iCIMS
What’s happening: A former employee remains flagged as active in iCIMS long after they were terminated in UKG.
Why: The return path from UKG to iCIMS was never enabled, or the Person Profile field that receives the termination date was not mapped.
Fix: Confirm bidirectional sync is enabled, add the termination date mapping on the UKG-to-iCIMS direction, and backfill historical terminations with a one-time data load from UKG.
Both iCIMS and UKG maintain integration error logs. They are the first place to look when something looks off. In iCIMS, the integration monitor shows outbound failures with the exact field that caused the rejection. In UKG, the inbound processing log shows the raw payload and the resolution outcome for each record.
Running into integration issues you can’t trace?
We have run dozens of iCIMS UKG Pro integration setup projects. If you are stuck on a mapping error or planning a new rollout, we can help you unblock it in a single working session.
Book a discovery callWhen to bring in an iCIMS consultant
Not every iCIMS UKG Pro integration setup needs outside help. If your IT team has implemented HRIS integrations before, your hire volume is predictable, and your field structure is clean, you can run the project internally and lean on iCIMS and UKG support for the connector-specific steps.
The scenarios where our team typically gets called in fit three patterns. The first is a failed or stalled project that already went live with mapping errors and is bleeding trust. The second is a greenfield implementation with multiple component companies, complex location taxonomies, or custom field structures that need to be architected before the vendors are engaged. The third is a post-M&A integration where two previously separate iCIMS and UKG environments need to merge without breaking reporting continuity.
If any of those sound familiar, our iCIMS consulting services and iCIMS managed services cover both short-term project rescue and ongoing support. And for teams earlier in the journey, our guides on iCIMS Workday integration setup and iCIMS ADP Workforce Now integration cover the parallel integration patterns for the other two major HRIS platforms.
Frequently asked questions
The 3rd Generation API integration syncs in near real time on hire events and scheduled refreshes for reference data. Flat-file transfers run on a batch schedule, typically nightly, which means new hires and location updates can take hours to appear.
The HCM integration sends new hires from iCIMS directly into UKG Pro core HR and keeps reference data like locations and departments in sync. The Onboarding integration hands the candidate off to UKG Pro Onboarding first, which runs forms and tasks, then passes the completed record into UKG Pro HCM. Some customers use one, some use both.
A flat-file transfer can go live in roughly 4 to 6 weeks. A Configurable or 3rd Generation API setup typically takes 8 to 12 weeks because field mapping, testing, and rehire logic all need to be validated before go-live.
The most common cause is an unmapped External ID on the location profile, owner profile, or CoID. When UKG cannot resolve one of these values, the record is rejected and silently fails. Check the integration error log and the External ID fields in iCIMS before touching anything else.
Yes, but rehire matching is the most common post-go-live issue. The integration relies on the Social Security Number or an equivalent unique identifier to match a candidate back to an existing UKG person record. If matching logic is not configured, the integration creates a duplicate employee record instead of rehiring.
Yes. iCIMS enables the integration on their side and provisions the connection. UKG provides the Person IDs, location codes, and CoIDs and configures the UKG endpoints. Both vendors need to be engaged, and the configuration cannot be completed unilaterally.
Ready to get your iCIMS and UKG Pro talking to each other?
We scope, implement, and troubleshoot iCIMS UKG Pro integrations for enterprise recruiting teams. Whether you are planning a new rollout or rescuing a stalled one, our certified consultants can get you unblocked.
Talk to an iCIMS consultant
