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

# UKG Pro

> Connect UKG Pro (formerly UltiPro) to Serval so workflows can read employee, employment, and org data on demand through a dedicated UKG Pro service account.

## About UKG Pro

UKG Pro (formerly UltiPro) is UKG's cloud human capital management suite, covering core HR, payroll, benefits, and talent. The Serval integration connects to your UKG Pro tenant through a dedicated service account, so workflows can look up employees, track new hires, job changes, and terminations, and read your company's org structure.

<Note>
  This integration is for **UKG Pro HCM**. Kronos Workforce Central, UKG's self-hosted timekeeping suite, has its own [Kronos Workforce Central integration](/sections/integrations/kronos). UKG Pro Workforce Management (also called UKG Dimensions) has a separate API that this integration doesn't cover.
</Note>

**Authentication:** A UKG Pro service account using HTTP Basic authentication, plus your tenant's Customer API Key. Serval adds both to every request to your tenant. There is no OAuth flow or token refresh, so the stored password has to keep matching UKG Pro.

**Data sync:** On demand only. Serval doesn't run a background sync or install pre-built workflows. All reads and writes happen inside workflow runs. Four health checks verify the connection.

## What the UKG Pro integration enables

| Capability                 | Description                                                                                                                                                                                                 |
| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| UKG Pro API request action | On-demand calls to UKG Pro's REST API from any workflow. Serval handles sign-in automatically. The action covers the Employee Data, Configuration Setup, Platform Configuration, and Security API families. |
| Employee lookups           | Person details (names, email addresses, addresses), employment details (job, status, supervisor, hire and termination dates), demographics, compensation, contacts, job history, and user-defined fields.   |
| Change tracking            | Employee changes by employee or by date range, for joiner, mover, and leaver workflows.                                                                                                                     |
| Org structure              | Company details, org levels, jobs, positions, locations, and code tables.                                                                                                                                   |
| PTO plans                  | Read, create, and update employees' PTO plan records. UKG Pro applies these directly, without its approval workflow.                                                                                        |
| Security users             | UKG Pro user details and roles.                                                                                                                                                                             |
| Connection health checks   | Four built-in checks that verify your credentials and the web service permissions Serval needs.                                                                                                             |

## Get your credentials

Serval connects as a UKG Pro service account. UKG Pro grants a service account access one web service at a time, and the health checks verify the minimum set listed below. For UKG's own reference, see [Web Service Account](https://developer.ukg.com/hcm/docs/web-service-account) on the UKG developer portal.

<Steps>
  <Step title="Sign in to UKG Pro as a system administrator">
    You need access to **System Configuration > Security**.
  </Step>

  <Step title="Create a service account">
    Go to **System Configuration > Security > Service Account Administration** and click **Add**. Give it a recognizable username, for example `serval-integration`. UKG Pro generates the password and shows it only once, so copy it before you leave the page.
  </Step>

  <Step title="Grant the web services the health checks verify">
    Give the service account the **View** role for **Company Configuration Integration**, **Employee Person Details**, and **Personnel Integration**.
  </Step>

  <Step title="Grant optional web services for your workflows">
    Add the **View** role for any other web service your workflows read, for example **Employee Compensation Details** or **Employee Contacts**. Each endpoint's reference page on the UKG developer portal names the web service it needs. Grant **Add** or **Edit** only for the specific services your workflows write to.
  </Step>

  <Step title="Note your service endpoint host and Customer API Key">
    Go to **System Configuration > Security > Web Services**. Copy the host from the service endpoint address, for example `service4.ultipro.com`, and copy the **Customer API Key**.
  </Step>
</Steps>

<Note>
  Only grant the web services your workflows need. The service account can read or change exactly what its roles allow, and Serval can't narrow that further.
</Note>

## Connect in Serval

<Steps>
  <Step title="Open the UKG Pro connect form">
    In Serval, add the **UKG Pro** integration to open the connect form. All four fields are required.
  </Step>

  <Step title="Service Endpoint Host">
    The host from **System Configuration > Security > Web Services**, for example `service4.ultipro.com`. You can paste the full service address (for example `https://service4.ultipro.com/services/`), and Serval keeps only the host. Serval accepts only UKG Pro hosts: service or rental hosts on `ultipro.com`, Canadian hosts on `ultipro.ca`, and regional gateway hosts on `ukg.net`.
  </Step>

  <Step title="Username">
    The service account username. It can't contain a colon.
  </Step>

  <Step title="Password">
    The service account password UKG Pro generated.
  </Step>

  <Step title="Customer API Key">
    Your tenant's Customer API Key from the same **Web Services** page.
  </Step>
</Steps>

<Note>
  When you reopen the connection to edit it, the saved password and Customer API Key appear masked. Leaving a masked field untouched keeps the stored value, so you can update the password or key on its own. The host and username identify the connection and can't be changed; to point at a different host or service account, add a new UKG Pro connection.
</Note>

## Verifying the connection

**Test UKG Pro Connection** fetches one company record, which confirms the host, credentials, Customer API Key, and the **Company Configuration Integration** permission.

* Pass: "Successfully authenticated with UKG Pro and retrieved \[number] company record"

**Read UKG Pro Person Details** reads one person record, which needs the **View** role for **Employee Person Details**.

**Read UKG Pro Employment Details** reads one employment record, which needs the **View** role for **Personnel Integration**.

**Read UKG Pro Org Levels** reads your active org levels, which needs the **View** role for **Company Configuration Integration**.

<Tip>
  If the connection test passes but a later check fails, your credentials are fine. The service account is missing that check's web service, and the failure message names it.
</Tip>

## Gotchas and troubleshooting

<AccordionGroup>
  <Accordion title="The host field rejects the value you pasted">
    Serval accepts only UKG Pro service hosts, because it sends your credentials to that host. Copy the host from **System Configuration > Security > Web Services** rather than your browser's address bar. The address you sign in to UKG Pro with isn't the API host.
  </Accordion>

  <Accordion title="Every check fails with a 401">
    One of the username, password, or Customer API Key is wrong. Re-copy the Customer API Key from the **Web Services** page. If you no longer have the password, reset it in **Service Account Administration** and update the connection.
  </Accordion>

  <Accordion title="The connection stops working after a password change">
    Serval stores the password and sends it on every request. If the service account password changes in UKG Pro, edit the connection and enter the new one.
  </Accordion>

  <Accordion title="Large lists come back in pages">
    List endpoints take `page` and `per_Page` query parameters and return at most 10,000 records per page. Loop on `page` until a page returns fewer records than you asked for.
  </Accordion>

  <Accordion title="Requests fail with 429 Too Many Requests">
    UKG Pro rate limits API calls but doesn't publish the limits. Space out bulk reads and retry after a short wait. UKG asks callers to query employee changes no more than eight times a day.
  </Accordion>

  <Accordion title="The employee ID lookup returns a 403">
    UKG Pro sends the employee ID lookup as a POST so identifiers stay out of the request address, and it requires both the **View** and **Add** roles for **Personnel Integration**. It doesn't change any data.
  </Accordion>

  <Accordion title="Creating, terminating, or rehiring employees">
    UKG Pro's REST API doesn't support new hires, terminations, or most employee record updates. UKG offers those only through its SOAP web services, which this integration doesn't cover.
  </Accordion>

  <Accordion title="Payroll data isn't available">
    The action doesn't include UKG Pro's payroll endpoints (pay statements, direct deposit, pay registers). Contact [support@serval.com](mailto:support@serval.com) if your workflows need them.
  </Accordion>
</AccordionGroup>