Connecting to UKGProWFM

Using OAuth Authentication

UKG Pro Workforce Management uses OAuth 2.0 with the Resource Owner Password Credentials grant (grant_type=password) to authorize access to the API. Unlike most OAuth-based profiles, this does not use a browser redirect/authorization-code step: the driver exchanges your UKG Pro WFM username, password, client ID, and client secret directly for an access token.

Set the following connection properties to authenticate:

AuthScheme: Set this to OAuthPassword.
Host: Set this to the hostname of your UKG Pro Workforce Management datacenter/tenant (for example, yourcompany.mykronos.com). Do not include the protocol (https://) or a trailing slash.
OAuthClientId: Set this to the client ID issued for your UKG Pro Workforce Management OAuth application.
OAuthClientSecret: Set this to the client secret issued for your UKG Pro Workforce Management OAuth application.
User: Set this to your UKG Pro Workforce Management username.
Password: Set this to your UKG Pro Workforce Management password.

Access tokens are obtained from https://{Host}/api/authentication/access_token. Refresh tokens issued by UKG Pro Workforce Management expire after 7 days; if a refresh attempt fails because the refresh token itself has expired, the driver must re-authenticate with your User/Password credentials to obtain a new access token.

Example Connection String

Profile=C:\profiles\UKGProWFM.apip;AuthScheme=OAuthPassword;ProfileSettings="Host=yourcompany.mykronos.com;User=your_username;Password=your_password;";OAuthClientId=your_client_id;OAuthClientSecret=your_client_secret;

Available Tables

The UKG Pro Workforce Management API Profile provides access to the following tables:

Employees: Core employee/person identity records - single-record lookup by PersonId, or a lighter-weight bulk lookup by PersonNumber.
PersonInformation: A person's name, contact, and account details (requires PersonNumber).
EmploymentTerms: Employment term configuration (contract rules, accrual/holiday profile, work hours) - not which term a specific employee is currently on.
LaborLevelEntries: The organization's labor category/labor level hierarchy (requires LaborCategoryEntryId for reliable results).
Timecards: Timecard detail for a single employee over a date range (requires PersonId, StartDate, EndDate).
Punches: Recent punches over a short (<=60 minute) time window (requires StartDateTime, EndDateTime).
PayCodes: Pay codes defined in Timekeeping setup.
Accruals: Accrual profile configuration (accrual codes/policies assigned to a profile) - not per-employee accrual balances.
HistoricalCorrections: Status of historical timecard correction (compute/preview) jobs.
HistoricalCorrectionSaves: Status of historical timecard correction save (apply) jobs.
Schedules: Scheduled shifts for a single employee over a date range (requires PersonId, StartDate, EndDate).
Shifts: Full shift/segment detail for a specific shift (requires ShiftId; see Schedules).
OpenShifts: Computes the cost and hours for a proposed open shift - a hypothetical calculator, not a browse of existing open shifts.
StaffingMatrix: Target staffing coverage used for schedule forecasting (requires StaffingMatrixId or LocationId).
LeaveCases: Leave-of-absence cases - single-record lookup by LeaveCaseId, or a bulk lookup by PersonId/StartDate/EndDate.
LeaveRequests: Individual leave request/edit records tied to a leave case (requires LeaveRequestId).
HyperFindQueries: Configured HyperFind queries used within the UKG Pro WFM UI for employee/location selection.
PayPeriods: Computes the pay period timespan containing a given date.
WorkRules: Pay rules/work rules defined in Timekeeping setup.
Jobs: A single job by name, effective as of a given date (requires JobName, Date).
Locations: A single location, by LocationId or by LocationPath (requires Context, Date).
LocationTypes: Hierarchy-level reference data (e.g. Company, District, Department, Site) used in the Business Structure (requires LocationTypeId or LocationTypeName, plus Date).

Notes

The profile is read-only. UKG Pro Workforce Management write operations are not surfaced through this profile.
Most tables in this profile require a filter to return results, since the underlying API has no bulk/list-all endpoint for that resource: PersonInformation requires PersonNumber, Timecards, Schedules require PersonId/StartDate/EndDate, Punches requires StartDateTime/EndDateTime, Shifts requires ShiftId, LeaveRequests requires LeaveRequestId, Jobs requires JobName and Date, Locations and LocationTypes require Date (plus Context or an id/name), and StaffingMatrix requires StaffingMatrixId or LocationId.
HyperFind query IDs configured in HyperFindQueries are not usable as an input anywhere else in this profile - every bulk-read table (Timecards, Punches, Schedules, Shifts, Accruals, LeaveCases) was confirmed to reject HyperFind-based employee selection and instead reads by an explicit PersonId.
Pagination is not automatic across this profile the way it is in some others. Most endpoints return their entire result in a single response because the underlying API does not support paging for them; Accruals is the only table with real query-string pagination, and Punches exposes its own Count/Index inputs because its pagination is driven by the POST request body rather than query parameters.
A few fields (in Punches, LeaveRequests, HistoricalCorrections/HistoricalCorrectionSaves, and LaborLevelEntries) come from the documented response schema only; no real records existed in the environment used to build this profile to confirm their exact values against live data.

Usage Examples

Retrieve a job by name, effective as of a given date:

SELECT * FROM Jobs WHERE JobName = 'Duty Mgt' AND Date = '2026-09-21'

Retrieve a single employee's identity record by person ID:

SELECT * FROM Employees WHERE PersonId = 12345

Retrieve a person's name, contact, and account details by person number:

SELECT * FROM PersonInformation WHERE PersonNumber = 'RE0001'

Retrieve an employment term's contract rules and accrual/holiday profile:

SELECT * FROM EmploymentTerms WHERE EmploymentTermId = 1

Retrieve a labor category/labor level hierarchy entry:

SELECT * FROM LaborLevelEntries WHERE LaborCategoryEntryId = 1

List the HyperFind queries configured in the UKG Pro WFM UI:

SELECT * FROM HyperFindQueries

Retrieve a single employee's timecard detail for a pay period:

SELECT * FROM Timecards WHERE PersonId = 6301 AND StartDate = '2026-01-01' AND EndDate = '2026-01-14'

Retrieve recent punches within a 60-minute window:

SELECT * FROM Punches WHERE StartDateTime = '2026-01-01T00:00:00' AND EndDateTime = '2026-01-01T00:59:59'

List the pay codes defined in Timekeeping setup:

SELECT * FROM PayCodes

Retrieve a single employee's scheduled shifts for a date range:

SELECT * FROM Schedules WHERE PersonId = 6301 AND StartDate = '2026-01-01' AND EndDate = '2026-01-14'

Retrieve full shift/segment detail for a specific shift:

SELECT * FROM Shifts WHERE ShiftId = 714390

Compute the projected cost and hours of a proposed open shift:

SELECT * FROM OpenShifts WHERE ReferenceIdInput = 1 AND PayRuleId = 8 AND WageRate = 15.50 AND ShiftId = 1 AND SegmentStartDateTime = '2026-01-01T08:00:00' AND SegmentEndDateTime = '2026-01-01T16:00:00' AND SegmentTypeId = 1 AND WorkRuleId = 7

Retrieve the target staffing coverage for a location:

SELECT * FROM StaffingMatrix WHERE StaffingMatrixId = 1

List the accrual codes/policies assigned to an accrual profile:

SELECT * FROM Accruals WHERE ProfileId = 1

List the leave-of-absence cases for an employee over a date range:

SELECT * FROM LeaveCases WHERE PersonId = 6301 AND StartDate = '2019-01-01' AND EndDate = '2026-12-31'

Retrieve a single leave request/edit record by ID:

SELECT * FROM LeaveRequests WHERE LeaveRequestId = 1

Compute the pay period timespan containing a given date:

SELECT * FROM PayPeriods WHERE Date = '2026-01-01'

List the pay rules/work rules defined in Timekeeping setup:

SELECT * FROM WorkRules

Check the status of a historical timecard correction (compute) job:

SELECT * FROM HistoricalCorrections

Check the status of a historical timecard correction save (apply) job:

SELECT * FROM HistoricalCorrectionSaves

Retrieve a single location by ID within a business structure context:

SELECT * FROM Locations WHERE LocationId = 701 AND Context = 'ORG' AND Date = '2026-09-21'

Retrieve a business structure hierarchy level by name, effective as of a given date:

SELECT * FROM LocationTypes WHERE LocationTypeName = 'Site' AND Date = '2026-09-21'

Limitations

UKG Pro Workforce Management enforces domain-specific request limits rather than a simple requests-per-second rate limit. Notable limits include:

HyperFind execute: up to 365 days, up to 10,000 employees, up to 10,000 locations, up to 50,000 combined employees in a single response.
Information Access (ad hoc/aggregated queries): up to 365 days, up to 500 employees, up to 300 locations.
Leave operations: employees × days up to 84,000; up to 1,000 leave cases; up to 1,000 leave edits.
People operations: up to 100 employees per bulk request.
Business structure: up to 5,000 jobs.
HTTP 429 is returned when request throttling limits are exceeded.

Connection Properties

The connection string properties are the various options that can be used to establish a connection. This section provides a complete list of the options you can configure in the connection string for this provider.

Property	Description
AuthScheme	The scheme used for authentication. Accepted entries are None or OAuthPassword. Allowed values are: BASIC, NONE, NTLM, OAUTH, APIKEY, OAUTH_CLIENT, OAUTH_PASSWORD
CallbackURL	Identifies the URL users return to after authenticating to API via OAuth (Custom OAuth applications only).
Host	The hostname of the UKG Pro Workforce Management datacenter or tenant assigned to your organization.
InitiateOAuth	Specifies the process for obtaining or refreshing the OAuth access token, which maintains user access while an authenticated, authorized user is working. Allowed values are: OFF, REFRESH, GETANDREFRESH
OAuthAccessToken	Specifies the OAuth access token used to authenticate requests to the data source. This token is issued by the authorization server after a successful OAuth exchange.
OAuthClientId	Specifies the client ID (also known as the consumer key) assigned to your custom OAuth application. This ID is required to identify the application to the OAuth authorization server during authentication.
OAuthClientSecret	Specifies the client secret assigned to your custom OAuth application. This confidential value is used to authenticate the application to the OAuth authorization server. (Custom OAuth applications only.).
OAuthExpiresIn	Specifies the duration in seconds, of an OAuth Access Token's lifetime. The token can be reissued to keep access alive as long as the user keeps working.
OAuthRefreshToken	Specifies the OAuth refresh token used to request a new access token after the original has expired.
OAuthSettingsLocation	Specifies the location of the settings file where OAuth values are saved.
OAuthTokenTimestamp	Displays a Unix epoch timestamp in milliseconds that shows how long ago the current access token was created.
OAuthVerifier	Specifies a verifier code returned from the OAuthAuthorizationURL . Used when authenticating to OAuth on a headless server, where a browser can't be launched. Requires both OAuthSettingsLocation and OAuthVerifier to be set.
Password	Your UKG Pro Workforce Management password.
Scope	Scope(s) to use when authenticating, that control access to specific information.
User	Your UKG Pro Workforce Management username.