What is a Hyperfind?

A Hyperfind is a saved search for employees inside UKG Pro WFM. Think of it like a saved filter or a “smart list”: instead of picking employees one by one, you define a rule once (for example, “all active hourly employees in the US”), give it a name, and reuse it everywhere.

Whenever a part of UKG or an integration like ours needs to act on a group of employees, it can point at a Hyperfind and get back exactly that group. The Hyperfind does the filtering, you just reference it.

There are mainly two ways to reference a Hyperfind:

1. By name (“qualifier”): e.g. santosh-test.
2. By numeric ID: an internal number UKG assigns e.g. 5655. This is what most settings and fields want.

Why do we use Hyperfinds in the UKG Pro WFM integration?

A UKG Pro WFM tenant can hold thousands of employees: active, inactive, terminated, test records, and more. We almost never want to sync all of them blindly.

A Hyperfind lets the customer decide, inside their own UKG system, exactly which employees should flow into Kombo. In the Kombo integration settings there is a field called “Hyperfind ID for employee sync.”

Whatever Hyperfind you put there defines the population we pull on every sync. Change the Hyperfind in UKG, and the synced set changes automatically.

TLDR: the Hyperfind is the “who do we sync?” switch, owned by the customer, and read by us.

Key concepts you need to know

1. Name (qualifier) vs. numeric ID

Every Hyperfind has both a name and a numeric ID. The API can take either, but Kombo’s settings field needs the number. The catch: the UKG UI shows the name everywhere and hides the number, so getting the ID takes a small extra step (see How to set it up in Kombo? below).

2. Visibility and Display Profiles

Hyperfinds have a visibility setting:

Public – intended to be shared, but still only appears for users whose Display Profile includes it.

Personal – only the person who created it can see or use it. This matters a lot for integrations. Our sync runs as a dedicated service account, not as a human admin. Even a “Public” Hyperfind will be invisible to that account and the “list all Hyperfinds” API will come back empty unless the Hyperfind is included in the service account’s Display Profile. If a Hyperfind isn’t showing up or won’t execute, this is almost always why.

3. “For Home Employees” and the as-of date

The Kombo field expects a Hyperfind that covers active, inactive, and terminated employees, using the “as of today” date setting. When you build or choose a Hyperfind for sync, make sure its filter matches that otherwise you may silently sync the wrong population (for example, only currently-active people).

4. The built-in “All Home” HyperFind (ID -1)

UKG has a built-in “All Home” Hyperfind that some integrations use as a shortcut, referenced by the special ID -1. Be careful: it is not guaranteed to work. On our demo tenant, executing -1 was rejected with a permission error (WCO-112009). Don’t rely on -1; use a real, named HyperFind whose ID you’ve confirmed.

How a Hyperfind is used through the API?

The integration talks to UKG’s public REST API. The base URL is the customer’s tenant host, for example:

https://{tenant}.{region}.mykronos.com

1. Authentication Every request needs two things: a bearer access token and the appkey header. The token is obtained from the authentication endpoint; the appkey identifies the application.

POST /api/authentication/access_token

Headers:
appkey: {your-app-key}
Content-Type: application/x-www-form-urlencoded

Body: grant_type=password&username=...&password=...
&client_id=...&client_secret=...