Skip to main content
Select Actions to adjust the guide
Some actions may require additional configuration in the provider to be accessible. Choose the actions you need and the guide will be updated.
Action
Scope(s)
Loading actions…
Dynamic Guide URL
Scopes Selected
Separator
Ensure you have Admin privileges in UKG Pro to create Service Accounts and access Web Services configuration.


​
Create a Service Account
A Service Account is required to authenticate SOAP API requests to UKG Pro. Service Accounts are recommended over Web Users for API integrations.
1
Log in to UKG Pro
Sign in to your UKG Pro account with administrator credentials.
2
Navigate to Service Account Administration
Go to Sidebar Menu > System Configuration > Security > Service Account Administration.
3
Create a new Service Account
Click the Add button to create a new service account.
  • Username: Enter a descriptive name (e.g., StackOneIntegration)
  • E-mail: Add a valid email
4
Configure Web Service Permissions
During new service account creation, enable the required permissions based on your integration needs.
Each permission maps to specific SOAP API capabilities. The following steps show which permissions are needed for different features.
5
Enable Employee Data Permissions
Enables actions: Find Contacts, Find Jobs, Find People, Find User Defined Fields, Get Contact By Employee Identifier, Get Employee Contact By Contact ID, Get Job By Employee Identifier, Get Person By Employee Identifier, Get Person Details, Get User Defined Fields By Employee Identifier, List Person Details
Enable these permissions to access employee data, profiles, contacts, job details, and custom fields via SOAP services.
  • Employee Person Details (View) - Personal information and employee profiles
  • Employee Job Details (View) - Job titles, departments, positions, and employment information
  • Employee Contacts (View) - Emergency contacts, dependents, and beneficiary information
  • Employee User Defined Fields (View) - Retrieve custom fields configured for employee records
6
Enable Compensation Permissions
Enables actions: Find Compensations, Get Compensation By Employee Identifier, Get Compensation Details By Employee, List Compensation Details
Enable this permission to access salary, pay rates, and compensation data via SOAP services.
  • Employee Compensation Details (View) - Salary, pay rates, and compensation data
7
Save and record credentials
Click Save. The system will generate a password and User API Key for the service account.
  • ⚠️ Important: Copy and securely store the generated password immediately. It will only be displayed once.
  • ⚠️ Important: Record the User API Key that appears in the grid next to your username. This is required for SOAP authentication.
  • If you lose the password, you’ll need to reset it from the Service Account Administration page.


​
Find Your Customer API Key
The Customer API Key is required for all SOAP API authentication.
1
Navigate to Service Account page
Go to Sidebar Menu > System Configuration > Security > Service Account Administration.
2
Locate the Customer API Key
The Customer API Key is displayed at the top of the Service Account Administration page.
  • The API Key is typically a short alphanumeric string (often uppercase)
  • Example format: VWUIA or similar
  • Copy this value for use in the integration setup


​
Find Your User API Key
The User API Key is specific to each Service Account and is required for SOAP authentication (not needed for REST APIs).
1
Navigate to Service Account Administration
Go to Sidebar Menu > System Configuration > Security > Service Account Administration.
2
Locate the User API Key
The User API Key will be visible on the grid corresponding to the created username at the Service Account Administration page.
  • The User API Key appears to the right of the service account username in the list
  • This key is automatically generated when the service account is created
  • ⚠️ Note: This is different from the Customer API Key and is specific to your service account
  • Copy this value for use in the SOAP authentication setup


​
Find Your Web Services Domain
You need to identify your UKG Pro Web Services domain and subdomain.
1
Navigate to Web Services
Go to Sidebar Menu > System Configuration > Security > Web Services.
2
Identify the domain from any endpoint
Look at any Web Services endpoint URL displayed on the page.
  • Example URL: https://service2.ultipro.com/services/...
  • Web Service Domain: ultipro.com (the main domain)
  • Web Service Subdomain: service2 (the subdomain prefix)


​
Troubleshooting
Common issues and how to resolve them.
1
Error: 401 Unauthorised
This error indicates authentication failure.
  • Check all 4 credentials (username, password, Customer API Key, User API Key)
  • Verify the Service Account username is correct (case-sensitive)
  • Confirm the password is correct
  • Ensure the Customer API Key is correct
  • Verify the User API Key matches the service account
  • Ensure the Service Account status is Active
2
Error: 403 Forbidden
This error indicates the Service Account lacks required permissions.
  • Verify permissions on Service Account Administration page
  • Go to Service Account Administration
  • Edit the Service Account
  • Enable the required SOAP web service permissions
  • Save and retry the connection
3
Error: Invalid User API Key
This error indicates the User API Key is incorrect or missing.
  • Verify key from Service Account Administration page
  • Check that the User API Key corresponds to the correct service account username
  • Ensure you’re not using the Customer API Key in place of the User API Key
  • These are two different keys with different purposes
4
Error: Connection timeout or host not found
This error indicates incorrect domain configuration.
  • Check domain/subdomain configuration
  • Double-check the Web Service Domain (e.g., ultipro.com)
  • Verify the Web Service Subdomain (e.g., service2)
  • Ensure your network allows outbound HTTPS connections to UKG Pro
5
Service Account password expired
Service Account passwords may expire based on your organisation’s security policies.
  • Go to Service Account Administration
  • Select the Service Account
  • Click Reset Password
  • Update the password in your StackOne connection


​
Linking the Account from the Hub
1
Navigate to the Hub
Use one of the three Linking Account Methods to access the Hub.
2
Fill out the fields
Fill out the following fields using details from your provider:
  • UKG Pro Service Account User name
  • UKG Pro Service Account Password
  • UKG Pro Customer API Key (ClientAccessKey)
  • UKG Pro User API Key (UserAccessKey)
  • UKG Pro Web Service domain
  • UKG Pro Web Service subdomain
3
Connect
  • Click Connect
  • If applicable, the provider will redirect you to a sign-in or authorization page. Complete the provider’s authorization flow.
  • Once authorization is successful, you will see a confirmation popup
If the account linking is successful, you will see the newly linked account in your Accounts page.