> For the complete documentation index, see [llms.txt](https://docs.stackai.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.stackai.com/integrations/catalog/ukg-pro.md).

# UKG Pro

Connect to UKG Pro to read HR and payroll data: list employees, look one employee up by employee number or work email, read pay statements for a date range, and read time off requests and their approval status.

## Connectors

Choose the connector that matches your authentication method. The options below use the names shown in StackAI.

| Connector                     | Authentication |
| ----------------------------- | -------------- |
| UKG Pro (HCM)                 | Credentials    |
| UKG Pro (Time and Attendance) | Credentials    |

### UKG Pro (HCM)

Connect to UKG Pro HCM with a web service account to read employees, look one employee up by identifier, and read pay statements. Needs your tenant's base service URL and Customer API key from System Configuration > Security > Web Services. Time off requests live on UKG Pro Time and Attendance and need the separate UKG Pro (Time and Attendance) connection.

#### Set up in UKG Pro

1. Prepare the UKG Pro account or service that the workflow will access. Grant access to the required resources and operations.
2. **UKG Pro base service URL:** Your tenant's UKG Pro base service URL, read from System Configuration > Security > Web Services in UKG Pro. Enter the host on its own, for example 'servicet.ultipro.com'; if you paste the URL with a trailing '/services/' that part is dropped, because UKG's own operation paths disagree about whether they include it.
3. **Web service account user name:** The user name of a UKG Pro web service account, created by a UKG Pro system administrator under System Configuration > Security > Service Account Administration. Give the account View on 'Personnel Integration' to read employees, View and Add on the same service to look an employee up by identifier, and View on 'Employee Pay Statements' to read pay.
4. **Password:** The web service account's password, set when a UKG Pro system administrator created the account. UKG also assigns every web service account a separate user API key; if your tenant authenticates API calls with that key, put it in the 'User API key' field below and it is sent in this field's place.
5. **User API key (optional):** The unique user API key UKG assigns to the web service account; ask the UKG Pro system administrator who created the account for it. UKG's API reference documents the Basic secret as the account password, while UKG's own published UKG Pro HCM connector authenticates with the user name and user API key instead, so both fields exist here. When this is filled it is sent as the Basic password and the Password field is not used.
6. **Customer API key:** Your tenant's Customer API key, from System Configuration > Security > Web Services in UKG Pro. It is sent in the US-CUSTOMER-API-KEY header on every request and identifies the tenant, not the user.

#### Set up in StackAI

1. Open **Settings → Connections**, add a connection, and select **UKG Pro (HCM)**.
2. Enter the credentials and connection details in the fields below.
3. Save the connection and check its connection status. Select this saved connection when configuring an action or feature that uses it.

**Connection fields**

| StackAI field                   | Required                 | What to enter                                                                                                                                                                                                                                                                                                                                                                                                                               |
| ------------------------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| UKG Pro base service URL        | Yes                      | Your tenant's UKG Pro base service URL, read from System Configuration > Security > Web Services in UKG Pro. Enter the host on its own, for example 'servicet.ultipro.com'; if you paste the URL with a trailing '/services/' that part is dropped, because UKG's own operation paths disagree about whether they include it. [Provider instructions](https://developer.ukg.com/hcm/docs/web-service-account).                              |
| Web service account user name   | Yes                      | The user name of a UKG Pro web service account, created by a UKG Pro system administrator under System Configuration > Security > Service Account Administration. Give the account View on 'Personnel Integration' to read employees, View and Add on the same service to look an employee up by identifier, and View on 'Employee Pay Statements' to read pay.                                                                             |
| Password                        | Yes                      | The web service account's password, set when a UKG Pro system administrator created the account. UKG also assigns every web service account a separate user API key; if your tenant authenticates API calls with that key, put it in the 'User API key' field below and it is sent in this field's place.                                                                                                                                   |
| User API key (optional)         | Optional / as applicable | The unique user API key UKG assigns to the web service account; ask the UKG Pro system administrator who created the account for it. UKG's API reference documents the Basic secret as the account password, while UKG's own published UKG Pro HCM connector authenticates with the user name and user API key instead, so both fields exist here. When this is filled it is sent as the Basic password and the Password field is not used. |
| Customer API key                | Yes                      | Your tenant's Customer API key, from System Configuration > Security > Web Services in UKG Pro. It is sent in the US-CUSTOMER-API-KEY header on every request and identifies the tenant, not the user.                                                                                                                                                                                                                                      |
| Primary company code (optional) | Optional / as applicable | Your Pro Customer primary company code, read from System Configuration > Company Setup in UKG Pro, from the value shown for 'Primary Company Code'. UKG requires it on the pay-statements operation, so Get Employee Pay Statements will not run without it; the employee actions do not need it.                                                                                                                                           |

### UKG Pro (Time and Attendance)

Connect to UKG Pro Time and Attendance to read time off requests and their approval status. This is a separate UKG product from UKG Pro HCM, on its own address: use the host shown in your browser while you are signed in to Time and Attendance. If your organisation does not license Time and Attendance, use the UKG Pro (HCM) connection instead; it covers employees and pay.

#### Set up in UKG Pro

1. Prepare the UKG Pro account or service that the workflow will access. Grant access to the required resources and operations.
2. **UKG Pro Time and Attendance URL:** The host you are signed in to when you use UKG Pro Time and Attendance: the server name plus the '.ultiprotime.com' domain from your browser's address bar, for example 'acme.ultiprotime.com'. UKG's API reference points some tenants at the same base service URL as UKG Pro HCM instead, so if the ultiprotime.com host is rejected, try the host from System Configuration > Security > Web Services. Anything after the host is dropped, and the connection always uses https even if you paste http.
3. **Customer API key:** Your tenant's Customer API key, from System Configuration > Security > Web Services in UKG Pro. Sent in the US-CUSTOMER-API-KEY header. It is the same tenant key the UKG Pro HCM connection uses.

#### Set up in StackAI

1. Open **Settings → Connections**, add a connection, and select **UKG Pro (Time and Attendance)**.
2. Enter the credentials and connection details in the fields below.
3. Save the connection and check its connection status. Select this saved connection when configuring an action or feature that uses it.

**Connection fields**

| StackAI field                   | Required | What to enter                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| ------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| UKG Pro Time and Attendance URL | Yes      | The host you are signed in to when you use UKG Pro Time and Attendance: the server name plus the '.ultiprotime.com' domain from your browser's address bar, for example 'acme.ultiprotime.com'. UKG's API reference points some tenants at the same base service URL as UKG Pro HCM instead, so if the ultiprotime.com host is rejected, try the host from System Configuration > Security > Web Services. Anything after the host is dropped, and the connection always uses https even if you paste http. [Provider instructions](https://library.ukg.com/a/207329). |
| User name                       | Yes      | A UKG Pro service account, or a UKG Pro web user with Web Services permissions, that may see the time off requests you want to read. Signing in returns the session this connection then replays.                                                                                                                                                                                                                                                                                                                                                                      |
| Password                        | Yes      | That user's UKG Pro Time and Attendance password.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| Customer API key                | Yes      | Your tenant's Customer API key, from System Configuration > Security > Web Services in UKG Pro. Sent in the US-CUSTOMER-API-KEY header. It is the same tenant key the UKG Pro HCM connection uses.                                                                                                                                                                                                                                                                                                                                                                     |

### Verify the connection

Check that the connection is healthy. Then run a read operation against a resource the connected account can access. A successful connection check confirms authentication; it does not guarantee permission for every action.

If access is denied, check the credential or OAuth permissions, the selected account or environment, and access to the specific resource. Update expired credentials or reconnect after permissions change.

## Use an action

1. Add the required **UKG Pro** action to the workflow.
2. Select a connection when the action requests one.
3. Complete the required fields. Use the reference picker when a value comes from another workflow step.
4. Run the workflow and inspect the action’s output. Check the result before using it in a later step.

## Actions

### Get Employees

List employees from UKG Pro, optionally filtered by company, last name, email or address. Sensitive identifiers (national ID, date of birth, home address) are left out unless you switch them on.

#### Inputs

| Field                                 | Type    | Required | Description                                                                                                                                                                                                                                                                    |
| ------------------------------------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Company ID                            | string  | No       | Limit results to one UKG Pro company. Leave blank to search every company the service account can see.                                                                                                                                                                         |
| Last name                             | string  | No       | Match employees by last name.                                                                                                                                                                                                                                                  |
| Work email                            | string  | No       | Match one employee by their work email address.                                                                                                                                                                                                                                |
| Maximum employees                     | integer | No       | Roughly how many employees to return. The action fetches whole pages, so it can return a few more than this rather than cutting a page in half. Minimum: 1. Maximum: 1000. Default: 50.                                                                                        |
| Employee ID                           | string  | No       | Match one employee by their UKG Pro employee ID (EEID), the internal ID Get Employee returns. This is not the employee number that appears on a payslip.                                                                                                                       |
| State or province                     | string  | No       | Match employees whose home address is in this state or province.                                                                                                                                                                                                               |
| Country                               | string  | No       | Match employees whose home address is in this country.                                                                                                                                                                                                                         |
| Include home address                  | boolean | No       | Off by default. Turn this on if your workflow needs employees' home addresses and phone numbers, for example to post something to them. These values are written into the run history and, for an AI step, sent to the model provider. Default: false.                         |
| Include national ID and date of birth | boolean | No       | Off by default, and the most sensitive switch here. Turn this on only if your workflow genuinely cannot proceed without national identifiers or dates of birth. These values are written into the run history and, for an AI step, sent to the model provider. Default: false. |
| Start at page                         | integer | No       | Resume a previous listing. Paste the 'Next page' value from an earlier run. Minimum: 1.                                                                                                                                                                                        |

#### Outputs

| Field              | Type          | Description                                                                                        |
| ------------------ | ------------- | -------------------------------------------------------------------------------------------------- |
| Employees          | object\_array | The employees found.                                                                               |
| Next page          | integer       | Page number to pass back as 'Start at page' to fetch more employees. Empty when there are no more. |
| Employees returned | integer       | How many employees this call returned.                                                             |

### Get Employee

Look up one employee's employment record in UKG Pro from their employee number, work email or another identifier. Pay rate and salary are left out unless you switch them on.

#### Inputs

| Field                       | Type            | Required | Description                                                                                                                                                                                                                                                                                                                                                                                                                   |
| --------------------------- | --------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Employee identifier         | string          | Yes      | The value that identifies the employee, for example their employee number or work email. Pick the matching type below.                                                                                                                                                                                                                                                                                                        |
| Employee identifier type    | select (string) | Yes      | What kind of identifier you entered above. Prefer Employee number or Work email. National ID, SSN and SIN are accepted by UKG but are stored with the workflow, so avoid them unless nothing else identifies the employee. Available values: Employee number, Work email, UKG employee ID, UKG person ID, Integration key, National ID, Social insurance number (SIN), Social security number (SSN). Default: EmployeeNumber. |
| Company                     | string          | No       | Narrow the lookup to one company. Needed when the employee exists in more than one of your UKG Pro companies and you do not want their home company.                                                                                                                                                                                                                                                                          |
| Company identifier type     | select (string) | No       | What kind of company value you entered above. Company code is the code you see in UKG Pro; pick Company ID only if you pasted an internal ID from another UKG Pro step. Available values: Company code, Company ID, Federal ID. Default: Company Code.                                                                                                                                                                        |
| Include salary and pay rate | boolean         | No       | Off by default. Turn this on only if your workflow needs the employee's annual salary or hourly pay rate. It makes one extra call to UKG, and these values are written into the run history and, for an AI step, sent to the model provider. Your web service account needs View on the 'Employee Compensation Details' Web Service; without it the employee still comes back, just with no pay. Default: false.              |

#### Outputs

| Field       | Type   | Description                                             |
| ----------- | ------ | ------------------------------------------------------- |
| Employee    | object | The employee's employment record.                       |
| Employee ID | string | UKG Pro's internal employee ID for this person.         |
| Company ID  | string | UKG Pro's internal company ID the record was read from. |
| Supervisor  | string | The employee's supervisor, where UKG records one.       |

### Get Employee Pay Statements

Get an employee's pay statements from UKG Pro payroll for a date range: gross and net pay, earnings and deductions per statement.

#### Inputs

| Field                    | Type            | Required | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| ------------------------ | --------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Employee identifier      | string          | Yes      | The value that identifies the employee, for example their employee number or work email. Pick the matching type below.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| Employee identifier type | select (string) | Yes      | What kind of identifier you entered above. Employee number plus a company code below is the only combination that reads pay in a single call, and the only one that works if your web service account has View but not Add on Personnel Integration. National ID, SSN and SIN are accepted by UKG but are stored with the workflow and echoed back on the statement, so avoid them unless nothing else identifies the employee. Available values: Employee number, Work email, UKG employee ID, UKG person ID, Integration key, National ID, Social insurance number (SIN), Social security number (SSN). Default: EmployeeNumber. |
| From date                | date            | Yes      | Earliest pay date to include.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| To date                  | date            | Yes      | Latest pay date to include.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| Maximum pay statements   | integer         | No       | Roughly how many pay statements to return. The action fetches whole pages, so it can return a few more than this rather than cutting a page in half. Minimum: 1. Maximum: 500. Default: 25.                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| Company                  | string          | No       | The company to read pay statements from. Enter the company code whenever you can: employee number plus company code reads pay in one call. It is also needed when the employee has worked in more than one of your UKG Pro companies and you do not want their home company.                                                                                                                                                                                                                                                                                                                                                       |
| Company identifier type  | select (string) | No       | What kind of company value you entered above. Company code is the code you see in UKG Pro; pick Company ID only if you pasted an internal ID from another UKG Pro step. Available values: Company code, Company ID, Federal ID. Default: Company Code.                                                                                                                                                                                                                                                                                                                                                                             |
| Start at page            | integer         | No       | Resume a previous listing. Paste the 'Next page' value from an earlier run. Minimum: 1.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |

#### Outputs

| Field                   | Type          | Description                                                                                             |
| ----------------------- | ------------- | ------------------------------------------------------------------------------------------------------- |
| Pay statements          | object\_array | The pay statements in the date range.                                                                   |
| Next page               | integer       | Page number to pass back as 'Start at page' to fetch more pay statements. Empty when there are no more. |
| Pay statements returned | integer       | How many pay statements this call returned.                                                             |
| Employee ID             | string        | The employee identifier the statements were read for.                                                   |

### Get Time Off Requests

List time off requests and their approval status from UKG Pro Time and Attendance for a date range. Needs a UKG Pro Time and Attendance connection, which is a separate product from UKG Pro HCM.

#### Inputs

| Field              | Type     | Required | Description                                                                                                                                                                                                |
| ------------------ | -------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| From date and time | datetime | Yes      | Start of the window to list requests for.                                                                                                                                                                  |
| To date and time   | datetime | Yes      | End of the window to list requests for.                                                                                                                                                                    |
| Employee name      | string   | No       | Limit results to one employee by name.                                                                                                                                                                     |
| Employee ID        | string   | No       | Limit results to one employee by their Time and Attendance employee ID (digits only). This is not the same as the Employee ID that Get Employee returns from UKG Pro HCM, so do not paste that value here. |

#### Outputs

| Field                    | Type          | Description                                                |
| ------------------------ | ------------- | ---------------------------------------------------------- |
| Time off requests        | object\_array | The time off requests found in the window.                 |
| Requests returned        | integer       | How many time off requests this call returned.             |
| Requests reported by UKG | integer       | The total UKG reported for this window, when it sends one. |

## Important behavior

Actions that create, update, send, or delete data can change the connected service. Review their inputs before running them. A retry can repeat an operation; consider this when configuring retries for actions that change data.

The catalog lists the fields and capabilities available in the supplied provider definition. Availability can also depend on your deployment and organization’s Feature Access settings.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.stackai.com/integrations/catalog/ukg-pro.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
