UKG Pro punch and token data API

UKG, Inc. · Business

UKG Pro is the employee self-service app from UKG, Inc. (Ultimate Kronos Group), the Lowell, Massachusetts human-capital-management company formed when Ultimate Software merged with Kronos. After a worker adds their employer tenant they sign in through UKG AuthN or company SSO, then land in a native shell that hosts Pro payroll and HR screens — pay statements, pay summary, my time-off, my schedule, team timesheets, org chart, unified inbox approvals and UKG Talk — alongside Kronos Dimensions timekeeping: clock in and out, store punches offline when the device has no signal, upload them later, and plot in/out/transfer punches on a geofence map. The app is published for United States employers that run UKG Pro (the former UltiPro stack) and UKG Dimensions / Workforce Central. It serves hourly and salaried employees, supervisors and timekeepers who need pay, leave, schedule and clock data on a phone rather than a kiosk, and it sits in the same employee-facing slot as ADP Mobile Solutions, Workday and Paylocity.

Imported clock events stamp punchTime and a punchValid flag, with optional punchGeoLocation, geofenceMethod and jobName when the punch was taken inside a known place. Offline uploads first read serverTime, the worker's gmtOffset / zoneId and FACP flags such as EMPLOYEE_OFFLINE_MOBILE_PUNCH so the device can correct timestamps across DST transitions before posting.

The identity envelope on the session carries personId, personBadgeNumber and the tenant vanityUrl; AuthN returns accessToken, refreshToken and WFM/Talk scopes (access:wfm, read:talk, write:talk). Pro gateway configuration adds componentCompanyId and companyAccessCode. Talk then maps the same worker through externalUID, mobileNumber, tenantDomain and spotId. Payroll reconcilers, attendance auditors, directory joiners and IT provisioning bots consume those fields; openData Studio turns them into callable open data.

Screenshots

API surface

The endpoints and request/response examples below are reconstructed from the app's interface — illustrative, not a live capture.

Import offline timekeeping punches

POST /v1/clock/{tenantId}/punches/batch opendata

Uploads clock-in, clock-out and job-transfer punches stored on-device while offline so Workforce Central / Dimensions can post them to the employee's timecard.

Auth: Session cookies plus AuthN Bearer accessToken. Mutating calls attach the csrf from GET /v1/clock/{tenantId}/feature-flags.

personId
personNum
personBadgeNumber
punchTime
punchValid
punchXferJson
punchGeoLocation
geofenceMethod
jobName
deviceTimeAtPunchSec
serverTimeAtPunchSec

POST /v1/clock/ACME_PROD/punches/batch HTTP/1.1
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "punches": [
    {
      "personId": "10432",
      "personNum": "E-10432",
      "personBadgeNumber": "88421",
      "punchTime": 1759687200,
      "punchValid": "yes",
      "punchXferJson": "{}",
      "punchGeoLocation": {"latitude": 42.6334, "longitude": -71.3162, "geofenceMethod": "gps"},
      "jobName": "Warehouse-A",
      "deviceTimeAtPunchSec": 1759687200,
      "serverTimeAtPunchSec": 1759687201
    }
  ]
}

{
  "imported": 1,
  "failed": 0,
  "punches": [
    {
      "personId": "10432",
      "punchTime": 1759687200,
      "punchValid": "yes",
      "verified": true
    }
  ]
}

Offline punch information and FACP flags

GET /v1/clock/{tenantId}/offline-policy opendata

Fetches the tenant's server clock, the worker's timezone/currency preferences and DST transition table, plus FACP feature flags that decide whether offline mobile punch, meal-deduct cancel and location recording are allowed before an upload.

Auth: Bearer accessToken from AuthN plus tenant session cookies. Query carries tenantId and facpNames.

serverTime
userDetails
gmtOffset
zoneId
currencyPreference
userPreferences
rules
transitions
dateTimeBefore
offsetBefore
dateTimeAfter
offsetAfter
tenantId
facpNames

GET /v1/clock/ACME_PROD/offline-policy?facpNames=EMPLOYEE_OFFLINE_MOBILE_PUNCH,TS_CANCEL_MEAL_DEDUCTS,EMPLOYEE_LOCATION_RECORD_DATA HTTP/1.1
Authorization: Bearer <access_token>

