Overview

UKG Pro HCM (formerly UltiPro) is a cloud-based human capital management suite from UKG that covers core HR, payroll, talent and workforce management. Organizations use it as the system of record for employee personal data, job and compensation information, tax locations and employment lifecycle events such as job changes and terminations.

The Leena AI UKG Pro HCM connector lets your AI Colleague read and update employee data in UKG Pro. You can look up an employee's contacts, personal details, employment and compensation details, pay statements and recent changes, and you can submit updates (name and address, SSN, private information, job and salary, work location, and terminations) through the UKG Pro Import Tool, then check the status of those updates.

API Details

Leena AI integrates with UKG Pro HCM via the UKG Pro REST APIs (Personnel, Payroll and Import Tool APIs).

Documentation link: https://developer.ukg.com/hcm/reference

Setup

Prerequisites

Before you set up the connection, make sure you have:

• Access to UKG Pro with permissions to create or manage web service (service) accounts, or a UKG Pro administrator who can do this for you.
• A UKG Pro web service account (username and password) that is allowed to call the web services used by this connector:
  • Personnel APIs (person details, contacts, employment details, compensation details, employee changes, Import Tool).
  • Payroll APIs (employee pay statements), if you plan to use Get employee payroll data.
  • Configuration APIs (code tables, jobs, locations, org levels, shift codes). Leena AI uses these to load dropdown options such as job codes, locations and termination reasons in the action forms.
• Your tenant's Customer API key (sent as the US-CUSTOMER-API-KEY header).
• Your tenant's UKG Pro API base URL (for example, https://servicet.ultipro.com). The host differs by tenant and environment, so confirm it with your UKG Pro administrator.

Get credentials

1. Sign in to UKG Pro as an administrator.
2. Open the web services administration area (typically Menu > System Configuration > Security > Web Services or Service Account Administration).
3. Note the Customer API Key shown for your tenant. This is the value for US-customer-API-KEY in Leena AI.
4. Create a service account (or use an existing one) and grant it access to the web services listed in the prerequisites. Give it View access for the read actions and Add/Change access for the services behind the update actions (Import Tool).
5. Note the service account's username and password.
6. Confirm your tenant's API Base URL (the host part of your UKG Pro web services endpoint, for example https://servicet.ultipro.com).

Add connection

1. Log in to your Leena AI workspace
2. Navigate to Settings > Integrations, search for "UKG Pro HCM" and select it to add a new connector
3. For Auth type, select Username and password.
4. Fill in the fields:

5. Save the connection and run Test connection.

Leena AI authenticates every request with HTTP Basic authentication (username and password) and sends the customer API key in the US-CUSTOMER-API-KEY header. All actions and dropdowns call the Base URL saved on the connection. If no Base URL is saved (for example, on connections created before the field was added), they use https://servicet.ultipro.com.

Test connection

Test connection makes a lightweight call to the UKG Pro person-details API (one record), using the Base URL, username, password and customer API key on the connection. Possible results:

• Success: "Connection test (Username and password) was successful. The connection is working properly."
• Missing credentials: "Missing required credentials (Username, Password, US-CUSTOMER-API-KEY)."
• Wrong Base URL or customer API key: "The UKG Pro API could not be reached with the provided details. Please verify the Base URL and US-CUSTOMER-API-KEY are correct." You see this when UKG returns a 404 or an HTML page instead of an API response, which usually means the host or the API key is wrong.
• Other HTTP errors (for example, 401 for a wrong username or password, or 403 for a service account without access to the person-details service): an error message based on the HTTP status and the details UKG returned.
• Network errors (for example, a host that cannot be resolved, or a timeout after 15 seconds): "Connection test failed:

Actions

Get Employee Contacts

Retrieves the contacts (for example emergency contacts, dependents and beneficiaries) recorded for an employee in UKG Pro.

Here are some common use cases:

• Let an employee check who is listed as their emergency contact.
• Check an employee's dependents and beneficiaries before a benefits conversation.

Input Parameters

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

Mandatory

Here is a sample JSON input:

{
  "employeeId": "EB5KU3000020"
}

Response

