---
availability: INSTALLABLE
description: Enables employees to check their PTO balances across limited leave types, so they can plan time off quickly and confidently.
name: Check PTO Balance
installation_asset_uuid: 7eb48245-5ae2-467d-a82c-a565f1317d8f
purple_chat_link: https://marketplace.moveworks.com/purple-chat?conversation=%7B%22messages%22%3A%5B%7B%22role%22%3A%22user%22%2C%22parts%22%3A%5B%7B%22richText%22%3A%22I+want+to+view+my+PTO+balances%22%7D%5D%7D%2C%7B%22role%22%3A%22assistant%22%2C%22parts%22%3A%5B%7B%22reasoningSteps%22%3A%5B%7B%22status%22%3A%22success%22%2C%22richText%22%3A%22%3Cp%3ERetrieving+current+leave+balances+for+%3Cb%3EAlex+Rivera%3C%2Fb%3E+from+%3Cb%3EUKG%3C%2Fb%3E...%3C%2Fp%3E%22%2C%22connectorName%22%3A%22ukg%22%7D%5D%7D%2C%7B%22richText%22%3A%22%3Cp%3EYou+have+an+aggregated+balance+of+%3Cb%3E124+hours%3C%2Fb%3E+available+across+all+leave+types%3A%3C%2Fp%3E%3Cul%3E%3Cli%3E%3Cb%3EVacation%3A%3C%2Fb%3E+80+hours%3C%2Fli%3E%3Cli%3E%3Cb%3ESick+Leave%3A%3C%2Fb%3E+32+hours%3C%2Fli%3E%3Cli%3E%3Cb%3EPersonal+Time%3A%3C%2Fb%3E+12+hours%3C%2Fli%3E%3C%2Ful%3E%22%7D%2C%7B%22citations%22%3A%5B%7B%22connectorName%22%3A%22ukg%22%2C%22citationTitle%22%3A%22Alex+Rivera+-+UKG+WFM+Time+Off%22%7D%5D%7D%5D%7D%2C%7B%22role%22%3A%22user%22%2C%22parts%22%3A%5B%7B%22richText%22%3A%22%3Cp%3EWhat+will+be+my+vacation+balance+as+of+Dec+31%3F+I+am+planning+to+take+a+long+vacation+this+new+year%3C%2Fp%3E%22%7D%5D%7D%2C%7B%22role%22%3A%22assistant%22%2C%22parts%22%3A%5B%7B%22reasoningSteps%22%3A%5B%7B%22status%22%3A%22success%22%2C%22richText%22%3A%22%3Cp%3ECalculating+projected+accruals+through+December+31%2C+2024+in+%3Cb%3EUKG%3C%2Fb%3E...%3C%2Fp%3E%22%2C%22connectorName%22%3A%22ukg%22%7D%5D%7D%2C%7B%22richText%22%3A%22%3Cp%3EAs+of+December+31%2C+2024%2C+your+%3Cb%3EVacation%3C%2Fb%3E+balance+is+projected+to+be+%3Cb%3E104+hours%3C%2Fb%3E.%3C%2Fp%3E%3Cp%3EThis+includes+your+current+balance+of+80+hours+plus+24+hours+of+projected+accruals%2C+assuming+no+additional+time+is+taken+before+then.%3C%2Fp%3E%22%7D%5D%7D%5D%7D
solution_tags:
- HR - Other
- HR - Time & Absence
systems:
- ukg-pro-wfm
---
# Description
Enables employees to check their PTO balances across limited leave types, so they can plan time off quickly and confidently.
# User Experience Preview
Please refer to the following [**Purple Chat**](https://marketplace.moveworks.com/purple-chat?conversation=%7B%22messages%22%3A%5B%7B%22role%22%3A%22user%22%2C%22parts%22%3A%5B%7B%22richText%22%3A%22I+want+to+view+my+PTO+balances%22%7D%5D%7D%2C%7B%22role%22%3A%22assistant%22%2C%22parts%22%3A%5B%7B%22reasoningSteps%22%3A%5B%7B%22status%22%3A%22success%22%2C%22richText%22%3A%22%3Cp%3ERetrieving+current+leave+balances+for+%3Cb%3EAlex+Rivera%3C%2Fb%3E+from+%3Cb%3EUKG%3C%2Fb%3E...%3C%2Fp%3E%22%2C%22connectorName%22%3A%22ukg%22%7D%5D%7D%2C%7B%22richText%22%3A%22%3Cp%3EYou+have+an+aggregated+balance+of+%3Cb%3E124+hours%3C%2Fb%3E+available+across+all+leave+types%3A%3C%2Fp%3E%3Cul%3E%3Cli%3E%3Cb%3EVacation%3A%3C%2Fb%3E+80+hours%3C%2Fli%3E%3Cli%3E%3Cb%3ESick+Leave%3A%3C%2Fb%3E+32+hours%3C%2Fli%3E%3Cli%3E%3Cb%3EPersonal+Time%3A%3C%2Fb%3E+12+hours%3C%2Fli%3E%3C%2Ful%3E%22%7D%2C%7B%22citations%22%3A%5B%7B%22connectorName%22%3A%22ukg%22%2C%22citationTitle%22%3A%22Alex+Rivera+-+UKG+WFM+Time+Off%22%7D%5D%7D%5D%7D%2C%7B%22role%22%3A%22user%22%2C%22parts%22%3A%5B%7B%22richText%22%3A%22%3Cp%3EWhat+will+be+my+vacation+balance+as+of+Dec+31%3F+I+am+planning+to+take+a+long+vacation+this+new+year%3C%2Fp%3E%22%7D%5D%7D%2C%7B%22role%22%3A%22assistant%22%2C%22parts%22%3A%5B%7B%22reasoningSteps%22%3A%5B%7B%22status%22%3A%22success%22%2C%22richText%22%3A%22%3Cp%3ECalculating+projected+accruals+through+December+31%2C+2024+in+%3Cb%3EUKG%3C%2Fb%3E...%3C%2Fp%3E%22%2C%22connectorName%22%3A%22ukg%22%7D%5D%7D%2C%7B%22richText%22%3A%22%3Cp%3EAs+of+December+31%2C+2024%2C+your+%3Cb%3EVacation%3C%2Fb%3E+balance+is+projected+to+be+%3Cb%3E104+hours%3C%2Fb%3E.%3C%2Fp%3E%3Cp%3EThis+includes+your+current+balance+of+80+hours+plus+24+hours+of+projected+accruals%2C+assuming+no+additional+time+is+taken+before+then.%3C%2Fp%3E%22%7D%5D%7D%5D%7D) for a sample conversational experience between a user and the AI Assistant for this plugin.
# Pre-requisites
Before installing and using the **Check PTO Balance** plugin, please ensure the following requirements are met:
## **1. UKG Connector**
This plugin requires an active **UKG connector** and **user consent auth** to communicate with your UKG instance.
- If you have not already configured the connector, please follow the [**UKG Connector Guide](https://marketplace.moveworks.com/connectors/ukg-pro-wfm)** available in the Moveworks Marketplace.
- The connector must be fully set up before installing this plugin.
- Once the connector is successfully configured, follow our [**plugin installation documentation**](https://help.moveworks.com/docs/ai-agent-marketplace-installation) for detailed steps on how to install and activate the plugin in **Agent Studio**.
**Note:** UKG’s user-consent authorization expires every 24 hours, requiring users to reauthorize once per day. This is a known limitation, and support for handling such short-lived refresh tokens is being built on Moveworks.
## **2. UKG System Requirements**
### **End User Permissions (Employee Persona)**
To look up PTO balance through this plugin, employees must already have permission to check PTO Balance in UKG — the same permissions required to check PTO balance through the UKG UI.
At a minimum, end users must have:
- **Time Off permissions** that allow:
- Viewing available Time Off Types
- Access to their own **employee profile and time account balances**
**Note**: The plugin does not grant new permissions. It respects existing role-based permissions and policies granted to the user in UKG.
# **Implementation details**
## Visual Representation of How the Plugin Works
## API Details
Before running the cURL examples below, replace `<YOUR_UKG_HOST>` with your actual UKG hostname.
**Admin Checklist: How to Find Your UKG Hostname**
1. Log in to your UKG account.
2. Check the URL in your browser’s address bar.
3. Your hostname will follow this format:
Examples:
- `https://acme-dev.cfn.mykronos.com`
- `https://acme-test.cfn.mykronos.com`
- `https://acme-uat.cfn.mykronos.com`
- `https://acme-prod.cfn.mykronos.com`
Use the full hostname (e.g., `acme-prod.cfn.mykronos.com`) when replacing `<YOUR_UKG_HOST>` in the cURL commands.
### **API #1: Get a User’s UKG ID based on their Email**
This API is used to fetch employee details (such as **User ID, name, and email**) from UKG using the employee’s email address. The returned **User ID** is required for fetching the PTO Balance API call.
```bash
curl --request POST \
--url https://<YOUR_UKG_HOST>/api/v1/commons/persons/extensions/multi_read \
--header 'Authorization: {{access_token}}' \
--header 'Content-Type: application/json' \
--data '{
"where": {
"employees": {
"key": "useremailaddress",
"values": [
"{{USER_EMAIL}}"
]
},
"includeBaseWages": false,
"includeAccrualPolicyDetails": false
}
}'
```
**Query Parameters:**
- `USER_EMAIL` *(string):* Email address of the logged in employee.
### **API #2: Retrieve Available PTO Sub Types**
This REST API is used to retrieve the list of time-off types available to an employee as of a specific date. The API returns only limited leave types.
```bash
curl --request GET \
--url 'https://<YOUR_UKG_HOST>/api/v1/scheduling/timeoff/request_subtypes?person_number={{USER_NUMBER}}' \
--header 'Authorization: {{access_token}}' \
--header 'Content-Type: application/json'
```
**Query Parameters:**
- `USER_NUMBER` *(string):* This will be the UKG person number fetched from API #1.
### **API #3: Retrieve Accrual Codes from Paycodes**
This REST API is used to retrieve **accrual code mappings** for leave paycodes in UKG. It helps determine which paycodes have valid accrual buckets associated with them and filters out non-accrual paycodes (e.g., "Overtime Payout", "EmergencyPaidSick") before attempting to fetch balances.
```bash
curl --request POST \
--url 'https://<YOUR_UKG_HOST>/api/v1/timekeeping/paycodes_to_accrual_codes/multi_read' \
--header 'Authorization: Bearer {{access_token}}' \
--header 'Content-Type: application/json' \
--data '{
"timeframe_id": "Current_Payperiod",
"paycodes": {{{paycodes_payload}}},
"employee": {
"qualifier": "{{person_number}}"
}
}'
```
**Body Parameters:**
- `TIMEFRAME_ID` (string): This specifies the timeframe for which accrual mappings should be evaluated. It is typically set to "Current_Payperiod".
- `PAYCODES_PAYLOAD` (array): A dynamically generated JSON array containing paycode qualifiers extracted from the subtypes API (e.g., [{"qualifier": "Vacation"}, {"qualifier": "Sick"}]).
- `PERSON_NUMBER` (string): The unique alphanumeric person number of the employee (e.g., "M140031").
### **API #4: Retrieve PTO Balance**
This API is used to **retrieve PTO balance on behalf of an employee** in UKG based on date, leave sub type and Person Number of the Employee.
```bash
curl --request GET \
--url 'https://<YOUR_UKG_HOST>/api/v1/scheduling/timeoff/accruals?date={{date}}&subtype_name={{subtype_name}}&employee_id={{user_id}}' \
--header 'Authorization: {{access_token}}' \
--header 'Content-Type: application/json'
```
**Query Parameters:**
- `DATE` *(string):* This will be the date leave balances accruals will be calculated. If user has not specified a date, it is defaulted to current date.
- `SUBTYPE_NAME` *(string):* This will be the leave type name (e.g., “Time Off”).
- `USER_ID` *(string):* This will be UKG person number fetched from API #1.
**Key nuances:**
- Checking balances for all subtypes.
- If needed, perform a loop and get the balance of all subtypes.
### API References
This plugin use **UKG WFM Pro Time Management REST APIs** to retrieve employee information, determine eligible PTO time types, and check PTO balance.
For detailed information on request parameters, response formats, error handling, and versioning, please refer to the [**official UKG API documentation**](https://developer.ukg.com/wfm/reference/welcome-to-the-ukg-pro-workforce-management-api) provided by UKG.
# **What Is In Scope for This Plugin?**
This plugin supports the following capabilities:
- Balance check for **limited leave types** (e.g., Vacation, Sick Leave, Casual Leave, Earned Leave, Comp Time).
- Check PTO Balance “**as of**” a specific date in the **past or a future date.**
# **What Is Out of Scope for This Plugin?**
This plugin does **not** support the following:
- Checking PTO balance **on behalf of another employee**, including direct reports.
- Balance check for **non-limited or leave-of-absence types**, such as parental leave, FMLA, or long-term disability.
- Viewing accrual schedules, expiry dates and carry over details of the available leave types.
- Proactively surfacing **public holidays, and/ or weekends.**
- Submission of PTO requests.