.png)
UKG Pro Integration Guide
Integrate UKG Pro with enterprise applications through REST APIs, legacy SOAP web services, tenant-specific callbacks, scheduled workflows, and supported file-based exchanges.
UKG Pro integration options at a glance
UKG Pro integrations typically use REST APIs for supported HCM capabilities, with SOAP web services retained for selected or legacy scenarios. Depending on the product, tenant, and module, organizations may also use event or callback notifications, batch or asynchronous processing, scheduled exports, and file-based imports or exports. OAuth 2.0, bearer tokens, tenant-issued API credentials, and legacy service-account authentication may apply. Martini can consume UKG Pro REST and SOAP interfaces, receive supported callbacks, schedule incremental synchronization, transform employee and organizational data, and route results to applications, databases, files, queues, or normalized APIs.
| Integration point | Supported by UKG Pro? | Common use cases | How Martini supports it |
|---|---|---|---|
| REST APIs | Yes | Read Employees, Persons, Jobs, Positions, Organizational Units, Payroll, and other supported UKG Pro HCM data; selected APIs may support create or update operations and incremental filters. | Martini can consume UKG Pro REST APIs in workflows, map responses, apply validation and business rules, and expose normalized APIs or write to downstream systems. |
| SOAP APIs | Limited | Selected or legacy UKG Pro web-service integrations may use SOAP, particularly where an organization already has a provisioned WSDL and service-account model. | Martini can consume SOAP services after the tenant WSDL, operations, credentials, and supported objects are confirmed. |
| Webhooks / outbound callbacks | Limited | UKG products and tenants may expose event, notification, or HTTPS callback mechanisms for selected objects and events; universal webhook coverage should not be assumed. | Martini can expose an API endpoint or receive webhook-style notifications through a workflow, then retrieve the current UKG Pro resource and process it idempotently. |
| Bulk, async, or batch processing | Limited | Selected product families may provide batch requests, asynchronous jobs, scheduled exports, or integration feeds for enterprise-scale exchange. | Martini can orchestrate batch submissions, poll job status where available, process pages or files, and record checkpoints and reconciliation outcomes. |
| File-based imports and exports | Limited | Scheduled files may be used for payroll, benefits, workforce, or downstream HR processes, with formats and transfer protocols depending on the product and contract. | Martini can schedule file workflows, parse and transform supported formats, validate content, and deliver or consume files through configured enterprise endpoints. |
| Authentication | Yes | Supported patterns include OAuth 2.0 bearer tokens, tenant-issued API credentials or keys, scopes, service accounts, and legacy web-service authentication. | Martini can manage endpoint configuration and secrets, send bearer tokens or configured credentials, and apply least-privilege environment-specific settings. |
| Database access | Not confirmed | Direct SQL access to UKG Pro SaaS application data is not established as a supported integration mechanism; APIs, reports, exports, or feeds should be used instead. | Martini can connect to customer-managed databases for downstream storage, but should not assume direct UKG Pro database access. |
How UKG Pro exposes data and business events
UKG Pro REST APIs
UKG provides REST APIs for supported UKG Pro products and functional areas. Availability, objects, write operations, filters, scopes, and pagination vary by product, tenant, and licensed module.
Martini implementation pattern
Martini implementation pattern: a workflow authenticates to the applicable UKG Pro API, retrieves pages or filtered changes, normalizes the response, applies business rules, and writes to downstream applications or exposes a controlled normalized API.
Implementation sequence
UKG Pro SOAP web services
Selected or legacy UKG Pro integrations use SOAP web services. The WSDL, available operations, authentication model, and supported objects must be confirmed for the customer tenant.
Martini implementation pattern
Martini implementation pattern: configure the confirmed WSDL and credentials, invoke the required SOAP operation, transform XML responses or requests, and route business or transport faults through controlled error handling.
Implementation sequence
UKG Pro callbacks and event notifications
UKG products may expose event, notification, or HTTPS callback mechanisms for selected events. Coverage is product- and event-specific rather than universal across UKG Pro objects.
Martini implementation pattern
Martini implementation pattern: expose a controlled receiving API or webhook-oriented workflow, validate the notification, retrieve the authoritative UKG Pro resource when needed, and deduplicate repeated deliveries.
Implementation sequence
UKG Pro scheduled and file exchange
Scheduled synchronization, exports, integration feeds, and file exchange may support payroll, benefits, workforce, or downstream HR processes where real-time event delivery is unavailable.
Martini implementation pattern
Martini implementation pattern: schedule a workflow, retrieve a bounded API window or configured file, parse and validate the contents, transform records, deliver them to the target, and create reconciliation results.
Implementation sequence
Common UKG Pro integration patterns
Pattern 1: Synchronize employees to Salesforce
When to use this pattern
Use this pattern when Salesforce needs current employee, manager, department, location, or employment-status information for ownership, provisioning, or service processes.
Integration direction
Example Mapping
| UKG Pro Field | Canonical Field | Target Field |
|---|---|---|
| employeeId | worker.sourceId | Salesforce Employee ID |
| employmentStatus | worker.lifecycleStatus | User Status |
| managerId | worker.managerSourceId | Manager |
| organizationalUnit | worker.department | Department |
Martini implementation pattern
A scheduled Martini workflow uses a UKG-supported modification filter or watermark, traverses paginated Employees and Organizational Units, resolves managers, validates required Salesforce fields, and performs idempotent upserts. Transient failures are retried with bounded backoff and rejected records are included in reconciliation output.
Martini capabilities used
- workflows
- API consumption
- scheduling
- data mapping
- business rules
- error handling
Pattern 2: Align workers with ServiceNow
When to use this pattern
Use this pattern when ServiceNow users, departments, locations, and manager relationships must follow UKG Pro as the HR system of record.
Integration direction
Example Mapping
| UKG Pro Field | Canonical Field | Target Field |
|---|---|---|
| personId | person.sourceId | ServiceNow User ID |
| organizationalUnit | organization.department | Department |
| location | organization.location | Location |
| employmentStatus | worker.lifecycleStatus | Active |
Martini implementation pattern
Martini retrieves relevant UKG Pro resources, resolves organizational relationships, and applies explicit rules for hires, transfers, terminations, and rehires before calling ServiceNow. Stable source identifiers and upsert semantics prevent duplicate users, while failures are isolated for replay.
Martini capabilities used
- API consumption
- workflow orchestration
- data mapping
- validation
- business rules
- retry handling
Pattern 3: Exchange payroll data with NetSuite
When to use this pattern
Use this pattern when supported UKG Pro payroll or workforce data must be transferred into NetSuite for labor-cost processing, financial reconciliation, or reporting.
Integration direction
Example Mapping
| UKG Pro Field | Canonical Field | Target Field |
|---|---|---|
| employeeId | worker.sourceId | Employee ID |
| payPeriod | payroll.period | Accounting Period |
| laborCost | payroll.cost | Labor Cost |
| organizationalUnit | payroll.costCenter | Department or Class |
Martini implementation pattern
A Martini workflow retrieves the tenant-supported payroll or workforce extract, converts it to the NetSuite API or import model, validates periods and cost centers, and records correlation IDs and processing status. Batch results are reconciled and sensitive payroll fields are excluded from routine logs.
Martini capabilities used
- scheduled workflows
- file or API processing
- data transformation
- validation
- reconciliation
- secure configuration
Pattern 4: Provision identities from employee lifecycle changes
When to use this pattern
Use this pattern when hires, transfers, leave, and terminations in UKG Pro should drive controlled identity changes in Microsoft Entra ID or Okta.
Integration direction
Example Mapping
| UKG Pro Field | Canonical Field | Target Field |
|---|---|---|
| employeeId | identity.sourceWorkerId | Employee ID |
| workEmail | identity.email | User Principal Name or Login |
| employmentStatus | identity.lifecycleStatus | Account Status |
| effectiveDate | identity.changeEffectiveAt | Activation or Deactivation Date |
Martini implementation pattern
Martini polls UKG Pro or consumes a supported callback, validates effective dates and lifecycle state, and applies approval and duplicate-prevention rules before invoking the identity API. Future-dated changes can be staged rather than applied immediately, and termination failures are routed for controlled review.
Martini capabilities used
- workflows
- API consumption
- webhook handling
- date transformation
- business rules
- error handling
Applications commonly integrated with UKG Pro
UKG Pro is commonly used as an HR and workforce system of record in broader enterprise architectures. The following applications represent practical integration targets; exact objects, direction, and write capabilities depend on the UKG Pro product, tenant, and licensed modules.
| Application | Scenario | Direction | Martini Pattern |
|---|---|---|---|
| Salesforce | Synchronize employee, manager, department, location, and employment-status information for ownership, provisioning, and service processes. | UKG Pro → Martini → Salesforce | A scheduled Martini workflow retrieves changed Employees and Organizational Units, validates required values, maps them to Salesforce objects, and performs idempotent upserts with retry and reconciliation handling. |
| ServiceNow | Keep users, departments, locations, and manager relationships aligned with the HR system of record for service and access processes. | UKG Pro → Martini → ServiceNow | Martini consumes UKG Pro REST resources, resolves manager and organizational relationships, applies deactivation and rehire rules, and calls ServiceNow APIs with correlation and error tracking. |
| NetSuite | Transfer payroll, labor-cost, employee, or organizational data into financial reconciliation and reporting processes. | UKG Pro → Martini → NetSuite | Martini retrieves supported payroll or workforce data, converts it to the NetSuite API or import model, records correlation IDs, and produces processing and reconciliation status. |
| Microsoft Entra ID | Drive identity lifecycle changes from employee status, effective dates, hires, transfers, leaves, and terminations. | UKG Pro → Martini → Microsoft Entra ID | Martini polls UKG Pro or receives a supported notification, validates status and effective dates, applies approval and duplicate-prevention rules, and invokes the identity platform API. |
| Okta | Provision, update, or deactivate workforce identities using employee lifecycle information. | UKG Pro → Martini → Okta | A Martini workflow retrieves incremental employee changes, maps stable UKG identifiers and lifecycle states to Okta attributes, and performs controlled writes with retry and replay safeguards. |
| Jira | Associate employees, organizational ownership, and onboarding work with HR lifecycle processes. | UKG Pro → Martini → Jira | Martini transforms selected employee or organizational changes into Jira user, project, or onboarding-workflow requests, applying business rules before writing and recording rejected items. |
| ADP | Exchange employee, payroll, or workforce information where both platforms participate in a broader HR and payroll landscape. | UKG Pro → Martini → ADP | Martini coordinates API or file-mediated exchange, normalizes employee and payroll identifiers, validates effective dates, and produces reconciliation results for both systems. |
| Microsoft Power BI | Load employee, organizational, workforce, or payroll extracts into reporting and analytics processes. | UKG Pro → Martini → Microsoft Power BI | Martini retrieves supported API data or exports, transforms it into an analytics-ready model, and delivers it to the configured reporting or data platform while protecting sensitive fields. |
How to build a UKG Pro integration in Martini
Objective
Establish the tenant-specific UKG Pro API, SOAP, callback, or file configuration and keep credentials isolated by environment.
Instructions in Martini
- Confirm the UKG Pro product, module, API family, and tenant permissions
- Configure OAuth 2.0, API credentials, service-account, or legacy authentication as applicable
- Store client secrets, API keys, and credentials in Martini secrets management
- Confirm HTTPS endpoints, scopes, and least-privilege access
Objective
Select event delivery, scheduled polling, batch processing, or file exchange according to the supported UKG Pro capability.
Instructions in Martini
- Use a supported callback only for explicitly available events
- Use a scheduler for employee, organizational, payroll, or workforce synchronization where callbacks are unavailable
- Define the polling window, watermark, effective-date policy, or file schedule
- Set a bounded concurrency and checkpoint strategy
Objective
Obtain complete and authoritative UKG Pro data while handling pagination, filters, batch status, and partial failures.
Instructions in Martini
- Retrieve the selected Employees, Persons, Jobs, Positions, Organizational Units, or Payroll objects
- Traverse page or cursor results according to the endpoint contract
- Use modification timestamps, effective dates, or supported change filters when available
- Record source IDs, request identifiers, checkpoints, and processing status
Objective
Convert UKG Pro-specific structures into a canonical model and then into the target application format.
Instructions in Martini
- Separate UKG-specific mappings from downstream mappings
- Normalize identifiers, dates, time zones, enumerations, and nested relationships
- Apply privacy-aware field selection for employee and payroll information
- Validate required fields and route invalid records without stopping the full batch unnecessarily
Objective
Make lifecycle, effective-date, reconciliation, and duplicate decisions explicit before writing downstream.
Instructions in Martini
- Distinguish current, future-dated, historical, terminated, and rehired workers
- Use stable UKG identifiers and correlation IDs for idempotency
- Resolve manager, position, job, and organizational-unit dependencies
- Apply approval or controlled-review rules before identity deactivation or sensitive updates
Objective
Deliver transformed data to enterprise applications, databases, files, queues, or a normalized Martini API.
Instructions in Martini
- Use target upsert or equivalent idempotent operations where available
- Handle downstream validation responses separately from transient transport failures
- Record source-to-target correlation and per-object outcomes
- Use normalized Martini APIs when multiple consumers need a consistent UKG Pro model
Common UKG Pro data objects used in integrations
| Object | Typical Use | Common target systems | Martini handling |
|---|---|---|---|
| Employees | Synchronize worker profiles, employment status, manager relationships, identifiers, and lifecycle changes. | Salesforce, ServiceNow, Microsoft Entra ID, Okta, data warehouses | Martini retrieves full or incremental results, handles pagination and effective dates, maps stable identifiers, validates required fields, and performs idempotent downstream writes. |
| Persons | Represent person-level identity and demographic information used across HR processes. | Identity platforms, reporting systems, HR applications | Martini separates person identity from employment state, applies privacy-aware mappings, and preserves source IDs and correlation values. |
| Jobs | Synchronize job definitions, codes, titles, and related workforce reference data. | ServiceNow, Salesforce, reporting platforms, workforce applications | Martini can cache relatively static reference data, normalize codes, and use it to enrich employee or position flows. |
| Positions | Represent assigned or available organizational positions and their relationships to jobs and units. | ServiceNow, Salesforce, identity workflows, analytics platforms | Martini resolves relationships, applies effective-date rules, and prevents duplicate downstream position or ownership updates. |
| Organizational Units | Synchronize departments, business structures, cost centers, and organizational relationships. | ServiceNow, Salesforce, NetSuite, Power BI | Martini retrieves hierarchical data, maps parent-child relationships, caches reference values, and flags unresolved references for reconciliation. |
| Payroll | Exchange supported payroll, labor-cost, or payroll-related information for financial and workforce processes. | NetSuite, reporting platforms, data warehouses, payroll-adjacent systems | Martini applies restricted-field mappings, validates period and effective-date information, protects sensitive payloads, and records batch reconciliation status. |
Authentication and security considerations
Tenant-specific authentication
UKG Pro authentication varies by product, module, endpoint, and tenant. Supported scenarios may use OAuth 2.0 bearer tokens, client credentials, scopes, tenant-issued API credentials, API keys, or legacy service-account authentication for web services.
Protect workforce data
- Store client secrets, API keys, and service credentials in Martini secrets management.
- Use least-privilege scopes and tenant permissions.
- Use HTTPS and restrict access to workflow payloads and error details.
- Exclude payroll, tax, banking, and identity data from routine logs.
- Apply suitable retention, deletion, and environment-separation policies.
Operational considerations for UKG Pro integrations
Reliability and throughput
- Handle HTTP 429 responses and other transient failures with bounded exponential backoff.
- Respect endpoint-specific pagination, request-size, concurrency, and batch limits.
- Use checkpoints and safe recovery for long-running page or file sequences.
- Prefer modification filters, effective dates, and overlap windows for incremental synchronization.
Data correctness
- Use stable UKG Pro identifiers, correlation IDs, and idempotent target writes.
- Model future-dated changes separately from current state.
- Protect mappings against nullable fields, enumeration changes, date formats, relationship changes, and API-version retirement.
- Separate business validation failures from transport failures and produce reconciliation totals.
Why use Martini instead of scripts or point-to-point integrations?
One orchestration layer
Martini coordinates UKG Pro APIs, SOAP services, callbacks, schedules, files, and downstream systems in maintainable workflows rather than scattering logic across scripts or point-to-point integrations.
Reusable integration behavior
Teams can centralize authentication, pagination, mapping, validation, effective-date rules, retries, correlation, and reconciliation while exposing normalized APIs to multiple consumers.
Operational control
- Use environment-specific secrets and configuration.
- Apply consistent error handling and replay rules.
- Monitor workflow outcomes and protect sensitive HR and payroll data.
- Extend workflows with custom logic when tenant-specific behavior requires it.
Frequently asked questions
UKG Pro can be integrated through supported REST APIs, selected SOAP web services, product- or tenant-specific event callbacks, scheduled synchronization, and file-based imports or exports. The appropriate method depends on the UKG Pro product, module, tenant configuration, and data object.
Yes. Martini can integrate with UKG Pro by consuming supported REST APIs and SOAP web services, receiving applicable callbacks, orchestrating scheduled synchronization, transforming UKG Pro data, and delivering it to enterprise applications or normalized APIs.
No. A dedicated UKG Pro connector is not required. Martini can use UKG Pro's confirmed native integration mechanisms, including REST APIs, supported SOAP services, callbacks, scheduled workflows, and file-based exchanges.
Lonti does not charge an additional per-connector or per-vendor fee to integrate UKG Pro. Integrations are subject to the provisioned capacity of the Martini environment. Separate costs may apply from UKG, infrastructure providers, or other third-party systems based on subscription, usage, and deployment model.
REST APIs are the primary choice for supported current capabilities. SOAP is appropriate for selected or legacy web-service scenarios, while callbacks should be used only for explicitly supported events. Scheduled polling, batch processing, and file exchange remain practical where real-time delivery or endpoint coverage is limited.
UKG Pro should be treated as having limited, product-specific event coverage rather than universal webhooks for every object. Where a tenant exposes a supported callback, Martini can receive and process it; otherwise, scheduled polling and incremental synchronization are appropriate.
Use vendor-supported modification filters, effective dates, or change indicators where available, with a Martini watermark and overlap window when needed. Map UKG Pro objects through a canonical model, use stable identifiers and idempotent writes, paginate safely, retry transient failures with bounded backoff, and reconcile accepted, rejected, skipped, and retried items.
Yes. Martini can expose a controlled REST API that presents normalized UKG Pro data to downstream applications. The façade can centralize authentication, field mapping, validation, business rules, caching, and access to UKG Pro while isolating consumers from tenant-specific API details.
Related Martini documentation
Data
Operations
Plan your UKG Pro integration
Use Martini to connect UKG Pro with enterprise applications through governed APIs, workflows, data mappings, scheduled synchronization, and resilient error handling.