{
  "serverTime": 1759687300,
  "userDetails": {
    "timeZone": {"gmtOffset": -14400, "zoneId": "America/New_York"},
    "currencyPreference": "USD",
    "userPreferences": {"locale": "en_US"}
  },
  "rules": {
    "EMPLOYEE_OFFLINE_MOBILE_PUNCH": true,
    "TS_CANCEL_MEAL_DEDUCTS": false,
    "EMPLOYEE_LOCATION_RECORD_DATA": true
  },
  "transitions": [
    {
      "dateTimeBefore": "2026-03-08T02:00:00",
      "offsetBefore": -18000,
      "dateTimeAfter": "2026-03-08T03:00:00",
      "offsetAfter": -14400
    }
  ]
}

Last punch and most-recently-used transfers

GET /v1/clock/{tenantId}/latest-and-favorites opendata

Returns the worker's most recent clock event and the most-recently-used job/labor-account transfers so the punch button can default the next in/out or transfer.

Auth: Bearer accessToken plus tenant session cookies.

lastPunch
punchTime
punchValid
jobName
geofenceMethod
punchGeoLocation
mru
punchXferJson

GET /v1/clock/ACME_PROD/latest-and-favorites HTTP/1.1
Authorization: Bearer <access_token>

{
  "lastPunch": {
    "punchTime": 1759680000,
    "punchValid": "yes",
    "jobName": "Warehouse-A",
    "geofenceMethod": "wifi",
    "punchGeoLocation": {"latitude": 42.6334, "longitude": -71.3162}
  },
  "mru": [
    {"jobName": "Warehouse-A", "punchXferJson": "{\"laborAccount\":\"LA-12\"}"},
    {"jobName": "Shipping-Dock", "punchXferJson": "{\"laborAccount\":\"LA-18\"}"}
  ]
}

Mobile capabilities and CSRF token
GET /v1/clock/{tenantId}/feature-flags opendata
Issues the CSRF token the shell attaches to punch import and other writes, and advertises which Dimensions mobile capabilities the tenant has enabled.
Auth: Tenant session cookies after SSO. Used to mint a fresh CSRF token for later mutating calls.
- csrf
- offlinePunch
- locationRecordData
- cancelMealDeducts
```
GET /v1/clock/ACME_PROD/feature-flags HTTP/1.1
Cookie: TENANT_SSO=...
```
```
{
  "csrf": "c9f1e2a0-4b7d-4c21-9e01-8f2d6a41b0c7",
  "offlinePunch": true,
  "locationRecordData": true,
  "cancelMealDeducts": false
}
```
Mobile session context
GET /v1/people/{tenantId}/me osint
Returns the signed-in worker's identity envelope — person, badge, tenant and vanity URL — that every later punch, schedule and inbox call is scoped to.
Auth: Bearer accessToken plus tenant session cookies.
- personId
- personNum
- personName
- userName
- personBadgeNumber
- tenantId
- vanityUrl
- offlineUser
```
GET /v1/people/ACME_PROD/me HTTP/1.1
Authorization: Bearer <access_token>
```
```
{
  "personId": "10432",
  "personNum": "E-10432",
  "personName": "Jane Doe",
  "userName": "jdoe",
  "personBadgeNumber": "88421",
  "tenantId": "ACME_PROD",
  "vanityUrl": "https://acme.example.invalid",
  "offlineUser": false
}
```
Mobile client startup
GET /v1/shell/{tenantId}/boot opendata
Tells the hybrid shell which parent product (Dimensions vs Pro) the tenant is on and which home module to open after login.
Auth: Bearer accessToken plus tenant session cookies.
- parentProduct
- mobileHome
- tenantId
- modules
```
GET /v1/shell/ACME_PROD/boot HTTP/1.1
Authorization: Bearer <access_token>
```
```
{
  "parentProduct": "dimensions",
  "mobileHome": "punch",
  "tenantId": "ACME_PROD",
  "modules": ["timekeeping", "scheduling", "inbox"]
}
```
Auth-done handshake
GET /v1/session/{tenantId}/ready opendata
Confirms SSO has finished for the mobile client so the shell can proceed to feature flags, identity and punch calls.
Auth: SSO session cookies established at GET /v1/session/{tenantId}/sso-start. Completes the mobile login handshake before feature-flags and identity calls.
- status
- personId
- tenantId
```
GET /v1/session/ACME_PROD/ready HTTP/1.1
Cookie: TENANT_SSO=...
```
```
{
  "status": "ok",
  "personId": "10432",
  "tenantId": "ACME_PROD"
}
```
Issue OAuth access token
GET /v1/session/{tenantId}/bearer opendata
Mints the OAuth accessToken the shell stores and attaches as Bearer on Dimensions REST calls.
Auth: SSO session after GET /v1/session/{tenantId}/sso-start. Returns OAuth token fields stored for later Bearer calls.
- accessToken
- expiresInSeconds
- refreshToken
- oidcFlag
- expirationDateInSeconds
- clientId
- appKey
```
GET /v1/session/ACME_PROD/bearer HTTP/1.1
Cookie: TENANT_SSO=...
```
```
{
  "accessToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiresInSeconds": 3600,
  "refreshToken": "rt-c91e2b77",
  "oidcFlag": true,
  "expirationDateInSeconds": 1759690900,
  "clientId": "ukgpromobileapp",
  "appKey": "ukg-oneapp-android"
}
```

