Ellipse Gradient for Header

UKG Integration Guide

Integrate UKG Pro, UKG Pro Workforce Management, and UKG Ready with enterprise systems through REST APIs, selected web services, events, and file-based workflows.

UKG integration options at a glance

UKG integrations vary by product, tenant, region, licensed module, and API program. REST APIs are the preferred starting point for current integrations, while selected UKG products and legacy capabilities may expose SOAP or other web services. Event or callback mechanisms may be available for selected events, but coverage is not universal. Batch, scheduled, and file-based exchanges are also used for employee, payroll, time, and organizational data. OAuth 2.0 is the primary authentication pattern for current developer APIs, with other credentials possible for legacy services. Martini can authenticate securely, orchestrate workflows, transform JSON, XML, and files, and expose normalized APIs to downstream systems.

Integration pointSupported by UKG?Common use casesHow Martini supports it
REST APIsYesRead and update Employees, Persons, Jobs, Organizations, Locations, time data, and other product-specific resources where enabled.Martini can consume UKG REST APIs, manage authentication, paginate responses, map JSON, apply rules, and expose normalized APIs.
SOAP APIsLimitedSupport selected legacy or product-specific UKG functions when an equivalent current REST resource is unavailable or not enabled.Martini can consume SOAP services, transform XML payloads, and route service faults through workflow error handling.
Webhooks / outbound callbacksLimitedReceive notifications for selected UKG products or events where the tenant provides a documented callback mechanism.Martini can expose an authenticated API endpoint, receive the notification, retrieve current UKG data, and start a workflow.
Bulk / async / batch APIsLimitedProcess product-specific bulk extracts, asynchronous jobs, batch payroll or time transactions, and scheduled workforce data exchanges.Martini can orchestrate job submission and retrieval where available, process batches, and maintain checkpoints and reconciliation results.
File imports and exportsLimitedExchange employee master data, payroll or benefits files, time exports, general-ledger files, and scheduled reports where configured.Martini can receive or retrieve files, validate structure and control totals, transform content, and deliver results to target systems.
AuthenticationYesUse OAuth 2.0, commonly with client credentials and bearer tokens, subject to UKG product, tenant, scopes, and roles.Martini can store client secrets, tokens, API keys, and tenant endpoints as environment-specific secrets and configuration.
Database accessNot confirmedDirect access to UKG SaaS application databases is not a standard supported integration approach.Martini should use UKG APIs, reports, exports, or vendor-provided data delivery rather than direct database connectivity.

How UKG exposes data and business events

UKG REST APIs

UKG provides current REST API programs for products including UKG Pro and workforce-management services. Available resources, operations, scopes, and base URLs depend on the product and tenant.

Martini implementation pattern

Martini implementation pattern: configure the tenant endpoint and OAuth settings, call UKG REST resources from a workflow, handle pagination and incremental criteria, transform JSON, and write results to the target system or expose a normalized Martini API.

Implementation sequence

Authenticate with the applicable UKG OAuth configuration
Request the relevant UKG resource or changed-data window
Process every paginated response
Validate and map the UKG JSON payload
Apply business rules and write the target result
Store checkpoints and processing outcomes

UKG SOAP and web services

Selected UKG products and legacy capabilities may expose SOAP or web-service interfaces. Availability and recommended usage vary by product, tenant, and function.

Martini implementation pattern

Martini implementation pattern: consume the documented SOAP service, configure the required credentials, transform XML into a canonical model, handle service faults, and route the result through the same downstream workflow used by REST integrations where appropriate.

Implementation sequence

Configure the UKG SOAP endpoint and credentials
Build the request from validated workflow data
Send the XML request to the applicable service
Parse the SOAP response or fault
Map the response into the canonical model
Retry transient failures and record permanent errors

UKG event notifications

UKG event or notification mechanisms may be available for selected products and events, but coverage should not be assumed for every Employee, Timecard, Payroll, or Organization change.

Martini implementation pattern

Martini implementation pattern: expose an appropriately secured API endpoint, accept the UKG notification, verify the event context, retrieve current UKG data when needed, and combine event processing with scheduled reconciliation for completeness.

