> ## Documentation Index > Fetch the complete documentation index at: https://docs.stackone.com/llms.txt > Use this file to discover all available pages before exploring further. # Connect UKG Pro with Service Account - SOAP – StackOne Hub > Link a UKG Pro account in the StackOne Hub using Service Account - SOAP. End-user guide to authorize the integration and start using UKG Pro actions. Ensure you have Admin privileges in UKG Pro to create Service Accounts and access Web Services configuration.
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

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.

Sign in to your UKG Pro account with administrator credentials.

Go to Sidebar Menu > System Configuration > Security > Service Account Administration.

Click the Add button to create a new service account.

  • Username: Enter a descriptive name (e.g., StackOneIntegration)
  • E-mail: Add a valid email

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.
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
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

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.

Go to Sidebar Menu > System Configuration > Security > Service Account Administration.

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).

Go to Sidebar Menu > System Configuration > Security > Service Account Administration.

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.

Go to Sidebar Menu > System Configuration > Security > Web Services.

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.

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

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

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

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

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

Use one of the three Linking Account Methods to access the Hub. 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
  • 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.