> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lumos.com/llms.txt
> Use this file to discover all available pages before exploring further.

# UKG Pro

*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](/integrations/library/ukg/ukg-pro-hris).*

## 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

| Functionality | Type | Sync | Provision | Description |
| - | - | - | - | - |
| Users | Account | Yes | Yes | User account records and attributes from UKG. Lumos can create new hires, update primary and secondary email, and terminate employees (see below) |

| Provisioning Action | Type | Description |
| - | - | - |
| Create User | User | Creates a new hire via the SOAP EmployeeNewHire service (`NewHireUsa`) |
| Update Users Primary Email | User | Writes the user's primary email back to UKG |
| Update Users Secondary Email | User | Writes the user's secondary email back to UKG |
| Deprovision | User | Terminates the employee via the SOAP EmployeeTermination service (`TerminateEmployee`) |

**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](/integrations/library/ukg/ukg-pro-hris) 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

<Note>
  The API endpoints this integration uses are available to logged-in Lumos customers. [Log in](/login) to view them.
</Note>

## 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](/integrations/library/ukg/ukg-pro-hris) 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.