Implementation sequence

Receive the documented UKG notification
Authenticate and validate the request
Identify the affected UKG object and tenant
Retrieve the current resource when the event is partial
Map and route the change to downstream systems
Acknowledge safely and record the event outcome

UKG files and batch exchanges

File-based and batch-oriented integrations are used in some UKG workforce, payroll, time, benefits, and general-ledger scenarios. Formats, transport, schedules, and control requirements are tenant-specific.

Martini implementation pattern

Martini implementation pattern: receive or retrieve the configured file, validate filename and control totals, parse the supported format, transform records, deliver the target output, and retain reconciliation information for replay or audit.

Implementation sequence

Receive or retrieve the configured UKG file
Validate the file identity, format, and control totals
Parse and validate each data row
Transform records for the target system
Deliver the output or submit the batch
Archive processing status and rejected records

Common UKG integration patterns

Pattern 1: Synchronize UKG employees to identity and service systems

When to use this pattern

Use this pattern when UKG is the source for worker lifecycle data and downstream identity or service platforms must reflect hires, changes, and terminations. A scheduled workflow is appropriate when event coverage is unavailable or incomplete.

Integration direction
UKG
Martini
Microsoft Entra ID and ServiceNow
Example Mapping
UKG FieldCanonical FieldTarget Field
employeeIdworker.sourceIdemployeeId or externalId
employmentStatusworker.lifecycleStatusaccountEnabled or requestStatus
jobCodeworker.jobCodejobCode
organizationworker.organizationIddepartment
Martini implementation pattern

A scheduler retrieves changed Employees, Persons, Jobs, Organizations, and Locations using a supported change indicator or reconciliation window. Martini validates required identifiers, applies hire and termination rules, maps the canonical worker model, writes idempotent updates, and sends failures to controlled retry or reconciliation handling.

Martini capabilities used
  • workflows
  • API consumption
  • scheduling
  • data mapping
  • business rules
  • error handling

Pattern 2: Send approved UKG timecards to finance

When to use this pattern

Use this pattern to transfer approved Timecards from UKG Pro Workforce Management to payroll, project accounting, finance, or an ERP system while preventing duplicate submissions and handling corrections.

Integration direction
UKG Pro Workforce Management
Martini
NetSuite
Example Mapping
UKG FieldCanonical FieldTarget Field
timecardIdtime.sourceIdexternalTimeId
employeeIdtime.workerIdemployee
laborCategorytime.costCategoryitem or costCenter
approvedHourstime.quantityhours
Martini implementation pattern

Martini retrieves approved timecard pages or supported exports, filters by payroll period and approval state, converts labor categories and time zones, checks the source-to-target transaction map, and submits idempotent finance updates. Reopened periods and rejected records are routed for reconciliation rather than blindly retried.

Martini capabilities used
  • workflows
  • API consumption
  • file processing
  • data mapping
  • business rules
  • error handling

Pattern 3: Orchestrate UKG payroll and general-ledger files

When to use this pattern

Use this pattern when payroll or costing data is delivered through a UKG-supported file process rather than a directly available REST resource. It provides validation and controlled delivery to a finance platform.

Integration direction
UKG
Martini
NetSuite
Example Mapping
UKG FieldCanonical FieldTarget Field
employeeIdpayroll.workerIdemployee
earningCodepayroll.earningTypeaccount
grossPaypayroll.grossAmountamount
costCenterpayroll.costCenterdepartment
Martini implementation pattern

Martini receives the configured UKG file, validates its format, record count, control totals, and generation timestamp, then transforms payroll or costing rows into the target schema. The workflow archives the input, records rejected rows, and prevents duplicate posting using a file identifier and source transaction keys.

Martini capabilities used
  • workflows
  • file processing
  • data mapping
  • validation
  • business rules
  • error handling

Pattern 4: Combine UKG events with scheduled reconciliation

When to use this pattern

Use this pattern where the UKG tenant provides documented notifications for selected worker events but event coverage or delivery completeness requires a periodic comparison with UKG data.

