UKG Ready API: architecture, authentication, and data access

Key takeaways

• UKG Ready runs its own REST API, separate from UKG Pro/WFM and HR Service Delivery, each with different endpoints, auth, and docs.
• Authentication is tenant-specific: a machine-to-machine OAuth application in the customer's tenant issues a client ID and secret, which you exchange for a bearer token.
• UKG Ready documents a 7-day refresh-token lifetime; read expires_in from every token response instead of hardcoding an expiry.
• You can reach employee, timesheet, accrual, pay, and schedule data through REST calls, reports and exports, and webhooks.
• Throttling surfaces as 429 or 503 responses, and the standard response is to back off using whatever wait indicator the response carries.

UKG Ready has its own REST API. So does UKG Pro/WFM. They are different products with different endpoints, different authentication, and different documentation, and mixing them up is the single most common way to lose a day integrating with a customer's UKG Ready tenant.

Build against the wrong docs and credentials that authenticate cleanly still return 404s on every endpoint you expected. Copy a token lifetime or rate-limit figure from the wrong product's page and your integration passes testing, then behaves differently in production against the tenant you connected to.

UKG Ready exposes its data through a tenant-specific REST API covering employees, timesheets, accrual balances, pay information, and schedules, plus webhooks for change notifications. You authenticate to one customer's tenant with credentials that customer issues, never a shared, product-wide UKG credential.

This page covers UKG Ready specifically: how the API is structured, how the auth flow works end to end, what data you can reach and through which pattern, how the tenant enforces rate limits, and how to decide whether to build the connector yourself.

What is the UKG Ready API, and how is it different from UKG Pro/WFM?

UKG Ready is not "the UKG API." UKG's product lines, Ready, Pro/WFM, and HR Service Delivery, ship separate APIs, separate authentication mechanics, and separate documentation, and credentials or endpoints that work against one will not work against another. The most common integration mistake at this stage is landing on the wrong product's page and building against endpoints your tenant doesn't have.

UKG's Developer Hub (developer.ukg.com) covers Pro, Pro WFM, HR Service Delivery, and Talk. For Ready, it links out to the REST documentation hosted on Ready itself, under /ta/docs/rest/public. Make sure that's the reference you're reading. If you landed here still deciding which product you're looking at, the broader guide to UKG's API surface covers all of them; this page stays on Ready.

Inside UKG Ready, the API organizes a tenant's data by resource path under a company ID, and two levels do most of the work. Most integration traffic lives at the employee level, since that's where the timesheets, accruals, and pay data your product needs are attached.

• Company-level resources: organization structure, pay groups, tenant-wide configuration, under /ta/rest/v2/companies/{cid}.
• Employee-level resources: profile, demographics, pay information, and more, scoped to one person under /ta/rest/v2/companies/{cid}/employees/{id}.

Once you know which product and which documentation you're reading, the next question is how you get a token that UKG Ready will accept.

How do you authenticate to a UKG Ready tenant?

Authentication to UKG Ready is tenant-specific: you authenticate against a single customer's Ready instance, using credentials that customer's admin creates. UKG Ready documents OAuth 2.0 for this, with an OAuth application set up inside the tenant. For a backend integration, that application is the "Machine to Machine" type and uses the client-credentials grant; the "Interactive" type, with authorization code and PKCE, is for acting on behalf of a signed-in user.

curl -X POST "https://$HOST/ta/rest/v2/companies/$COMPANY_ID/oauth2/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "client_id=$CLIENT_ID&client_secret=$CLIENT_SECRET&grant_type=client_credentials"

curl "https://$HOST/ta/rest/v2/companies/$COMPANY_ID/employees" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json"

The Authorization header itself isn't a UKG invention: RFC 6750 defines the Bearer scheme as the standard way to present an OAuth access token to a protected resource, and UKG Ready follows it.

On token lifetimes, UKG Ready's own documentation says refresh tokens expire after 7 days. UKG's Pro WFM documentation gives 8 hours, which is where conflicting numbers online come from. Either way, read expires_in from each token response and renew from that, rather than building a fixed expiry into your code.

Older Ready integrations use a different login: a company API key plus a dedicated service-account username and password, sent to a legacy login endpoint. Many vendor integrations still run that way. Our guide to UKG Ready API credentials covers both models and how to provision each.

If you're weighing whether to hand-roll this flow at all, a unified API's equivalent authentication step shows what the same problem looks like once it's abstracted away.

With a token in hand, the next question is what it lets you reach.

What data can you reach, and through which access patterns?

A valid token against a UKG Ready tenant reaches employee, timesheet, accrual, pay, and schedule data, limited by the security profile behind it and organized the same way the resource paths are: company level and employee level. What differs by domain is less the data itself than how you're expected to pull it.