• A list of the employee's contacts. Each contact includes:
  • Name details: first, middle and last name, suffix, former name.
  • Relationship code and description, and whether the contact is an emergency contact, dependent or beneficiary.
  • Address (address lines, city, county, state, ZIP code, country), and whether it differs from the employee's address.
  • Phone numbers (home, work with extension, other, preferred) and email address.
  • Personal details such as date of birth, gender, marriage, divorce and death dates, smoker, student and disabled flags.
  • COBRA details (status, reason, event and letter dates, notes).
  • Identifiers such as contact ID, person ID, SSN, national ID and health care ID, and the active status.

Get Employee Details

Retrieves person details for one employee or a filtered, paginated list of employees in UKG Pro.

Here are some common use cases:

• Look up an employee's personal information (name, email, home address, phone) from their employee ID.
• Find an employee by last name or email address.

Input Parameters

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

Optional

Here is a sample JSON input:

{
  "employeeId": "EB5KU3000020",
  "perPage": 100,
  "pageNumber": 1,
  "lastName": "Smith",
  "emailAddress": "[email protected]"
}

Response

• Person details for each matching employee, including:
  • Identifiers: employee ID, person ID, company ID, user name.
  • Names: first, middle, last, preferred and former names, prefix and suffix codes.
  • Contact details: primary and alternate email, home phone, home address (address lines, city, state, ZIP code, county, country).
  • Personal details: date of birth, gender, marital status code, ethnic code and description, disability, smoker status, nationality.
  • Identification: SSN, national ID and country, I-9 details.
  • Military service details, COBRA details and created/changed timestamps.

Get Employee Payroll Data

Retrieves an employee's pay statements in UKG Pro for a date range.

Here are some common use cases:

• Answer "What was my net pay on my last paycheck?"
• Show the earnings, deductions and taxes on pay statements within a period.

Input Parameters

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

Mandatory

Optional

Here is a sample JSON input:

{
  "startDate": "2026-01-01",
  "endDate": "2026-03-31",
  "eeid": "EB5KU3000020",
  "page": 1
}

Response

• A list of pay statements. Each pay statement includes:
  • Pay date, pay period start and end dates, pay period frequency, pay group and pay identifier.
  • Gross wages, deductions, taxes and net pay (current and year-to-date).
  • Earnings lines (pay code and description, hours, rate, amount, YTD values).
  • Deduction lines (code, description, employee and employer amounts, pre-tax flag).
  • Tax lines (code, description, amount, basis amount, YTD).
  • Net pay distribution (account type, account number, amount).
  • Federal and state filing status and allowances, job, location, org levels 1–4.
  • Employee and company names and addresses, and the employee's SSN.

Get Compensation Details

Retrieves compensation details for an employee in UKG Pro.

Here are some common use cases:

• Answer "What is my current annual salary or hourly rate?"
• Check an employee's pay group, salary grade and last salary review date.

Input Parameters

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

Mandatory

Here is a sample JSON input:

{
  "employeeId": "EB5KU3000020"
}

Response

• Compensation details, including:
  • Pay rates: annual salary, hourly, weekly and pay-period rates, other rates 1–4, piece pay rate, currency code.
  • Job information: primary job code, job title, salary grade, job group, job change reason, date in job.
  • Pay group code and description, pay period, pay scale code, salary or hourly code, full- or part-time code.
  • Scheduled hours: FTE, period work hours, annual work hours, weekly hours, primary shift and shift group.
  • Dates: last paid, last worked, paid through, last and next salary review.
  • Flags such as auto-paid, auto-allocated, seasonal, highly compensated and multiple jobs, plus performance review rating and type.

Get Employment Details

Retrieves employment details for an employee in UKG Pro.

Here are some common use cases:

• Answer "Who is my supervisor?" or "What is my hire date?"
• Check an employee's status, job, location and org levels before routing a request.

Input Parameters

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

Mandatory

Here is a sample JSON input:

{
  "employeeId": "EB5KU3000020"
}

Response