Integration direction
UKG
Martini
ServiceNow
Example Mapping
UKG FieldCanonical FieldTarget Field
eventTypeworker.changeTyperequestType
employeeIdworker.sourceIdrequestedFor
effectiveDateworker.effectiveAtdueDate
employmentStatusworker.lifecycleStatusstate
Martini implementation pattern

A Martini API receives selected UKG notifications and starts a focused workflow that retrieves the current object before applying changes. A separate scheduler performs periodic reconciliation using supported incremental criteria, compares checkpoints, and repairs missed events without duplicating ServiceNow requests.

Martini capabilities used
  • APIs
  • webhooks
  • workflows
  • scheduling
  • data mapping
  • idempotency
  • error handling

Applications commonly integrated with UKG

UKG commonly participates in workforce, identity, finance, service-management, and HR application landscapes. The exact direction and interface depend on the UKG product, tenant configuration, licensed capabilities, and the adjacent application’s APIs.

Application Scenario Direction Martini Pattern
Workday Coordinate employee, organization, job, and payroll-related data during HR-system coexistence, migration, or multi-system operation. UKG → Martini → Workday Use scheduled REST retrievals or supported UKG exports, normalize Employees, Jobs, Organizations, and Locations, apply source-of-truth rules, and write idempotent updates to Workday through its supported interface.
Salesforce Make workforce, service-agent, or organizational information available for internal service operations and workforce-related business processes. UKG → Martini → Salesforce Retrieve changed UKG data, validate employment status and identifiers, map the result to Salesforce objects, and route rejected or duplicate updates for reconciliation.
ServiceNow Automate onboarding, offboarding, access requests, and HR service workflows from UKG employee lifecycle information. UKG → Martini → ServiceNow Trigger from a documented UKG callback where available or from a scheduled reconciliation, transform worker changes into ServiceNow requests or records, and retain source identifiers for idempotency.
Microsoft Entra ID Provision, update, or deactivate workforce identities according to UKG employment status and worker attributes. UKG → Martini → Microsoft Entra ID Retrieve Employees and Persons, apply lifecycle and attribute rules, then call the Entra ID API with controlled retries and safeguards around deactivation operations.
NetSuite Exchange employee, department, location, payroll, or labor-cost information with an ERP and financial system. UKG → Martini → NetSuite Combine UKG API responses or payroll files, map Organizations, Locations, Jobs, and approved time or payroll data to NetSuite structures, and reconcile control totals and failed writes.
SAP SuccessFactors Coordinate worker and organizational data where UKG and SAP HR platforms coexist or serve different business units. UKG → Martini → SAP SuccessFactors Use product-specific UKG retrievals, canonical worker mappings, effective-date rules, and bidirectional workflow boundaries to prevent conflicting updates.
Jira Create or update operational work items for onboarding, HR technology changes, and workforce-related support processes. UKG → Martini → Jira Detect qualifying UKG lifecycle changes, apply routing and prioritization rules, create or update Jira issues, and store UKG-to-Jira identifiers for duplicate prevention.
ADP Workforce Now Exchange payroll, worker, or employment data where UKG and ADP products serve different payroll or HR functions. UKG → Martini → ADP Workforce Now Orchestrate the applicable UKG API or file interface with the ADP interface, validate records and control totals, and isolate product- or region-specific transformations.

How to build a UKG integration in Martini

Objective

Identify the UKG product, tenant, API family, scopes, roles, and endpoint before creating the integration boundary.

Instructions in Martini

  • Confirm UKG Pro, UKG Pro Workforce Management, or UKG Ready
  • Configure tenant-specific URLs and OAuth 2.0 or approved legacy credentials
  • Store client secrets, tokens, keys, and endpoints in Martini environment configuration
  • Limit access to required UKG resources and target operations

Objective

Select an event, scheduled workflow, API request, or file arrival pattern based on the UKG capability available for the required resource.

Instructions in Martini

  • Use a documented UKG callback only for supported events
  • Use a scheduler for incremental retrieval or reconciliation
  • Use a controlled file workflow for configured batch exchanges
  • Define the checkpoint, effective-date window, or file identity