AuthN connect (OIDC ping)

GET /v1/identity/oidc/handshake opendata

Pings AuthN with a deep-link OIDC token and returns the envelope (access, id and refresh tokens plus WFM/Talk scopes) used for the rest of the session.

Auth: Body/query carries oidcServerUrl and oidcToken from a deep-link OIDC handoff. No prior Bearer required.

oidcServerUrl
oidcToken
accessToken
idToken
refreshToken
scope
clientId
authNInstance

GET /v1/identity/oidc/handshake HTTP/1.1
Content-Type: application/json

{
  "oidcServerUrl": "https://acme.okta.com/oauth2/default",
  "oidcToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
}

{
  "accessToken": {
    "value": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
    "scope": "read:userinfo hrms_data access:wfm read:talk write:talk offline_access openid profile email"
  },
  "idToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "rt-c91e2b77",
  "clientId": "ukgpromobileapp",
  "authNInstance": "prod-us"
}

Mobile app configuration (Pro gateway)
GET /v1/pro/{companyId}/modules opendata
Loads the Pro mobile gateway configuration for the worker's company — module list (pay statements, time-off, schedule, org chart, inbox) and TMS tenant id.
Auth: Pro company session. Optional query componentCompanyId from the signed-in Pro profile.
- componentCompanyId
- companyAccessCode
- parentProduct
- modules
- tmsTenant
```
GET /v1/pro/C0012/modules?componentCompanyId=C0012 HTTP/1.1
Authorization: Bearer <access_token>
```
```
{
  "componentCompanyId": "C0012",
  "companyAccessCode": "ACME1",
  "parentProduct": "pro",
  "modules": ["pro.pay-statements", "pro.my-time-off", "pro.my-schedule", "pro.org-chart", "pro.inbox.todo.approve"],
  "tmsTenant": {"id": "tms-77", "instances": ["prod-atl"]}
}
```

Authentication access_token (form post)

POST /v1/identity/oauth/exchange opendata

Exchanges an authorization code for the OAuth access_token / refresh_token / id_token triple used when the tenant-host bearer path is not in play.

Auth: OAuth2 form post with grant_type and the clientId/clientSecret from the credential bean. Alternative to GET /v1/session/{tenantId}/bearer on the tenant host.

grant_type
access_token
token_type
expires_in
refresh_token
id_token
scope

POST /v1/identity/oauth/exchange HTTP/1.1
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&client_id=ukgpromobileapp&client_secret=******&code=spl-8f21

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "rt-c91e2b77",
  "id_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "scope": "read:userinfo hrms_data access:wfm offline_access openid profile email"
}

