Skip to main content
Lumos offers two UKG Pro connectors, each its own integration card. This article covers UKG Pro (HCM). It syncs users and attributes, creates new hires, writes a user’s primary and secondary email back to UKG, and terminates employees. For the Merge.dev-powered HRIS integration, use UKG Pro.

​
After this article

You will be able to connect the native UKG Pro connector to Lumos to sync users and their attributes, create new hires, write users’ primary and secondary email back to UKG, and terminate employees from Lumos.

​
Capabilities

Sync behavior: Lumos maps each employee’s ID, email, name, and username, and surfaces the rest of the person record, employment details, and user-defined fields as custom attributes you can select in Lumos. After the first full sync, Lumos syncs incrementally using UKG’s change-date filter. Lumos also reads each user’s last login date, so inactive accounts show up in reviews. UKG Pro is an HR system, so the connector syncs people rather than permissions. Groups, roles, and entitlements aren’t synced. Provisioning behavior:
  • Create: Lumos submits a new hire over SOAP (NewHireUsa) with a UKG Company Code, first name, and last name. Email is optional, and leaving Employee Number blank lets UKG assign one. This action isn’t idempotent, so a retry can create a duplicate record.
  • Update email: Lumos resolves the employee number from the REST employment-details endpoint, reads the person record over SOAP, and writes the new primary or secondary email while preserving every other field. If the emails already match, Lumos skips the write.
  • Deprovision: Lumos terminates the employee over SOAP (TerminateEmployee). The termination date, last day worked, and paid-through date are all set to the day the action runs (UTC), and the record is marked not eligible for rehire. This action isn’t idempotent. Future-dated terminations aren’t supported, so run those in UKG Pro directly. There is no separate suspend action, so treat Deprovision as a real termination in UKG.

​
Required plan and roles

  • UKG Pro role: an administrator with access to System Configuration > Security is needed to copy the Customer API Key and create the service account.
  • Credentials: the connector uses Basic authentication with a UKG Web Service Account plus two API keys. You will collect four values: the service account Username and Password, the Customer API Key, and the User API Key.
  • Web service permissions: grant the service account these permissions in its Web Service section:
    • Personnel Integration: View (Edit for provisioning)
    • Employee Person Details: View
    • User Defined Fields: View (Edit for provisioning)
  • Read-only option: grant only the View permissions. Lumos syncs users, custom attributes, and last login, but the create, email update, and terminate actions won’t work.

​
Instructions

Phase 1: Copy the Customer API Key
  1. Log in to UKG Pro as an administrator.
  2. Go to System Configuration > Security > Web Services.
  3. The Customer API Key is displayed at the top of the page. Copy it.
Phase 2: Create a service account
  1. On the same page, click Add (+) to create a new service account.
  2. Enter a Username and Email.
  3. In the Web Service section, check View for Personnel Integration, Employee Person Details, and User Defined Fields. Check Edit on Personnel Integration and User Defined Fields if you want Lumos to provision.
  4. Click Save. A pop-up displays the account’s Password. Save it immediately. It can’t be retrieved later.
  5. Copy the service account’s User API Key (UKG also calls this the UserAccessKey). It’s displayed with the service account details.
Phase 3: Connect in Lumos
  1. In Lumos, go to Settings → Integrations and choose the native UKG Pro card, shown as UKG Pro (HCM) and NOT tagged HRIS. (The card tagged HRIS is the Merge.dev-powered UKG Pro integration.)
  2. Enter the Account Domain: the host of your UKG Pro URL without https:// or any path. If you log in at https://service5.ultipro.com/..., enter service5.ultipro.com.
  3. Enter the service account Username and Password.
  4. Enter the Customer API Key and the User API Key.
  5. Click Connect.

​
API Endpoints Used

​
Troubleshooting

You see two UKG Pro cards and aren’t sure which to pick. This native connector is shown as UKG Pro (HCM), the card that is NOT tagged HRIS. The card tagged HRIS is the Merge.dev-based UKG Pro integration. “Invalid credentials. Please verify that your Customer API Key, User API Key, and username/password are correct.” UKG returns a not-found response when any credential is wrong, so this error covers all four values. Also confirm the Account Domain matches your tenant’s host exactly. “UKG SOAP authentication failed” The sync credentials are fine but the SOAP login was rejected. Check the User API Key, and confirm the service account has the Edit web service permissions for the provisioning action you attempted. A new service account’s password was lost. The password is only shown once, in the pop-up at creation. Reset it from the service account’s page in UKG Pro, then update the credential in Lumos. Employees re-sync without changes. UKG’s change filter accepts only a date, not a time. Employees modified earlier on the same day as a sync can appear again in the next one. No action needed. Deprovision dated the termination to today. That’s how the connector works. It sets the termination date, last day worked, and paid-through date to the day the action runs. For a future-dated termination, process it in UKG Pro instead of running Deprovision from Lumos.