Overview

The UKG Pro HCM connector enables your Leena AI Agents to integrate with your organization's UKG Pro Human Capital Management platform, facilitating automated employee data management, payroll operations, and HR workflows.

UKG Pro HCM is a comprehensive human capital management solution that provides end-to-end HR, payroll, and workforce management capabilities. The UKG Pro HCM connector allows Leena AI to automate HR workflows, retrieve employee information, manage compensation data, and process employee lifecycle events seamlessly.

API Details

Leena AI integrates with UKG Pro HCM via REST APIs.

Documentation link: UKG Pro HCM API Documentation

Setup

The UKG Pro HCM connector uses Basic Authentication with username and password credentials.

Prerequisites

Before setting up the UKG Pro HCM connector, ensure you have:

• Administrator access to your UKG Pro HCM system
• Service account credentials with appropriate API permissions
• US Customer API Key from UKG Pro
• Access to your Leena AI workspace with connector management permissions

Get credentials

Here is how to obtain credentials for UKG Pro HCM:

1. Log in to UKG Pro HCM (Ensure you're signed in as an admin)
2. Navigate to System Configuration
3. Create or identify a service account with the following permissions:
   1. Personnel API access
   2. Payroll API access
   3. Import Tool access
4. Obtain your US Customer API Key:
   1. Contact your UKG Pro account administrator
   2. Request the US-CUSTOMER-API-KEY for API integrations
   3. Save this key securely as it will be needed during connector configuration
5. Note down the service account credentials (username and password)

Add connection

Here is how to add a connection on Leena AI:

1. Log in to your Leena AI workspace

2. Navigate to Settings > Integrations

3. Search for "UKG Pro HCM" and select it from the list to add its new connector

4. Start configuring the connector

   1. Username: Your UKG Pro HCM service account username
   2. Password: Your UKG Pro HCM service account password
   3. US Customer API Key: Your US-CUSTOMER-API-KEY provided by UKG Pro
   4. Base URL: Your UKG Pro service endpoint (Pre-filled as https://servicet.ultipro.com)

5. Test the connection

   1. Click Test Connection to verify credentials
   2. Ensure all authentication parameters are correct

6. Save the connector configuration

   

Actions

The following actions are supported for the UKG Pro HCM connector:

Get Employee Contacts

Retrieves contact information for a specific employee including emergency contacts, dependents, and beneficiaries. The Agent can leverage this action to fetch comprehensive contact details for any employee in the organization.

Input Parameters

Here are the input parameters required to set up this action:

Mandatory

Response

The action returns contact information including:

• Contact details (name, address, phone numbers)
• Relationship information (emergency contacts, dependents, beneficiaries)
• COBRA information and eligibility status
• Contact identifiers and status information

Get Employee Details

Retrieves comprehensive person details including personal information, demographics, and contact details with pagination support. This action can be leveraged by Leena AI Orchestrator/Agent to get detailed employee information with filtering capabilities. Here are some common use cases:

• Employee Lookup: Find employee by ID, email, or last name

• Bulk Employee Data: Retrieve multiple employee records with pagination

• Profile Information: Access complete employee demographic and contact information

• Data Auditing: Review employee information for compliance purposes

  

Input Parameters

Here are the input parameters required to set up this action:

Mandatory

None (all parameters are optional)

Optional

Here is a sample JSON input:

{
  "employeeId": "EB5KU3000020",
  "per_Page": 100,
  "page": 1
}

Response

The action returns comprehensive employee details including:

• Personal information (name, date of birth, gender, SSN)
• Contact information (email, phone, address)
• Employment identifiers and company information
• Health and demographic details
• I-9 verification and work authorization status
• COBRA status and military service information

Get Employee Payroll Data

Retrieves employee pay statements for a specified date range including earnings, deductions, and tax information. This action enables comprehensive payroll data access for reporting, analysis, and employee inquiries. Here are some common use cases:

• Pay Statement Retrieval: Access detailed pay information for specific periods

• Year-to-Date Analysis: Review cumulative earnings and deductions

• Tax Information: Retrieve federal and state tax withholding details

• Deduction Tracking: Monitor benefit deductions and contributions

  

Input Parameters

Here are the input parameters required to set up this action:

Mandatory

Optional

Here is a sample JSON input:

{
  "startDate": "2024-01-01",
  "endDate": "2024-12-31",
  "employeeIdentifier": {
    "eeid": "EB5KU3000020"
  },
  "page": 1,
  "per_page": 10000
}

Response

The action returns detailed payroll information including:

• Earnings breakdown by pay code (regular, overtime, holiday)
• Deductions (insurance, retirement, garnishments)
• Tax withholdings (federal, state, local)
• Net pay and payment method details
• Year-to-date totals for all categories
• Pay period and organizational information

Get Compensation Details

Retrieves compensation information for an employee including salary, pay rate, and compensation history. This action provides access to current compensation structures and payment details.

Input Parameters

Here are the input parameters required to set up this action:

Mandatory

Response

Upon successful retrieval, the action returns compensation details including:

• Annual salary and hourly pay rate
• Weekly and pay period pay rates
• Job and salary grade information
• Pay group and schedule details
• Job change reason and dates
• Performance review information

Get Employment Details

Retrieves employment details for an employee including job information, status, hire date, and organizational structure. This action provides comprehensive employment relationship data.

Input Parameters

Here are the input parameters required to set up this action:

Mandatory

Response

The action returns employment information including:

• Job codes and organizational hierarchy
• Employment dates (hire, termination, dates in position)
• Employment status and type (full-time/part-time)
• Supervisor and work location information
• Benefit seniority and scheduled hours
• Pay group and retirement dates

Get Employee Changes

Retrieves a log of changes made to employee records with pagination support. Useful for auditing and tracking employee data modifications. Here are some common use cases:

• Audit Trail: Track all modifications to employee records

• Compliance Reporting: Document changes for regulatory requirements

• Data Verification: Review recent updates to employee information

• Change History: Analyze patterns in employee data updates

  

Input Parameters

Here are the input parameters required to set up this action:

Mandatory

None (all parameters are optional)

Optional

Here is a sample JSON input:

{
  "employeeId": "EB5KU3000020",
  "page": 1,
  "per_page": 100
}

Response

The action returns a log of employee changes including:

• Modified employee information
• Change timestamps
• Current employment status and details
• Updated compensation information
• Modified organizational assignments

Get Import Tool Status

Checks the status of an import transaction submitted via the import tool. Essential for tracking asynchronous update operations. This action allows monitoring of bulk data imports and updates to ensure successful processing.

Input Parameters

Here are the input parameters required to set up this action:

Mandatory

Response

Upon successful status check, the action returns:

• Transaction staging ID
• Processing dates (file process, service submittal)
• Employee information
• Transaction status (Passed, Failed, Processing)
• Transaction type description
• Associated file name
• Status messages and error details (if applicable)

Update Employee Data

Updates employee name, address, contact information, and marital status using UKG Pro's import tool with XML-based transactions. The Agent can leverage this action to modify employee personal and contact information. Here are some common use cases:

• Address Updates: Change employee residential address

• Contact Information: Update phone numbers and email addresses

• Name Changes: Process legal name changes

• Marital Status: Update employee marital status records

  

Input Parameters

Here are the input parameters required to set up this action:

Mandatory

Optional

Here is a sample JSON input:

{
  "employeeNumber": "321543238",
  "companyCode": "HDLBX",
  "firstName": "John",
  "lastName": "Smith",
  "emailAddress": "[email protected]",
  "phoneHomeNumber": "5551234567",
  "addressLine1": "123 Main Street",
  "addressCity": "Atlanta",
  "addressState": "GA",
  "addressZipCode": "30318"
}

Response

Upon successful update, the action returns:

• Staging ID for the import transaction
• Transaction creation timestamp
• Generated file name for tracking
• Transaction status

Update Employee SSN

Updates employee Social Security Number and national ID information. This action handles sensitive employee identification data updates.

Input Parameters

Here are the input parameters required to set up this action:

Mandatory

Optional

Here is a sample JSON input:

{
  "employeeNumber": "321543238",
  "companyCode": "HDLBX",
  "ssn": "123456789",
  "nationalId": "123456789",
  "nationalIdExpireDate": "12/31/2030"
}

Response

Upon successful update, the action returns:

• Staging ID for the import transaction
• Transaction creation timestamp
• Generated file name for tracking
• Transaction status

Update Employee Private Information

Updates sensitive employee information including date of birth and gender. This action handles confidential personal information updates.

Input Parameters

Here are the input parameters required to set up this action:

Mandatory

Optional

Here is a sample JSON input:

{
  "employeeNumber": "321543238",
  "companyCode": "HDLBX",
  "dateOfBirth": "01/15/1985",
  "genderCode": "F"
}

Response

Upon successful update, the action returns:

• Staging ID for the import transaction
• Transaction creation timestamp
• Generated file name for tracking
• Transaction status

Terminate Employee

Terminates an employee with comprehensive termination details including COBRA information, severance eligibility, and ROE data. The Agent can leverage this action to process employee terminations with complete compliance documentation. Here are some common use cases:

• Employee Separation: Process standard employee terminations

• Compliance Documentation: Record all required termination details

• COBRA Management: Handle COBRA qualifying events

• Final Pay Processing: Configure final payment dates and methods

  

Input Parameters

Here are the input parameters required to set up this action:

Mandatory

Optional

Here is a sample JSON input:

{
  "employeeNumber": "321543238",
  "companyCode": "HDLBX",
  "dateOfTermination": "12/31/2024",
  "lastDateWorked": "12/31/2024",
  "datePaidThru": "12/31/2024",
  "termReasonCode": "VOL",
  "eligibleForRehire": "Y",
  "eligibleForSeverance": "N",
  "isCobraQualifying": "Y",
  "cobraDateOfEvent": "12/31/2024",
  "sendUpdates": "all"
}

Response

Upon successful termination processing, the action returns:

• Staging ID for the termination transaction
• Transaction creation timestamp
• Generated file name for tracking
• Transaction status

Update Job Salary

Updates employee job and salary information including job title, compensation, pay rates, organizational structure, and supervisor assignment using UKG Pro's import tool with XML-based transactions. The Agent can leverage this action to modify employee compensation and job-related information. Here are some common use cases:

• Salary Adjustments: Process pay rate changes and annual salary updates

• Job Changes: Update job codes, titles, and organizational assignments

• Promotions: Record promotions with updated compensation

• Supervisor Changes: Assign new supervisors to employees

• Organizational Restructuring: Update org level assignments

  

Input Parameters

Here are the input parameters required to set up this action:

Mandatory

Optional

Here is a sample JSON input:

{
  "employeeNumber": "102539647",
  "companyCode": "USG_1",
  "effectiveDate": "12/01/2024",
  "jobChangeReason": "PROMO",
  "hourlyPayRate": 25.00,
  "salaryOrHourly": "H",
  "jobCode": "ENGR02",
  "orgLevel1Code": "TECH",
  "orgLevel2Code": "DEV",
  "isPromotion": "Y",
  "supervisorId": "1HHN36000080",
  "supervisorCompanyCode": "USG_1"
}

Response

Upon successful update, the action returns:

• Staging ID for the import transaction
• Transaction creation timestamp
• Generated file name for tracking
• Transaction status

Update Work Location

Updates employee work location and tax information for both USA and Canada. This action handles country-specific tax settings and location assignments using UKG Pro's import tool with XML-based transactions. The Agent can leverage this action to modify employee work locations and associated tax configurations. Here are some common use cases:

• Location Transfers: Update employee work location assignments

• Tax Configuration: Modify state/provincial tax withholding settings

• Multi-location Management: Manage primary and secondary work locations

• Cross-border Assignments: Handle USA and Canada location updates

• Tax Exemption Updates: Configure tax exemption and allowance settings

  

Input Parameters

Here are the input parameters required to set up this action:

Mandatory

USA-Specific Required

USA-Specific Optional

Canada-Specific Required

Canada-Specific Optional

Here is a sample JSON input for USA:

{
  "employeeNumber": "571957925",
  "companyCode": "USG_2",
  "country": "USA",
  "workInLocationCode": "ATLANT",
  "workInIsPrimaryLocation": "Y",
  "workInIsActiveLocation": "Y",
  "workInFilingStatusCode": "S",
  "workInTotalAllowances": 2
}

Here is a sample JSON input for Canada:

{
  "employeeNumber": "571957925",
  "companyCode": "USG_2",
  "country": "CAN",
  "provinceLocationCode": "ON",
  "provinceIsPrimary": "Y",
  "provinceTotalClaimAmount": 15000.00,
  "provinceUseBasicPersonalAmount": "Y"
}

Response

Upon successful update, the action returns:

• Staging ID for the import transaction
• Transaction creation timestamp
• Generated file name for tracking
• Transaction status