• Employment details for the employee (the first record UKG returns), including:
  • Identifiers: employee ID, employee number, company ID, home company, supervisor ID.
  • Job: job code, primary job code, job title, job group, job change reason, position code, date in job.
  • Organization: org level 1–4 codes, primary work location, primary project.
  • Status: employee status code and start date, employee type code, full- or part-time code, salary or hourly.
  • Dates: original and last hire dates, seniority and benefit seniority dates, last worked, paid through, termination, retirement and suspension dates.
  • Termination details: termination reason code and description, term type, OK to rehire.
  • Pay and schedule: pay group, pay period, annual salary, hourly pay rate, salary effective date, scheduled FTE and hours, weekly hours, shift and shift group.
  • Work phone number, extension and country, union codes, and created/changed timestamps.

Get Employee Changes

Retrieves recent changes to employee records in UKG Pro, for one employee or for all employees.

Here are some common use cases:

• Check what changed recently on an employee's record (for example a new job code, location or supervisor).
• Sync recent hires, terminations and changes into another system.

Input Parameters

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

Optional

Here is a sample JSON input:

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

Response

• A list of changed employee records. Each record includes:
  • Identifiers: employee ID, employee number, person ID, user integration key, company ID and name.
  • Names, preferred name, prefix, suffix, primary and alternate email, work and home phone, address.
  • Job and organization: job code, job group, alternate job title, work location, project, org level 1–4 codes, supervisor ID and name.
  • Status: active flag, employee status, employee type, full- or part-time, salary or hourly.
  • Dates: hire date, date of last hire, termination date, date in job, status start date.

Get Import Tool Status

Retrieves the status of an update submitted to UKG Pro through the Import Tool. Use it to confirm whether an update or termination submitted by one of the update actions below was processed.

Input Parameters

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

Mandatory

Here is a sample JSON input:

{
  "transactionId": "3c64b062-96cf-4273-9072-0c85a743d513"
}

Response

• Staging ID of the transaction.
• Status of the transaction.
• Employee name and employee number.
• Transaction details and file name.
• File process date, service submittal date and last repost date.

Update Employee Data

Updates an employee's name, contact details and home address in UKG Pro (Import Tool transaction type NAMEADDRESS).

Here are some common use cases:

• Let employees update their home address or phone numbers from chat.
• Update a preferred name or alternate email address.

Input Parameters

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

Mandatory

Optional

Here is a sample JSON input:

{
  "employeeNumber": "100245",
  "companyCode": "USG_1",
  "firstName": "John",
  "lastName": "Smith",
  "preferredName": "Johnny",
  "emailAddress": "[email protected]",
  "alternateEmail": "[email protected]",
  "maritalStatusCode": "M",
  "phoneHomeNumber": "5125550123",
  "phoneHomeCountryCode": "USA",
  "phoneBusinessNumber": "5125550188",
  "phoneBusinessExtension": "204",
  "phoneBusinessCountryCode": "USA",
  "addressLine1": "1200 Main Street",
  "addressLine2": "Apt 4B",
  "addressCity": "Austin",
  "addressCountryCode": "USA",
  "addressStateCode": "TX",
  "addressCounty": "Travis",
  "addressZipCode": "78701"
}

Response

• The Import Tool submission details: stagingId, creation timestamp and file name. Use the stagingId with Get Import Tool Status to confirm the update.

Update Employee SSN

Updates an employee's Social Security number and, optionally, national ID and its expiry date in UKG Pro (Import Tool transaction type NATIONALID).

Input Parameters

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

Mandatory

Optional

Here is a sample JSON input:

{
  "employeeNumber": "100245",
  "companyCode": "USG_1",
  "ssn": "123456789",
  "nationalId": "A1234567",
  "nationalIdExpireDate": "12/31/2030"
}

Response

• The Import Tool submission details: stagingId, creation timestamp and file name. Use the stagingId with Get Import Tool Status to confirm the update.

Update Employee Private Information

Updates an employee's date of birth and gender in UKG Pro (Import Tool transaction type PRIVATEINFO).

Input Parameters

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

Mandatory

Optional

Here is a sample JSON input:

{
  "employeeNumber": "100245",
  "companyCode": "USG_1",
  "dateOfBirth": "04/15/1990",
  "genderCode": "M"
}

Response

• The Import Tool submission details: stagingId, creation timestamp and file name. Use the stagingId with Get Import Tool Status to confirm the update.

Terminate Employee

Terminates an employee in UKG Pro (Import Tool transaction type TERMINATION), including termination reason, rehire and severance eligibility, payroll and COBRA details.

