Skip to main content

​
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.
This integration is for UKG Pro HCM. Kronos Workforce Central, UKG’s self-hosted timekeeping suite, has its own Kronos Workforce Central integration. UKG Pro Workforce Management (also called UKG Dimensions) has a separate API that this integration doesn’t cover.
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

​
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 on the UKG developer portal.
1

Sign in to UKG Pro as a system administrator

You need access to System Configuration > Security.
2

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.
3

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.
4

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.
5

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

​
Connect in Serval

1

Open the UKG Pro connect form

In Serval, add the UKG Pro integration to open the connect form. All four fields are required.
2

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.
3

Username

The service account username. It can’t contain a colon.
4

Password

The service account password UKG Pro generated.
5

Customer API Key

Your tenant’s Customer API Key from the same Web Services page.
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.

​
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.
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.

​
Gotchas and troubleshooting

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.
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.
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.
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.
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.
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.
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.
The action doesn’t include UKG Pro’s payroll endpoints (pay statements, direct deposit, pay registers). Contact support@serval.com if your workflows need them.