SSO portal bootstrap
GET /v1/session/{tenantId}/sso-start opendata
Opens the tenant SSO portal that starts the mobile login, issuing the cookies later calls attach.
Auth: Unauthenticated entry. Company vanity URL plus optional companyAccessCode; sets SSO cookies consumed by GET /v1/session/{tenantId}/ready and GET /v1/session/{tenantId}/bearer.
- loginUrl
- vanityUrl
- companyAccessCode
```
GET /v1/session/ACME_PROD/sso-start HTTP/1.1
```
```
{
  "loginUrl": "/v1/session/ACME_PROD/sso-start",
  "vanityUrl": "https://acme.example.invalid",
  "companyAccessCode": "ACME1"
}
```
Mobile login setup
GET /v1/session/{tenantId}/brand opendata
Returns the tenant vanity URL and branding so the pre-login screen can paint the employer's colors before SSO.
Auth: Unauthenticated. Resolves the tenant vanity URL and branding before the SSO portal.
- vanityUrl
- brandingVersion
- brandingColor
- companyAccessCode
```
GET /v1/session/ACME_PROD/brand HTTP/1.1
```
```
{
  "vanityUrl": "https://acme.example.invalid",
  "brandingVersion": "2026.4",
  "brandingColor": "#0057B8",
  "companyAccessCode": "ACME1"
}
```
OIDC session (user-management)
GET /v1/people/{tenantId}/oidc-record osint
Reads the OIDC session record for the signed-in worker so the shell can bind personId and userName to later WFM calls.
Auth: SSO cookies.
- oidcSession
- personId
- userName
- personName
- email
```
GET /v1/people/ACME_PROD/oidc-record HTTP/1.1
Cookie: TENANT_SSO=...
```
```
{
  "oidcSession": "sess-10432",
  "personId": "10432",
  "userName": "jdoe",
  "personName": "Jane Doe",
  "email": "[email protected]"
}
```
Talk custom login
POST /v1/talk/session/from-bearer opendata
Exchanges the AuthN accessToken for a Talk session so the embedded workplace-channel module can load the worker's channel.
Auth: JSON body carries the AuthN accessToken as access_token.
- access_token
- token
- tenantDomain
- parentProduct
- spotId
```
POST /v1/talk/session/from-bearer HTTP/1.1
Content-Type: application/json

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
}
```
```
{
  "token": "talk-sess-c91e",
  "tenantDomain": "acme.talk.example.invalid",
  "parentProduct": "pro",
  "spotId": "spot-acme-prod"
}
```

Talk user by token

POST /v1/talk/people/lookup osint

Resolves the Talk profile for the signed-in worker — names, email, mobileNumber and the HRIS externalUID that maps back to personId.

Auth: Talk session after custom login. Body carries token plus user_agent.

id
firstName
lastName
name
email
mobileNumber
externalUID
status
online
customFieldData

POST /v1/talk/people/lookup HTTP/1.1
Content-Type: application/json

{
  "token": "talk-sess-c91e",
  "user_agent": "UkgOneApp ukgpromobileapp Android"
}

{
  "id": "u-10432",
  "firstName": "Jane",
  "lastName": "Doe",
  "name": "Jane Doe",
  "email": "[email protected]",
  "mobileNumber": "+1-978-555-0142",
  "externalUID": "10432",
  "status": "active",
  "online": {"state": "online"},
  "customFieldData": []
}

Talk channel (spot) detail
GET /v1/talk/workplace/{spotId} opendata
Loads the worker's Talk workplace channel (spot) — tenantDomain, parentProduct and span-of-control flags that decide which groups and alerts the Talk home shows.
Auth: Talk session after people lookup.
- spotId
- name
- tenantDomain
- parentProduct
- userEmail
- userMobile
- isSpanOfControlEnabled
- unreadAlertsCount
```
GET /v1/talk/workplace/spot-acme-prod HTTP/1.1
Authorization: Bearer talk-sess-c91e
```
```
{
  "spotId": "spot-acme-prod",
  "name": "Acme Workplace",
  "tenantDomain": "acme.talk.example.invalid",
  "parentProduct": "pro",
  "userEmail": "[email protected]",
  "userMobile": "+1-978-555-0142",
  "isSpanOfControlEnabled": true,
  "unreadAlertsCount": 3
}
```