Here are some common use cases:

• Process a voluntary resignation once it is approved in an offboarding workflow.
• Record the last day worked, paid-through date and COBRA qualifying event for a leaver.

Input Parameters

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

Mandatory

Optional

Here is a sample JSON input:

{
  "employeeNumber": "100245",
  "companyCode": "USG_1",
  "dateOfTermination": "10/31/2026",
  "lastDateWorked": "10/31/2026",
  "datePaidThru": "10/31/2026",
  "termReasonCode": "100",
  "termNote": "Resigned to accept another position.",
  "eligibleForRehire": "Y",
  "eligibleForSeverance": "N",
  "directDepositInactive": "Y",
  "inactivateAutoPay": "Y",
  "isCobraQualifying": "Y",
  "cobraDateOfEvent": "10/31/2026",
  "cobraReason": "200"
}

Response

• The Import Tool submission details: stagingId, creation timestamp and file name. Use the stagingId with Get Import Tool Status to confirm the termination.

Update Job Salary

Updates an employee's job and compensation information in UKG Pro as of an effective date (Import Tool transaction type JOBSALARY). The transaction is submitted with the BACKDATEWITHLATEST job effective rule, which lets you use backdated effective dates.

Here are some common use cases:

• Apply an approved pay rise or promotion.
• Move an employee to a new job code, org level, shift or supervisor.

Input Parameters

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

Mandatory

Optional

Fields marked Form and JSON appear in the form when Form based input? is on, and can also be sent as keys in JSON input. Fields marked JSON only have no form field and can only be sent through JSON input. In JSON input, use the key names shown in brackets. JSON values are passed to UKG Pro as given, without the format checks the form applies, so use the same codes and Y/N values as the form.

Here is a sample JSON input (form based):

{
  "employeeNumber": "100245",
  "companyCode": "USG_1",
  "effectiveDate": "11/01/2026",
  "jobChangeReason": "PROMO",
  "formBasedInput": true,
  "jobCode": "MGR01",
  "alternateJobTitle": "Engineering Manager",
  "orgLevel1Code": "ENG",
  "salaryOrHourly": "S",
  "fullOrPartTimeCode": "F",
  "isPromotion": "Y",
  "supervisorId": "EB5KU3000045",
  "supervisorCompanyCode": "USG_1"
}

Here is a sample JSON input (using JSON input):

{
  "employeeNumber": "100245",
  "companyCode": "USG_1",
  "effectiveDate": "11/01/2026",
  "jobChangeReason": "MERIT",
  "formBasedInput": false,
  "jsonInput": {
    "yearlyPayRate": "98000",
    "payScale": "PS2",
    "payStep": "3",
    "currencyCode": "USD",
    "paymentsPerYear": "26",
    "weeklyHours": "40",
    "salaryOrHourly": "S"
  }
}

Response

• The Import Tool submission details: stagingId, creation timestamp and file name. Use the stagingId with Get Import Tool Status to confirm the update.

Update Work Location

Updates an employee's work (tax) location in UKG Pro. For US employees the action submits a WORKLOCATION transaction (US work-in tax details). For Canadian employees it submits a CAWORKLOCATION transaction (provincial tax details).

Here are some common use cases:

• Move an employee to a new office or work-in state after a relocation.
• Update provincial tax details for a Canadian employee.

Input Parameters

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

Mandatory

Optional

USA

Canada

Here is a sample JSON input (USA, form based):

{
  "employeeNumber": "100245",
  "companyCode": "USG_2",
  "country": "USA",
  "formBasedInput": true,
  "workInLocationCode": "TX",
  "workInIsPrimaryLocation": "Y",
  "workInIsActiveLocation": "Y"
}

Here is a sample JSON input (Canada, using JSON input):

{
  "employeeNumber": "100245",
  "companyCode": "CAN_1",
  "country": "CAN",
  "formBasedInput": false,
  "jsonInput": {
    "provinceLocationCode": "ON",
    "provinceIsPrimary": "Y",
    "provinceTotalClaimAmount": "15705",
    "provinceAdditionalAmountWithheld": "50"
  }
}

Response

• The Import Tool submission details: stagingId, creation timestamp and file name. Use the stagingId with Get Import Tool Status to confirm the update.