Objective

Collect complete UKG data while accounting for pagination, product-specific representations, and incremental criteria.

Instructions in Martini

  • Call the appropriate REST or SOAP resource
  • Process all response pages or batch results
  • Retrieve current resources after partial event notifications
  • Capture correlation identifiers and source checkpoints

Objective

Use Martini workflows to coordinate retrieval, validation, transformation, target writes, and recovery paths.

Instructions in Martini

  • Separate acquisition, transformation, delivery, and reconciliation stages
  • Apply controlled concurrency and vendor-aware throttling
  • Branch for rejected, incomplete, or future-dated data
  • Keep reusable logic in maintainable integration assets

Objective

Convert UKG Employees, Persons, Jobs, Organizations, Locations, Timecards, or payroll data into the target model.

Instructions in Martini

  • Map stable UKG identifiers to canonical fields
  • Validate required values and permitted status transitions
  • Normalize dates, time zones, codes, and effective dates
  • Transform JSON, XML, or structured files as required

Objective

Enforce lifecycle, approval, duplicate, and source-of-truth rules before writing downstream data.

Instructions in Martini

  • Process only approved timecards where required
  • Distinguish current, future-dated, terminated, and corrected data
  • Use source-to-target ID maps for idempotency
  • Block unsafe retries of non-idempotent operations

Common UKG data objects used in integrations

ObjectTypical UseCommon target systemsMartini handling
EmployeesSynchronize worker identity, employment status, contact information, organizational assignment, and employment dates.Microsoft Entra ID, ServiceNow, Workday, Salesforce, NetSuiteMartini retrieves full or incremental data where supported, validates identifiers and status, applies effective-date rules, and performs idempotent target writes.
PersonsRepresent individual or worker-level identity information in product-specific UKG APIs.Microsoft Entra ID, Workday, Salesforce, ServiceNowMartini confirms the product-specific representation, maps person identifiers to a canonical worker model, and preserves source-to-target ID mappings.
JobsSynchronize job assignments, job codes, positions, and employment classifications.Workday, SAP SuccessFactors, NetSuite, ServiceNowMartini maps job codes and classifications, applies organizational business rules, and handles future-dated or changed assignments.
OrganizationsExchange departments, companies, business units, and cost-center structures.NetSuite, Workday, SAP SuccessFactors, SalesforceMartini transforms organizational hierarchies, validates parent relationships, and processes changes with reconciliation checkpoints.
LocationsSynchronize work locations, facilities, sites, and geographic assignments.NetSuite, Workday, Microsoft Entra ID, ServiceNowMartini normalizes location identifiers, addresses, and time zones before writing to target systems.
TimecardsTransfer worked time, attendance, punches, schedules, approvals, and corrections from UKG Pro Workforce Management.NetSuite, payroll platforms, project accounting systems, finance applicationsMartini filters approved periods, maps labor categories and cost centers, prevents duplicate submissions, and reconciles rejected or reopened timecards.

Authentication and security considerations

Product-specific authentication

UKG authentication depends on the product, tenant, API family, region, and enabled modules. OAuth 2.0 with client credentials and bearer access tokens is the primary current pattern for supported developer APIs. Selected legacy or product-specific services may require other credentials.

Secrets and access control

  • Store UKG client secrets, tokens, API keys, and tenant endpoints in Martini secrets and environment-specific configuration.
  • Use only the scopes, roles, and UKG permissions required for the integration.
  • Secure Martini endpoints that receive UKG callbacks using the documented authentication and authorization method.
  • Do not place access tokens, payroll details, tax data, or unnecessary employee information in logs.

Sensitive workforce data

Employee, compensation, benefits, tax, and time data can contain personally identifiable or regulated information. Use encrypted transport, least-privilege access, limited retention, and masked operational logging.

Operational considerations for UKG integrations

Rate limits and pagination

Respect UKG-specific quotas and throttling behavior. Process collection responses page by page, control concurrency, and retry transient failures such as HTTP 429 responses with backoff.

Incremental synchronization

Prefer supported modified timestamps, effective dates, incremental extracts, or event notifications. Maintain a Martini checkpoint and use scheduled reconciliation when events are partial or unavailable.