Three patterns cover almost everything in that table. Direct REST calls suit individual records and on-demand lookups. Reports and exports suit bulk pulls: syncing a whole population of employees or a full pay period at once. Webhooks suit the case where you don't want to poll: a tenant admin sets up subscriptions under Global Setup > Webhook Subscriptions, picks the fields that should trigger each one, and Ready posts the latest values to your endpoint when any of them change.

Plan for delivery failures. Ready logs failed webhook events and retries them in a nightly job, up to five attempts in total, so an endpoint that's down for a week loses events. Treat a notification as a trigger to re-read the record, and keep a scheduled pull as the backstop.

For patterns specific to pulling employee data at volume, this deeper guide to employee-data APIs works through the tradeoffs between polling and webhooks in more detail.

Pull enough of this on a schedule and you'll eventually meet the tenant's limits, which is the next thing worth understanding before you build against it.

How does UKG Ready handle rate limiting and transient errors?

UKG Ready enforces rate limits per tenant. The specific figure that circulates online comes from a single, unverified source rather than UKG's own documentation, so this page won't repeat it. What's reliable, because it comes from the HTTP standards UKG Ready's error responses follow, is how the limit surfaces and what a well-behaved client does about it.

Two status codes carry almost all of the signal:

• 429 Too Many Requests: you've exceeded the tenant's rate limit within the current window; back off before retrying, using any wait indicator the response includes.
• 503 Service Unavailable: a temporary overload or maintenance condition; a Retry-After header, when present, states how long to wait before trying again.
• Increase the delay on each retry: a fixed interval will keep tripping the same limit.

The 429 response comes from RFC 6585, which defines Too Many Requests as the standard way a server signals a client-side rate limit. The 503 behavior, including the Retry-After convention, comes from RFC 9110, the current HTTP standard.

For the broader retry and backoff hygiene that applies here and to most rate-limited APIs, this guide to integration best practices covers the pattern in more depth.

None of this is exotic: it's the standard shape of a rate-limited REST API. What it does mean is that someone has to build it, watch it, and keep it working as UKG's tenant behavior shifts, which leaves one question: do you want to be that someone?

How do you reach UKG Ready without building and maintaining the connector yourself?

Three paths get you from a customer's UKG Ready tenant to your product. You can build directly against the auth flow and data map above, and maintain it yourself as UKG's documentation, auth models, and tenant behavior shift. You can put a middleware layer in front of it, which still requires understanding Ready's auth and object model underneath. Or you can connect through a unified API that has already mapped UKG Ready, and the other systems you'll eventually need, into one interface.

Bindbee is one example of that third path. It connects to 102+ HRIS, payroll, ATS, and benefits systems, including UKG Ready, through a single API, using each tenant's own API credentials and never by logging into the UI and scraping screens. Healthee, Newfront, and Papershift run on it today.

Data syncs on a 24-hour default schedule that can be adjusted per connection, and webhooks fire when a sync finishes or fails, or when a sync finds changed records. Read and write both work: Bindbee supports writing back into the connected system, not only pulling data out of it.

The tradeoff is control. Building directly gives you the exact behavior described on this page with nothing abstracted away, at the cost of watching UKG's documentation for the next auth or throttling change yourself. A unified API trades some of that control for not having to be the one who catches it.

If that maintenance surface is the part you'd rather not own, Bindbee's UKG Ready connector is already built; Newfront went from a 12-week HRIS integration cycle to a first sync in 48 hours. See the full unified API if UKG Ready is one of several systems you need to reach. We build the integrations. You build the product.

Frequently asked questions

Does UKG have an API?

Yes, but not one API: UKG Ready exposes its own tenant-specific REST API and webhooks, and UKG's other products, Pro/WFM and HR Service Delivery, each ship separate APIs and separate documentation. If you're integrating with a UKG Ready tenant, stay within Ready's own REST documentation; the docs for the other products describe a different endpoint set and a different auth flow.

How long does a UKG Ready access token last?

Each token response says so in expires_in; UKG's sample shows about 30 minutes. Refresh tokens expire after 7 days, per UKG Ready's documentation. Renew based on the response rather than a hardcoded timer, since UKG notes lifetimes can change.

How does UKG handle the approval process for time-off requests?

The approval workflow is configured inside the tenant, not through the API. Time-off requests and balances are reachable as data, and the resulting state, requested, approved, rejected, or canceled, reaches your integration through a REST read or a time-off webhook event when it changes.

How do you see employee PTO in UKG?

For a one-off look, employee PTO lives in UKG Ready's own interface. For an integration, PTO maps to the time-off and accrual balance data under the employee-level resources (/ta/rest/v2/companies/{cid}/employees/{id}), subject to whatever the calling credential's security profile allows.