Who can use this feature?
Available on:
All Culture Amp subscriptions.
You can import employee data directly from UKG Pro into Culture Amp using a secure, one-way API connection. This ensures your employee list and demographics are always up-to-date.
Data Flow: Employee Data flows from UKG Pro flows into Culture Amp (one-way sync). Changes made in Culture Amp will not sync back to your HRIS.
Initial Setup Timeframe: Please note that due to the complexity and customization of UKG Pro, the full setup and validation process can take anywhere from a few days to several weeks. Please allocate sufficient time and internal resources for mapping and validation.
Choosing Your Integration Method
We offer two primary ways to connect your employee data. The table below briefly outlines both and should help with the decision on which is the best approach for your organization:
Method | Type of Import | Best For | Key Difference |
Full Integration (API) | Full Employee Import | Organizations seeking real-time, daily automation of all employee data that the API supports. | Data transfer is handled automatically via a secure, direct API connection.
Users with an explicit termination date ( |
Partial Employee Import | Organizations that need complete control over file creation, have unique filtering requirements, or need to manage data fields not supported by the API. | You generate a file and securely transfer it to us at scheduled intervals. Users missing from the file are ignored, so must be included on the file with an end date, to become former. |
API Integration Checklist
Access Requirements & Terminology — Prerequisites and system logic.
Step 1: Connect & Authenticate — Locating and entering your API credentials.
Step 2: Field Mapping — Aligning your UKG Pro demographics with Culture Amp.
Step 3: Activate Integration — Establishing the technical connection.
Step 4: Run Your First Sync — Reviewing and importing employee records.
Troubleshooting & FAQs — Solving errors, duplicates, and sync blocks.
Before You Start: Access Requirements & Terminology
To set up the connection, you’ll need:
Access to your UKG Pro instance with the required role (see Permissions below).
Access to Culture Amp with Account Administrator or Employee data administrator permissions.
Important Considerations & Data Limitations
Important Considerations & Data Limitations
Important Considerations:
UKG Pro is a highly customizable system. For best results, we strongly recommend involving a technical UKG Pro administrator who is familiar with your specific API configuration.
Initial Setup Timeframe: Be aware that due to system complexity and customization requirements, the entire setup and validation process for this integration can take anywhere from several days up to a few weeks. Please allocate sufficient time and internal resources to complete the necessary mapping and validation steps.
Data Access Limitations:
Some fields, their properties, or specific values may not be accessible because they do not form part of the regular API endpoint.
The Issue: If a field's desired value (like a descriptive name) is located in a complex, non-standard object that the API does not expose, the integration may only be able to pull the associated internal code/ID.
Example: For
Org Level #, the API currently only returns the associated internal codes (e.g., 'SLS1') during the data sync. Mapping toOrg Level # = descriptionis not yet supported.
Field Expansions & Custom Data:
UKG Pro has multiple ways to set up custom fields, but the API has specific limitations on which ones it can "see."
Personnel vs. Company Fields: The integration can only retrieve User-Defined Fields (UDFs) located on the "Other Personal Information"(
personnelUserDefinedFields) page in UKG Pro (Business Rules > Business Rules > User-defined fields)Unsupported Fields: Fields configured on the "Other Company Information" page (
companyUserDefinedFieldsList) or "Platform Configuration Fields" are not currently stored or accessible via this integration.Use User-Defined Fields: Please use User-Defined Fields for any custom data you wish to sync, or start a support conversation with one of our Data and Integrations specialists by typing "Ask a Person" to explore whether an adhoc mapping may be possible.
Terminology Breakdown
Terminology Breakdown
When working with your technical UKG administrator, these terms may be helpful for clarifying your data structure:
Term | Also Known As | Definition & Example |
Object | Entity or Table | The high-level data container or category that holds a group of related fields (e.g., the "Personnel" or "Employment" object) |
Component / Page | Personnel or Employment | The container or table where the data lives (e.g., |
Field | Field, Data Field, or Element | The specific piece of data you are tracking (e.g., "Job Title," "Email," "Start Date"). |
Property | Field Attributes | The rules for that field, such as whether it is a "Text" field, a "Date" field, or a "Required" field. |
Value | Data Point | The specific data assigned to the employee (e.g., "Software Engineer"). |
Required Permissions & Rationales (Technical)
Required Permissions & Rationales (Technical)
Having the correct UKG Pro permissions is essential. Most setup and field-mapping issues occur when the service account does not have access to the right objects.
Permission/Role | Permissions Needed in UKG Pro | Rationale |
Employee Data | View access for Personnel (Person Details) and Employment (Job History/Employment Details) | Allows the integration to retrieve core identity and employment history, such as Name, Email, Start Date, and Job Title. |
Groups & Org Structure | View access for Organization Levels (Org Levels 1-4) | Required to pull your company’s internal structure to create demographics like Department, Division, or Location. |
Custom Demographics | View access for User-Defined Fields (specifically those on the "Other Personal Information" page) | Necessary to sync any unique data points you track outside of standard fields, including the "Exclude from Culture Amp" flag. |
Web Services | View access for Web Services Administration | Required to generate the Customer API Key and Service Account credentials needed to link UKG Pro to Culture Amp. |
Tip: If you are trying to map a custom field and it does not appear in the mapping list, check if it is located on the "Other Company Information" page. If so, it will need to be recreated on the "Other Personal Information" page to be accessible via the API.
Step 1: Connect Your UKG Pro Account
Sign in to Culture Amp with an account that has Account Administrator or Employee data administrator access.
Navigate to your Settings > Account > Integrations page.
Select UKG Pro from the list of integrations and click Continue setup.
Click I am an admin to confirm your UKG Pro account administrator permissions.
Click Next to authorize Culture Amp's request to read your UKG Pro employee data.
Follow the interactive on-screen prompts to enter your credentials.
Entering your Service Account Credentials
Customer API Key: Locate your key in UKG Pro, paste it into Culture Amp, and click Next.
Service Account Credentials: Generate and copy across your Service Account credentials in UKG Pro and enter the Username and Password into Culture Amp. Click Next.
Web Services URL: Locate your URL in UKG Pro, enter the full URL into Culture Amp, and click Next.
Subdomain: On the next screen, select your Web Service URL subdomain from the dropdown based on your URL structure.
Click Submit to finalize the connection.
🔑 How to Locate Your API Key and Service Account Credentials
🔑 How to Locate Your API Key and Service Account Credentials
To authenticate your UKG Pro account, you will need to provide the Customer API Key, Service Account Credentials, a Web Services URL, and your Subdomain.
Note: The steps below are sourced from Merge, our integration partner. We recommend checking their official guide for the most current instructions: Merge UKG Pro Account Linking Guide.
Prerequisites
You must be an Administrator in your company's UKG Pro instance, or someone has shared their access with you.
Step 1: Find your UKG Pro Customer API Key
Log in to UKG Pro and search "Service Account Administration" on the top right
Copy the Customer API Key from under the header
Paste the Customer API Key in the linking flow
Step 2: Create your service account
On the Service Account Administration Page, click "+ add" on the top right
Create a new username and email for your service account.You will need the username later
On the same page, scroll down under Web Service to enable "View Employee Person Details". This is REQUIRED.
Depending on the use case, you may also be required to add some, or all, of these permissions:
Employee Pay Statement
Employee Employment Information
PTO Plan Integration
Company Configuration Integration
Payroll Integration
Personnel Integration
Employee Job History Details
Employee Compensation Details
Employee User Defined Fields
Click Save. Your new password will pop up. Save the password in a secure location
Enter your UKG Pro service account credentials in the linking flow and click Submit. This is user username of your service user and the password you just generated.
Step 3: Finding your UKG Web Service Domain
In your search bar, search for Web Services
Look at any of the URLs on this page and copy one of them. For example your URL may look something like this: http://Servicet.ultipro.com/services/BIDataService
Enter the URL into the linking modal.
Fields Culture Amp has Read Access to
Employees
Employees
Date Of Birth
Display Full Name
Employee Number
Employment Status
Ethnicity
First Name
Gender
Groups
Last Name
Manager
Marital Status
Mobile Phone Number
Personal Email
Preferred Name
Remote Created Timestamp
Start Date
Termination Date
Username
Work Email
Groups
Groups
Is Commonly Used As Team
Name
Type
Step 2: Setting Up Demographic Field Mapping
Once you have authenticated with UKG Pro, you will be prompted to map the demographic fields you would like to import into Culture Amp.
Core Demographics: Automatic Mapping
Core Demographics: Automatic Mapping
While the table below provides the most common, out-of-the-box fields, setting up and troubleshooting the UKG Pro API often requires a detailed understanding of the system's data structure.
UKG Pro is a highly customizable platform. Because every implementation is unique, there is no "one-size-fits-all" mapping. While the table below outlines the standard "out-of-the-box" configuration, your specific setup may vary, particularly if your organization has custom workflows for re-hires or contract changes.
This table is intended for your technical UKG Pro administrator. It lists the common UKG Pro field concepts, along with the primary UKG Pro API endpoints used to source each data object. This information helps ensure that the Service Account has the required Web Service permissions and View access for the data objects needed for the connection.
Note:
Do not manually map the fields below unless instructed by a specialist.
If the data for these core fields is not pulling correctly, reply with "Ask a Person" in a Support Conversation for a back-end custom mapping solution.
"Typical UKG Pro Source Field" shows the common reference field in UKG Pro. Exact UI labels and underlying field names may vary by tenant and configuration.
Typical UKG Pro Source Field | Primary UKG Pro API Endpoint (Data Location) | Culture Amp Field (The Destination) |
Work Email |
| Email (Unique Identifier) |
Employee Number |
| Employee ID (Unique Identifier) |
Display Full Name |
| Name |
Preferred Name |
| Preferred Name |
Date Of Birth |
| Date of Birth |
Start Date |
| Start Date |
Termination Date |
| End Date |
Manager (Work Email of referenced Manager) |
| Manager Email (Hierarchy demographic) |
Custom Demographics: Manual Mapping
Custom Demographics: Manual Mapping
If you track additional employee data in UKG Pro that you want to use as demographics in Culture Amp, follow these steps to set up custom mapping.
Note: UKG Pro fields can be highly customized. If you’re mapping a custom field and can’t find the data you need, check the Data Limitations section for more details. Our integration supports User-Defined Fields (UDFs) that are created in Business Rules → User-Defined Fields and are located on the "Other Personal Information" page in UKG Pro. At this time, fields found under "Platform Configuration" or on the "Other Company Information page" aren’t supported by the API.
Step 1. Map Fields
Now that the initial authentication is complete, on your Integrations page, click Map fields.
Step 2. Select the Data Model
Select the data model for your target field (e.g., Employee).
Step 3. Set Details for the Target Field
Set the details for the field you are targeting in Culture Amp (the demographic name, e.g., Gender).
Step 4. Choose the Matching Field from UKG Pro
Select the matching UKG Pro field that contains the data.
Step 5. Save Mappings
You can Save mappings or click the + Field mapping icon to add more.
Alternatively, if you’re not ready to map fields yet, you can click Skip for now and return to mapping later.
Tip: If you are unsure of the correct UKG Pro field, please involve your technical UKG Pro administrator to locate the correct API name.
Note: Some HRIS APIs may limit access to specific custom fields. If you cannot find a required demographic field during mapping, you may need to:
Map an alternate custom field that contains similar data.
Manage the demographic outside of UKG Pro directly in Culture Amp via manual imports or SFTP.
Excluding Employees (Optional)
Excluding Employees (Optional)
If you have specific employees in UKG Pro that you do not want to import into Culture Amp, you can set up an exclusion rule.
Step 1: Create the Exclusion Field in UKG Pro
You must create a specific type of custom field for the integration to recognize it.
Field Type: You must use a User-defined field.
Navigation: In UKG Pro, go to Business Rules > Business Rules > User-defined fields.
Note: Do not use "Platform Configuration" fields, as these are not supported by the integration.
Configuration: Create a field titled
Exclude from Culture AmpwithYesorNovalues.Action: Mark the employees you wish to exclude as
Yes.
Step 2: Contact Culture Amp Support (Required)
For UKG Pro customers, simply mapping the field is not enough to trigger the exclusion. You must contact Culture Amp support to finalize the backend configuration.
Reach out to Culture Amp’s Product Support Team by replying with "Ask a Person" in a support conversation to speak with a Specialist.
Let the Specialist know you need assistance with Basic Field Mapping to map the "Exclude from Culture Amp" field between Merge (API partner) and UKG Pro.
Once the Specialist confirms the update, the exclusion values will be recognized during your next sync.
Step 3: Start Mapping
After the basic field mapping has been set up, in Culture Amp, navigate to the Integrations page and click Map fields to begin the workflow.
Step 4: Select the Exclusion Field
Locate the Exclude from Culture Amp target field.
Search for and select the corresponding field you created in UKG Pro (e.g.,
excludeFromCultureAmp).Click Save mappings.
Step 3: Activate Integration
After mapping your fields, click Sync, and the system will run an initial sync to connect your UKG Pro account details and mappings.
Note: This sync does not import employee data yet.
You will see a "Syncing data" message. This initial sync can take up to 12 hours to complete, depending on the size and complexity of your UKG Pro configuration.
Feel free to navigate away from the page. The process runs in the background.
The "Syncing data" message confirms the connection and mapping setup. Once this first sync completes, you can proceed to import your employee data through another sync.
Note: As part of our commitment to data security, only data relevant to your import and field mappings will be stored.
Step 4: Run Your First Employee Data Sync
Once the initial setup sync is complete, the Integrations page in Culture Amp will update. Follow these steps to run your first employee data import:
Click the Finalise sync button.
Click Get Started.
On the review page, ensure Sync is selected in the "Sync with merge" section (ignore the other options).
Culture Amp will validate the data. If there are no concerns, click Next.
Review the data: Carefully examine the review screen, which shows the number of new employees to be created, existing employees to be updated, and employees to be deactivated.
If the data looks correct, click Import Data to pull the employees into Culture Amp.
After the import is complete, click Go to Users to review the new users.
Important: If you see any unexpected numbers (e.g., too many employees being deactivated or created), do not proceed with the import. Check the Troubleshooting section or reply with "Ask a Person" in a Support Conversation to speak with a Product Support Specialist.
Once these steps are completed, you will see the green "Syncing data" notification appear on the Integrations page.
After syncing is complete, you will see the latest sync information, including the date and time of the last sync, and confirmation that your integration is Connected on the Integrations page.
Set Up Automated Daily Syncs
Set Up Automated Daily Syncs
By default, auto-syncs are Off. We recommend enabling daily syncing to ensure your employee demographics are kept up-to-date.
To enable: Go to Integrations, click on the Off button and toggle Auto-sync On.
To disable: Go to Integrations, click on the On button, then click Turn off auto sync.
Note: Auto-sync won’t run if the Finalise sync step is still displayed. Click Finalise sync to finish setup.
Troubleshooting/FAQs
If the fixes below don't resolve your issue, please remember that the high potential for customization in UKG Pro means complex mapping or sync problems often require a specialist. Please reply with "Ask a Person" in a Support Conversation to speak with a Product Support Specialist.
General Data Integrity & Import Management
The first step when investigating any data issue is to check the Import Summary Screen for your most recent import.
Go to Settings > Employee Data > Import History.
Select your most recent import to view details.
This screen provides information on the state of your integration, any specific errors, or will prompt you to run a manual sync to identify problems.
UKG Pro: Integration-Specific Errors
UKG Pro: Integration-Specific Errors
Issue | Cause | Suggested Fix |
Field Values are Codes (e.g., 'SLS1') | The API is pulling the internal code/ID instead of the label. This is a known limitation for Org Level # = description. | Check Mapping: Currently, the API only returns internal codes for Org Levels. If you require descriptive labels, you may need to manage these specific demographics directly in Culture Amp via manual import. |
Hierarchy Errors | The person listed as the manager in UKG Pro is not imported, or the Manager is incorrectly mapped. | Check your data: Ensure all managers are included in the employee import. Verify that the Manager field (Work Email of referenced Manager from the |
Hierarchy demographic Mismatch | Hierarchy has been validated in Culture Amp previously under a demographic other than Manager Email (e.g., Manager ID from an old CSV import) | Contact Specialist: If you used a different demographic for your hierarchy previously, you may need a custom back-end mapping for your hierarchy demographic to ensure continuity. Reply with "Ask a Person" in a Support Conversation for assistance. |
Missing Data/403 Permission Errors | The UKG Pro Service Account lacks the required Web Service permissions to read specific data objects. | Verify Permissions: Ensure the Service Account has View access for Personnel (Person Details), Employment (Job History / Employment Details), Organization Levels, User-Defined Fields (Other Personal Information), and Web Services Administration.Job History Details. |
Need to Edit/Delete Mappings | Mappings are locked in Culture Amp once set up to protect data integrity. | Contact Support: Reply with "Ask a Person" in a Support Conversation. Be ready to provide the Field Names for the fields you wish to change. |
Switching From CSV or Other Imports
Switching From CSV or Other Imports
If you are moving from CSV uploads or a different integration, keep the following in mind:
Demographic Consistency: When mapping fields, you must map the data to the exact same demographic field you used historically (e.g., mapping to "TEAM" is different from mapping to "TEAM NAME"). Using an incorrect or slightly different title risks discontinuity in your trended survey results.
Recommended Action: To avoid confusion, we recommend navigating to Settings > Employee Data Demographics and deleting the old, unused demographics after your first successful sync. (This won't impact any previous survey results.)
Handling Duplicate Employees
Handling Duplicate Employees
Culture Amp matches employees based on their Email address. If an employee has a different email in Culture Amp than in UKG Pro, duplicate profiles will be created.
Scenario | Action to Take |
A. Before Changes Are Applied | During the first sync review screen, stop the sync. Update the employee emails in Culture Amp to match those in UKG Pro.
|
B. After Changes Are Applied | To clean up the duplicated profiles:
|
Further Guidance | Check out our dedicated support guide for further information on duplicate employee clean-up. |
Sync Blocked to Protect Employee Privacy
Sync Blocked to Protect Employee Privacy
Your automated daily sync might be blocked if Culture Amp detects a high-risk change for an employee. You will receive an email notification if this occurs.
When It Happens: The sync is blocked if a combination of an employee's Name, Date of Birth, or Email is changed simultaneously.
Purpose: This prevents one employee from accidentally getting access to another employee's private information (like performance reviews).
Fix: If you've intentionally changed the employee's details, you can run a manual sync to push the change through. Go to Settings > Employee Data > Users, click Import data, and select Sync. Culture Amp will guide you through the rest.
Redaction of Sensitive Data
Redaction of Sensitive Data
As part of this integration, Culture Amp has the ability to redact sensitive data at your request. If you need any fields to be disabled/redacted for your account, please reply with "Ask a Person" in a Support Conversation to speak with a Product Support Specialist.
💬 Need help? Just reply with "Ask a Person" in a support conversation to speak with a Product Support Specialist.