Where teams use this data

Workforce clock reconciliation
A timekeeping feed pulls imported punches by personId, punchTime and punchValid, then matches them to the last-punch snapshot so payroll can close the period without missing offline clock events.
Geofenced attendance audit
Compliance jobs read punchGeoLocation, geofenceMethod and jobName on each import, flagging punches outside the known-place radius or submitted without GPS/Wi-Fi proof.
Tenant-aware SSO provisioning
IT automation consumes componentCompanyId, companyAccessCode, vanityUrl and the AuthN accessToken/refreshToken envelope to provision a new hire's mobile tenant without a help-desk walkthrough.
Supervisor inbox routing
Once mobile-app-configuration lists pro.inbox.todo.approve and team timesheet modules, a bot can route pending approvals to the right manager using the personId from mobile context.
Talk-to-HRIS identity join
Directory jobs join Talk UserProfileModel.externalUID to Dimensions personId, then use tenantDomain and spotId to provision the same worker into the workplace channel without a second invite.

Frequently asked questions

How does UKG Pro authenticate mobile calls?

Workers enter a company vanity URL or companyAccessCode, complete SSO at the tenant portal, then the shell stores an AuthN accessToken (and refreshToken / idToken). Later timekeeping calls send that token as Bearer plus session cookies; mutating punch imports also attach the csrf value from GET /v1/clock/{tenantId}/feature-flags.

Which punch fields can a timekeeping integration read?

POST /v1/clock/{tenantId}/punches/batch accepts personId, personNum, personBadgeNumber, punchTime, punchValid, punchXferJson, punchGeoLocation and jobName. GET /v1/clock/{tenantId}/latest-and-favorites returns the latest clock event and favorite transfers; GET /v1/clock/{tenantId}/offline-policy supplies serverTime, timezone offsets and FACP flags before an offline upload.

Does the same client talk to UKG Pro payroll and Kronos Dimensions?

Yes. The native shell hosts both. Timekeeping REST lives on the tenant clock surface (/v1/clock/{tenantId}/… and punch batch). Pro payroll, time-off, schedule, org-chart and inbox modules are configured by GET /v1/pro/{companyId}/modules using componentCompanyId from the Pro profile.

Can offline punches be uploaded later?

Yes. When EMPLOYEE_OFFLINE_MOBILE_PUNCH is enabled, the app stores punches with deviceTimeAtPunchSec / serverTimeAtPunchSec and a punchValid flag, then posts them to POST /v1/clock/{tenantId}/punches/batch after AuthN succeeds.

More Business apps

Topics

UKG Pro API
UKG Pro endpoints
UKG punch import API
Kronos Dimensions last punch
UKG AuthN accessToken
UltiPro mobile gateway
employee timekeeping API
UKG Pro tenant configuration

Need this app's data API integrated?

We deliver scoped integrations for any named app — from USD 500 with source-code handoff, or hosted access billed per call. Tell us the data you need.

NDA + SOW on every engagement
Delivery in 3–7 days
Payment only after acceptance
Work scoped to authorized use

Get a quote

UKG Pro punch and token data API

Screenshots

API surface

Import offline timekeeping punches

Offline punch information and FACP flags

Last punch and most-recently-used transfers

Mobile capabilities and CSRF token

Mobile session context

Mobile client startup

Auth-done handshake

Issue OAuth access token

AuthN connect (OIDC ping)

Mobile app configuration (Pro gateway)

Authentication access_token (form post)

SSO portal bootstrap

Mobile login setup

OIDC session (user-management)

Talk custom login

Talk user by token

Talk channel (spot) detail

Data categories

Where teams use this data

Workforce clock reconciliation

Geofenced attendance audit

Tenant-aware SSO provisioning

Supervisor inbox routing

Talk-to-HRIS identity join

Frequently asked questions

More Business apps

ADP Mobile Solutions

Box

CryptoRush: Crypto Simulator

Darwinbox

Topics

Need this app's data API integrated?