Idempotency and effective dates

Use stable UKG identifiers and source-to-target mappings to prevent duplicate Employees, Jobs, Organizations, and Timecards. Treat future-dated changes, terminations, payroll periods, reopened time, and retroactive corrections explicitly.

Files and schema changes

For file exchanges, track file identity, generation time, record counts, control totals, rejected rows, and processing status. Validate explicit mappings because UKG resource names and schemas vary across products and API versions.

Testing and monitoring

Test in the appropriate UKG environment with representative employee, time, and payroll scenarios. Monitor correlation IDs, workflow outcomes, retries, rejected records, and changes to enumerations or response structures.

Why use Martini instead of scripts or point-to-point integrations?

Orchestration beyond point-to-point calls

UKG integrations often combine tenant-specific APIs, callbacks, scheduled reconciliation, and files. Martini provides a maintainable workflow layer that coordinates these mechanisms and separates acquisition, transformation, business rules, and delivery.

Reusable transformation and API assets

Martini can map UKG JSON, XML, and structured files into canonical models, expose controlled APIs for downstream consumers, and reuse authentication, validation, and error-handling logic across UKG products and target systems.

Operational control

  • Handle pagination, checkpoints, throttling, retries, and duplicate prevention consistently.
  • Route rejected records and partial failures for reconciliation instead of losing them in scripts.
  • Keep secrets and tenant-specific configuration separate from workflow logic.
  • Support REST, selected SOAP services, webhooks, scheduled workflows, and file-based processing in one integration design.

Frequently asked questions

How can UKG be integrated with enterprise systems?

UKG can be integrated through product-specific REST APIs, selected SOAP or web services, documented event or callback mechanisms, and supported file or batch exchanges. OAuth 2.0 is the primary current authentication pattern for developer APIs, while legacy services may use other credentials.

Can Martini integrate with UKG?

Yes. Martini can consume UKG REST APIs, selected SOAP services, and supported files; receive documented UKG notifications through an API; schedule synchronization workflows; transform UKG data; and expose normalized APIs for downstream applications.

Do I need a connector to integrate UKG with Martini?

No. A dedicated UKG connector is not required. Martini can use UKG's confirmed native integration mechanisms, including REST APIs, selected SOAP or web services, event callbacks where available, files, and supported authentication methods.

Is there any extra Lonti cost to integrate UKG with Martini?

Lonti does not charge an additional per-connector or per-vendor fee to integrate UKG. The integration is subject to the provisioned capacity of the Martini environment. Separate costs may apply from UKG, cloud infrastructure, or other third-party systems based on subscriptions, usage, and deployment model.

Which UKG integration methods should an architect use?

REST APIs are the preferred starting point when the required resource is available. Selected SOAP or web services may be needed for legacy or product-specific capabilities, while files and batch processes can suit payroll, time, and scheduled extracts. The choice depends on the UKG product, tenant, licensed modules, and resource coverage.

Does UKG support events or webhooks?

Event or notification mechanisms may be available for selected UKG products and events, but coverage should not be assumed for every object. Martini can receive documented HTTP callbacks and start workflows; scheduled reconciliation is recommended where event coverage or delivery completeness is limited.

How should UKG data synchronization handle duplicates and changes?

Use stable UKG Employee or Person identifiers, supported modified timestamps or incremental mechanisms, and a Martini-side checkpoint or mapping table. Apply effective-date and approval rules, make target writes idempotent, and reconcile partial failures, reopened periods, and missed events.

Can Martini expose an API façade for UKG data?

Yes. Martini can expose a controlled REST API that normalizes selected UKG resources for downstream consumers. The façade can centralize authentication, field mapping, business rules, pagination behavior, and error handling without exposing UKG tenant-specific details directly.

Related Martini documentation

API integration

Workflows

Data processing

Security

Operations

Plan your UKG integration with Martini

Connect UKG APIs, events, web services, and files to enterprise workflows with secure authentication, reusable mappings, and operational controls.

EXPLORE MARTINI
BOOK A DEMO