What employee, payroll, and benefits data is available from the UKG Pro API

Key takeaways

• The UKG Pro HCM API covers three data families: employee and HR, payroll and benefits, with a separate Workforce Management API for time and scheduling.
• Reads are broad. Writes exist for specific operations: new hires, job and compensation changes, contact data, custom fields, and pending deductions and earnings for payroll.
• Core HCM REST calls use Basic auth with a service account plus the US-Customer-Api-Key header. The service account's permissions decide what you can reach.
• UKG enforces per-client rate limits without publishing a number. Back off on 429.
• Deprecated endpoints get a 12-month sunset and a Warning header. Log it.

UKG Pro has an API for employee, payroll and benefits data. Whether it returns enough of each family to build on, and whether you can write anything back, is a different question, and it's the one most integration write-ups skip.

Scope a build around a payroll object that turns out not to exist, and you find out during implementation. Assume you can push a benefit election back, and you find out you can't the day a customer asks for it. Both mistakes come from an inventory that stops at naming the families instead of mapping what's inside them, and where the write paths actually are.

This page maps each family, lists the documented write paths, and covers the authentication, paging, rate limits and deprecation rules you'll build against. For UKG Pro's authentication models in depth, see our UKG Pro API authentication guide.

Employee and HR data

The employee family is the richest, and it's where most integrations start. Everything here is readable through the Core HCM REST API, subject to the service account's permissions.

If you want the general patterns first, our guide to employee data APIs covers the concepts this section assumes.

Payroll data

Payroll is where benefits and deduction integrations spend most of their time: reading what was deducted, and checking that what you sent actually landed.

Benefits data

Benefits data is readable in enough depth to reconcile elections against deductions, which is the job most benefits platforms need it for.

For the broader picture, see our guides to payroll APIs and employee benefits APIs.

Where you can write back, and where you can't

UKG Pro is often described as read-only. It isn't, but the write paths are specific, and most of them live in UKG's SOAP services rather than the REST API:

The practical rule: if your product needs to push a deduction to payroll, look at the Payroll Pending Items resources. If it needs to hire someone, look at the Employee New Hire service. If it needs to change a benefit election directly, plan for that to happen outside the public API. Scope this before you build, not after a customer asks.

Access mechanics: auth, paging, rate limits and deprecation

Getting the data model right doesn't help if the request never authenticates. Core HCM REST calls use HTTP Basic with a web service account, plus your tenant's US-Customer-Api-Key header:

curl "https://{service_host}/personnel/v1/person-details?page=1&per_Page=100" \
  -H "Authorization: Basic {base64(service_account_username:password)}" \
  -H "US-Customer-Api-Key: {customer_api_key}" \
  -H "Accept: application/json"

# {service_host} is tenant specific, e.g. service4.ultipro.com.
# Paging parameters are per endpoint; confirm them in the API reference.

Two of those deserve code. UKG's rate limiting guidance says a 429 isn't an error, just a request to slow down, and recommends at least a one-second pause or exponential backoff. Its deprecation strategy adds a Warning header, with the removal date, to responses from endpoints being retired. A client that handles both looks like this:

import os, time, logging
import requests

HOST = os.environ["UKG_SERVICE_HOST"]            # e.g. service4.ultipro.com
AUTH = (os.environ["UKG_SERVICE_ACCOUNT_USER"], os.environ["UKG_SERVICE_ACCOUNT_PASSWORD"])
HEADERS = {"US-Customer-Api-Key": os.environ["UKG_CUSTOMER_API_KEY"],
           "Accept": "application/json"}

def get_all(path: str, per_page: int = 100) -> list[dict]:
    session, rows, page, delay = requests.Session(), [], 1, 1
    while True:
        resp = session.get(f"https://{HOST}{path}", auth=AUTH, headers=HEADERS,
                           params={"page": page, "per_Page": per_page}, timeout=60)

        if resp.status_code == 429:
            time.sleep(int(resp.headers.get("Retry-After", delay)))
            delay = min(delay * 2, 60)
            continue
        delay = 1

        if "Warning" in resp.headers:
            logging.warning("UKG deprecation notice on %s: %s", path, resp.headers["Warning"])

        resp.raise_for_status()
        batch = resp.json()
        rows.extend(batch)
        if len(batch) < per_page:
            return rows
        page += 1

people = get_all("/personnel/v1/person-details")
print(len(people), "people")

Fitting UKG Pro data into your product's model

Every table on this page describes UKG Pro's shape: its object names, field names and codes. Your product almost certainly uses different ones, and if you pull from more than one payroll or benefits system, none of your other sources will match either. A deduction code like DEDCODE12 in UKG Pro and a field called pretax_401k somewhere else can describe exactly the same withholding, and nothing in either API tells you that.

That's the normalization problem, and it's separate from API access. A unified API sits in front of systems like UKG Pro and maps what each one calls a deduction, a dependent or a coverage tier into one model your product reads once.

Bindbee connects to 110+ HRIS, payroll, ATS and benefits systems through one API, UKG Pro among them, with 40+ unified data models:

• Benefits-ready models for employees, employments, dependents, benefits, employer benefits, dependent benefits, benefit coverages, and payroll runs with their deductions.
• Custom Fields for anything UKG holds that the unified model doesn't carry yet, mapped with a JMESPath expression instead of waiting on a release.
• Read and write through the same API, where the source system supports it.

Bindbee's UKG Pro connector uses the service-account path described above, which your customer's admin sets up following a published guide. Syncs run every 24 hours by default, adjustable per connection, and Bindbee sends a webhook when a sync finishes or finds changed records. For employee and benefits data, Bindbee is SOC 2 Type II and ISO 27001 certified, HIPAA and GDPR compliant, with a standard BAA template negotiated for enterprise agreements.

It isn't the right layer for every build. If you only need a handful of employee fields from one UKG Pro tenant, calling the API directly is simpler. The calculus changes once you're integrating more than one HRIS or payroll system. If you need change events from UKG itself, see our UKG Pro webhooks guide.

We build the integrations. You build the product.

FAQ

What data can you get from the UKG Pro API?

Employee and HR data (person, employment, job, compensation, contacts, custom fields), payroll data (pay statements, earnings, deductions, direct deposit, payroll configuration) and benefits data (plans, elections, coverage and contributions). Exact fields depend on the tenant's configuration and licensed modules.

Can you write data back to UKG Pro through the API?

Yes, for specific operations. UKG documents SOAP services for new hires, job and compensation changes, addresses, contacts and user-defined fields, and REST resources for sending pending deductions and earnings to payroll. We didn't find a general API for writing benefit elections in the public reference.

How do you authenticate to the UKG Pro HCM API?

Core HCM REST calls use HTTP Basic authentication with a web service account plus the US-Customer-Api-Key header. The service account's web service permissions decide which data it can read or write.

Does UKG Pro have API rate limits?

Yes. UKG's API gateway enforces per-client quotas over a window, normally one minute, and returns HTTP 429 when you exceed them. UKG doesn't publish a fixed number, and recommends waiting at least one second, or backing off exponentially, before retrying.

How does UKG Pro deprecate API versions?

UKG gives a sunset period of six months fully supported plus six months functional without support, marks deprecated operations in its API definition, and adds a Warning header to responses from deprecated endpoints.