UKG (platform)
UKG is a human capital management suite with three product lines behind one developer hub: UKG Pro (HCM, payroll and Recruiting), UKG Pro Workforce Management (the former Dimensions: time and scheduling) and UKG Ready (mid-market HCM). Each line has its own REST reference, hosts and credential model, so the destination is really the product line the tenant runs. composerID publishes the approved permanent-hire decision against the UKG Pro Recruiting Opportunity (the requisition object) and carries the Intent ID in a tenant-configured custom field on that record, holding the linkage on its own side until that field is confirmed writable and readable back.
The public API facts composerID's adapter relies on. Tenant-specific details (custom fields, picklists, approval chains) are confirmed during connection and folded into the MappingProfile.
| Authentication | UKG Pro: HTTP Basic with a web-services service account plus the US-Customer-Api-Key header (a per-customer API key issued in the tenant); Recruiting APIs are credentialed separately from the core web-services account, and the grant model is confirmed at onboarding. UKG Pro WFM: OAuth 2.0 access token from the authentication endpoint plus an appkey header issued on the developer hub. UKG Ready: a company-scoped API key exchanged through the login call for a session token. |
|---|---|
| API style | REST, JSON. Three product lines (UKG Pro, UKG Pro WFM, UKG Ready) with separate references, versioning and hosts; legacy UKG Pro SOAP web services remain for some employee writes. |
| Base URL | UKG Pro https://service{n}.ultipro.com/{service}/v1 | UKG Pro WFM https://{tenant}.{env}.mykronos.com/api/v1 | UKG Ready https://secure{n}.saashr.com/ta/rest/v2/companies/{cid} |
| Objects | UKG Pro: employee person details, employment details, jobs, org levels, employee changes, Recruiting opportunities, candidates, applications. UKG Pro WFM: persons and person assignments, schedules, timecards, hyperfind queries. UKG Ready: employees (external_id), applicant-tracking job requisitions and applicants. |
| Events / webhooks | No general outbound webhooks on UKG Pro; changes are polled through the Employee Changes API against a last-checked timestamp. UKG Pro WFM raises events into its Integration Hub rather than to arbitrary endpoints. UKG Ready offers tenant-configured webhook notifications for some record events (confirm coverage per company). Treat the suite as poll-first. |
| Rate limits | Not published as a single figure across the suite. UKG Pro WFM documents per-tenant rate limiting with HTTP 429; UKG Pro and UKG Ready thresholds are agreed per tenant. Back off exponentially on 429 everywhere. |
“Docs confidence” describes how deterministic our mapping templates can be before we connect to a tenant. Even with public docs, implementations vary, especially around custom fields, approval flows and object extensions.
Deterministic mapping
Common Workforce Model fields map to known API fields. Best for standard objects (requisitions, assignments, timesheets, POs).
Tenant discovery
composerID can scan tenant configuration (custom fields, picklists, required fields) where the platform permits it, then generate a tenant‑specific MappingProfile.
Enrichment loop
If the target platform requires a field the Intent record doesn't yet have, composerID emits an enrichment_request back to the intake layer.
An opinionated baseline. The platform adapter enforces additional requirements via preflight. “Tenant required” fields are discovered during connection and added to the MappingProfile.
| Object | Canonical fields | Platform target | Required status | Notes |
|---|---|---|---|---|
| Job requisition (Opportunity) Open the approved demand in UKG Pro Recruiting |
role_title, org_level, location, headcount, target_start_date | UKG Pro Recruiting: Opportunity (create where the tenant's Recruiting API exposes it; otherwise the decision reference attaches to a recruiter-opened Opportunity) | Required | Opportunity is Pro Recruiting's requisition object. Whether the Recruiting API accepts Opportunity create, and its writable fields and approval behaviour, is indicative until confirmed against the tenant's Recruiting API reference at onboarding. |
| Intent ID correlation Carry the Intent ID |
intent_id -> tenant-configured custom field on the Opportunity (indicative); UKG Ready tenants: job requisition custom field, or external_id on the hired employee record | Opportunity custom field / UKG Ready custom field or employee external_id | Required | Link-only until a writable field that is returned on read is confirmed for the tenant's product line; composerID holds the linkage on its side either way. Deep link {tenant_host}/recruiting/opportunities/{external_id} (illustrative). |
| Hire read-back Close the loop |
employee_id, employment_status, hire_date | UKG Pro Personnel: Employee Changes API (poll) | Read scope only | Polled against a last-checked timestamp. UKG Ready webhooks supplement where the company has them enabled. |
Idempotency & drift: publish + reconcileExpand
Publish operations are idempotent using a deterministic key {intent_id}-{intent_version}-{target_system}. Because humans can change records inside the platform, composerID supports reconciliation: it compares the platform record snapshot to the canonical intent and flags drift.
Real deployments rely on program-specific custom fields (for compliance, approvals, GL coding, rate rules or supplier constraints). composerID is designed to generate tenant‑specific mappings rather than forcing you to redesign your intake.
How scanning works
High-level flow
What gets produced
Portable artefacts
Important: where this platform is tenant-definedExpand
Establish which product line the tenant runs first: UKG Pro, UKG Pro WFM and UKG Ready have different hosts, credentials and references, and a customer may run two. UKG Pro service accounts need the web-services role and the customer API key; Recruiting access is granted separately and only the tenant can say whether its Recruiting API accepts Opportunity create at all. Confirm at onboarding whether the Opportunity exposes a client-writable custom field that is returned on read (ideally filterable); until then the Intent ID carrier is link-only. Rate limits for UKG Pro and UKG Ready are agreed per tenant.
Use this page alongside the API + Schemas docs to implement: destination connection, preflight validation, publish, webhook back-sync and reconciliation.