How to access UKG Ready payroll and benefits data via API
Summarise the blog with AI
Key takeaways
- UKG Ready's REST reference groups resources into areas including Benefits, Payroll, HR & Talent, Time & Attendance, and Authentication. A payroll and benefits build mostly needs three.
- Every resource sits under
/ta/rest/v2/companies/{cid}, where{cid}is the numeric company ID, or the company shortname prefixed with|or!. - Calls authenticate with an OAuth 2.0 bearer token; backend integrations use the client credentials flow from an OAuth application in the customer's tenant.
- A practical extraction order: employees, then changed-employee polling, then payroll reference data, then employee payroll data, then benefits.
- UKG says to build on resource APIs, not the Report API, because reports aren't versioned and can change underneath you.
- Benefits carrier feeds aren't a REST resource in Ready's reference, so plan a separate delivery path, usually an EDI 834 file.
UKG Ready's API looks like one thing to connect to. For payroll and benefits it's three areas, each with its own resource shapes, reached through one path and one auth model.
Get the company identifier wrong and every call fails. Get the tenant's security profile wrong and a correct call still comes back with an authorization error that reads like a bug in your code.
This guide covers the benefits and payroll resources in Ready's REST reference, how to address and authenticate a call, the order to pull data in, and the two places a REST-only plan runs out.
What the UKG Ready API gives you
UKG Ready's public REST reference, at secure.saashr.com/ta/docs/rest/public, organizes resources into functional areas, including Authentication, Benefits, Payroll, HR & Talent, Time & Attendance, Leave of Absence, Recruiting, Company Management, and System. A payroll and benefits integration mostly touches three: HR & Talent for employees, Payroll, and Benefits.
This guide covers building directly against that surface. If you'd rather not maintain the connection yourself, Bindbee also connects to UKG Ready, and the build-versus-abstract question comes back at the end.
The benefits resources
Ready's Benefits area is small. Per the REST reference:
The employee-level resource is where most benefits pulls end up. The rest is reference data that gives it context, so poll it far less often.
The payroll resources, and the order to pull them in
Payroll is the bigger surface. Ready's Payroll area covers, among others:
The processing actions are writes that move a payroll through its lifecycle. A read integration should leave them alone.
A practical extraction order:
- Pull employees first. Everything downstream keys off employee IDs.
- Switch to changed-employee polling. Ready documents a changed employees resource (
/employees/changed), so later runs pull only who changed. - Load payroll reference data. Pay types, pay period profiles, and the earning, deduction, and tax code tables.
- Pull employee payroll data. Pay info, deductions, direct deposits, and pay statements, decoded against the code tables.
- Pull benefits. Employee benefit plans, now attached to employees you've already loaded.
- Use data exports for bulk needs. Ready offers data export resources; UKG's own best practices say to build integrations on resource APIs, not the Report API.
Dates are easy to parse: Ready's Foundations page says its date and time handling follows ISO 8601, for example 2016-09-15 and 2016-09-15T20:55:00Z. Polling is non-destructive too, since RFC 9110 defines GET as a safe method. The limit to respect is throttling: Ready uses a rolling 60-second window scaled by the company's active employee count, and UKG's best practices say to honor the X-CallLimit-TimeToWait header, or wait at least 60 seconds, when throttled.
If changed-employee polling is new territory, this guide to consuming employee-data APIs covers the general pattern.
Addressing a resource and authenticating the call
Path convention. Every resource sits under https://{HOST}/ta/rest/v2/companies/{cid}/.... Per Ready's Foundations page, {cid} is the company's numeric identifier by default. You can use the company shortname instead, but then it must be prefixed with | or !.
Auth model. Every request carries an Authorization: Bearer <access_token> header. Tokens come from POST /ta/rest/v2/companies/{cid}/oauth2/token. Ready supports two OAuth flows, both of which need an OAuth application configured in the customer's tenant first: client credentials for machine-to-machine integrations, and authorization code with PKCE for apps acting for a signed-in user. For a scheduled payroll or benefits sync, use client credentials. Our guide to UKG Ready API architecture and authentication walks through the setup.
Why a correct call can still fail
A documented endpoint, correctly addressed, can still return an authorization error. In Ready that's usually not a bug. Per Ready's docs, each request is authorized by checking whether the credential's security profile contains the security item the endpoint requires. If the tenant admin didn't grant it, the call fails no matter how correct your code is.
The same request against two customer tenants can therefore behave differently. Confirm the security profile behind the client credential before you spend an afternoon debugging.
When something does fail, Ready returns a standard HTTP status with an error body carrying a code and a message. Read that body first. UKG's best practices also say to follow 301, 302, and 307 redirects rather than treating them as errors.
Tenant permissions are the first seam in a REST-only plan. The second is more fundamental.
The carrier-feed seam, and the build-versus-abstract decision
Ready's Benefits area covers plans and employee enrollments. It has no carrier-feed resource, so getting enrollment data to an insurance carrier needs a second delivery path. That path is usually the 834 Benefit Enrollment and Maintenance transaction, X12 005010X220. This walkthrough of EDI 834's file layout covers the format in detail.
Stack it up: tenant-by-tenant security profiles, a payroll surface with dozens of resources to map, and a carrier feed that runs outside REST, multiplied by every Ready customer you onboard. Building it yourself is a real option. So is abstracting it.
Model coverage above is per Bindbee's model support reference. Customers such as Newfront and Healthee run on Bindbee today.
None of this replaces the customer's own tenant setup. The security profile behind the credential still decides what any integration can read, and confirming it is the one step this guide can't do for you.
The API surface isn't the hard part: a handful of resource areas, one path convention, one auth model, and an extraction order that holds across tenants. What breaks a REST-only plan is tenant permissions and a carrier feed that never touches REST. If you'd rather not build around those yourself, see how Bindbee's unified API works.
Frequently asked questions
Where does UKG Ready keep benefits data in its API?
In the Benefits area of Ready's REST reference: benefit type and plan lookups, company benefit plans, and employee benefit plans at /ta/rest/v2/companies/{cid}/employees/{aid}/benefits.
Is the pipe character required in UKG Ready API URLs?
Only when you use the company shortname. By default the company is identified by its numeric ID; a shortname must be prefixed with | or !.
Why does a documented UKG Ready endpoint return an authorization error?
Ready authorizes each request against the security profile of the credential making it. If that profile doesn't include the security item the endpoint needs, the call fails even when the path and token are correct.
Can I get benefits carrier data from the UKG Ready REST API?
Not as a REST resource. Ready's Benefits area covers plans and employee enrollments, so carrier delivery usually runs as a separate feed, typically an EDI 834 file.
Should I use the UKG Ready Report API for integrations?
UKG advises against it. Its best practices say to build integrations on resource APIs, because report content isn't versioned and can change without notice.
