--- availability: INSTALLABLE description: Enables managers and employees to view PTO requests and team calendars, including pending requests, scheduled time off, and past leave history for better planning and visibility. name: View PTO Requests & Calendar installation_asset_uuid: 484fe8d7-9fb1-45ae-97da-944e9d802c02 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%22Show+my+PTO%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%3EValidating+employee+identity...%3C%2Fp%3E%22%2C%22connectorName%22%3A%22ukg%22%7D%2C%7B%22status%22%3A%22success%22%2C%22richText%22%3A%22%3Cp%3ERetrieving+personal+time+off+requests...%3C%2Fp%3E%22%2C%22connectorName%22%3A%22ukg%22%7D%5D%7D%2C%7B%22richText%22%3A%22%3Cp%3EI+found+3+time+off+requests+for+you+in+%3Cstrong%3EUKG+WFM%3C%2Fstrong%3E%3A%3C%2Fp%3E%3Cul%3E%3Cli%3E%3Cp%3E%3Cstrong%3EPTO-942%3C%2Fstrong%3E+%7C+Vacation+%7C+Oct+12+-+Oct+14%2C+2024+%7C+Family+trip+%28Approved%29%3C%2Fp%3E%3C%2Fli%3E%3Cli%3E%3Cp%3E%3Cstrong%3EPTO-955%3C%2Fstrong%3E+%7C+Personal+%7C+Nov+05%2C+2024+%7C+Appointment+%28Pending%29%3C%2Fp%3E%3C%2Fli%3E%3Cli%3E%3Cp%3E%3Cstrong%3EPTO-981%3C%2Fstrong%3E+%7C+Sick+Leave+%7C+Dec+02+-+Dec+03%2C+2024+%7C+Recovery+%28Pending%29%3C%2Fp%3E%3C%2Fli%3E%3C%2Ful%3E%22%7D%5D%7D%2C%7B%22role%22%3A%22user%22%2C%22parts%22%3A%5B%7B%22richText%22%3A%22I%27d+like+to+see+more+details+on+%3Cb%3EPTO-955%3C%2Fb%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%3EFetching+detailed+record+for+%3Cb%3EPTO-955%3C%2Fb%3E+from+%3Cb%3EUKG+WFM%3C%2Fb%3E...%3C%2Fp%3E%22%2C%22connectorName%22%3A%22ukg%22%7D%5D%7D%2C%7B%22richText%22%3A%22%3Cp%3EHere+are+the+details+for+your+request+%3Cstrong%3EPTO-955%3C%2Fstrong%3E%3A%3C%2Fp%3E%3Cul%3E%3Cli%3E%3Cstrong%3EType%3A%3C%2Fstrong%3E+Personal+Time+Off%3C%2Fli%3E%3Cli%3E%3Cstrong%3EStatus%3A%3C%2Fstrong%3E+Pending+Approval%3C%2Fli%3E%3Cli%3E%3Cstrong%3EDate%3A%3C%2Fstrong%3E+November+5%2C+2024+%28Full+Day%29%3C%2Fli%3E%3Cli%3E%3Cstrong%3ETotal+Hours%3A%3C%2Fstrong%3E+8.0%3C%2Fli%3E%3Cli%3E%3Cstrong%3EComment%3A%3C%2Fstrong%3E+%5C%22Dentist+appointment+in+the+morning%5C%22%3C%2Fli%3E%3Cli%3E%3Cstrong%3EApprover%3A%3C%2Fstrong%3E+Sarah+Jenkins%3C%2Fli%3E%3C%2Ful%3E%22%7D%5D%7D%2C%7B%22role%22%3A%22user%22%2C%22parts%22%3A%5B%7B%22richText%22%3A%22Can+you+show+me+any+pending+PTO+requests+for+my+team%3F%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%3EVerifying+manager+permissions...%3C%2Fp%3E%22%2C%22connectorName%22%3A%22ukg%22%7D%2C%7B%22status%22%3A%22success%22%2C%22richText%22%3A%22%3Cp%3EFetching+pending+requests+for+direct+reports+from+%3Cb%3EUKG+WFM%3C%2Fb%3E...%3C%2Fp%3E%22%2C%22connectorName%22%3A%22ukg%22%7D%5D%7D%2C%7B%22richText%22%3A%22%3Cp%3EHere+are+the+5+pending+requests+for+your+team+in+%3Cstrong%3EUKG+WFM%3C%2Fstrong%3E%3A%3C%2Fp%3E%3Cul%3E%3Cli%3E%3Cp%3E%3Cstrong%3EPTO-101%3C%2Fstrong%3E+%7C+%3Cb%3EJordan+Smith%3C%2Fb%3E+%7C+Vacation+%7C+Oct+08+-+Oct+10%2C+2024+%7C+Camping+trip%3C%2Fp%3E%3C%2Fli%3E%3Cli%3E%3Cp%3E%3Cstrong%3EPTO-102%3C%2Fstrong%3E+%7C+%3Cb%3EElena+Rodriguez%3C%2Fb%3E+%7C+Personal+%7C+Oct+12%2C+2024+%7C+Moving+day%3C%2Fp%3E%3C%2Fli%3E%3Cli%3E%3Cp%3E%3Cstrong%3EPTO-103%3C%2Fstrong%3E+%7C+%3Cb%3EMarcus+Chen%3C%2Fb%3E+%7C+Vacation+%7C+Oct+14+-+Oct+15%2C+2024+%7C+Short+break%3C%2Fp%3E%3C%2Fli%3E%3Cli%3E%3Cp%3E%3Cstrong%3EPTO-104%3C%2Fstrong%3E+%7C+%3Cb%3ESarah+Miller%3C%2Fb%3E+%7C+Vacation+%7C+Oct+25+-+Oct+27%2C+2024+%7C+Visit+parents%3C%2Fp%3E%3C%2Fli%3E%3Cli%3E%3Cp%3E%3Cstrong%3EPTO-105%3C%2Fstrong%3E+%7C+%3Cb%3EDavid+Wilson%3C%2Fb%3E+%7C+Sick+Leave+%7C+Nov+02%2C+2024+%7C+Minor+surgery%3C%2Fp%3E%3C%2Fli%3E%3C%2Ful%3E%22%7D%2C%7B%22citations%22%3A%5B%7B%22connectorName%22%3A%22ukg%22%2C%22citationTitle%22%3A%22PTO-101%22%7D%2C%7B%22connectorName%22%3A%22ukg%22%2C%22citationTitle%22%3A%22PTO-102%22%7D%2C%7B%22connectorName%22%3A%22ukg%22%2C%22citationTitle%22%3A%22PTO-103%22%7D%2C%7B%22connectorName%22%3A%22ukg%22%2C%22citationTitle%22%3A%22PTO-104%22%7D%2C%7B%22connectorName%22%3A%22ukg%22%2C%22citationTitle%22%3A%22PTO-105%22%7D%5D%7D%5D%7D%2C%7B%22role%22%3A%22user%22%2C%22parts%22%3A%5B%7B%22richText%22%3A%22Can+you+show+me+upcoming+approved+PTO+for+my+team%3F%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%3EVerifying+manager+permissions+for+team+calendar...%3C%2Fp%3E%22%2C%22connectorName%22%3A%22ukg%22%7D%2C%7B%22status%22%3A%22success%22%2C%22richText%22%3A%22%3Cp%3EFiltering+approved+requests+for+the+next+90+days+in+%3Cb%3EUKG+WFM%3C%2Fb%3E...%3C%2Fp%3E%22%2C%22connectorName%22%3A%22ukg%22%7D%5D%7D%2C%7B%22richText%22%3A%22%3Cp%3EI+found+7+upcoming+approved+requests+for+your+team+over+the+next+3+months%3A%3C%2Fp%3E%3Cul%3E%3Cli%3E%3Cp%3E%3Cstrong%3EPTO-201%3C%2Fstrong%3E+%7C+%3Cb%3EJordan+Smith%3C%2Fb%3E+%7C+Vacation+%7C+Oct+05+-+Oct+06%2C+2024+%7C+Weekend+trip%3C%2Fp%3E%3C%2Fli%3E%3Cli%3E%3Cp%3E%3Cstrong%3EPTO-202%3C%2Fstrong%3E+%7C+%3Cb%3EElena+Rodriguez%3C%2Fb%3E+%7C+Vacation+%7C+Oct+15+-+Oct+18%2C+2024+%7C+Hiking%3C%2Fp%3E%3C%2Fli%3E%3Cli%3E%3Cp%3E%3Cstrong%3EPTO-203%3C%2Fstrong%3E+%7C+%3Cb%3EDavid+Wilson%3C%2Fb%3E+%7C+Vacation+%7C+Oct+28%2C+2024+%7C+Birthday%3C%2Fp%3E%3C%2Fli%3E%3Cli%3E%3Cp%3E%3Cstrong%3EPTO-204%3C%2Fstrong%3E+%7C+%3Cb%3EMarcus+Chen%3C%2Fb%3E+%7C+Vacation+%7C+Nov+10+-+Nov+12%2C+2024+%7C+City+break%3C%2Fp%3E%3C%2Fli%3E%3Cli%3E%3Cp%3E%3Cstrong%3EPTO-205%3C%2Fstrong%3E+%7C+%3Cb%3ESarah+Miller%3C%2Fb%3E+%7C+Vacation+%7C+Nov+22+-+Nov+24%2C+2024+%7C+Thanksgiving%3C%2Fp%3E%3C%2Fli%3E%3Cli%3E%3Cp%3E%3Cstrong%3EPTO-206%3C%2Fstrong%3E+%7C+%3Cb%3EJordan+Smith%3C%2Fb%3E+%7C+Vacation+%7C+Dec+05+-+Dec+08%2C+2024+%7C+Ski+trip%3C%2Fp%3E%3C%2Fli%3E%3Cli%3E%3Cp%3E%3Cstrong%3EPTO-207%3C%2Fstrong%3E+%7C+%3Cb%3EElena+Rodriguez%3C%2Fb%3E+%7C+Vacation+%7C+Dec+24+-+Dec+26%2C+2024+%7C+Holidays%3C%2Fp%3E%3C%2Fli%3E%3C%2Ful%3E%22%7D%5D%7D%5D%7D solution_tags: - HR - Other - HR - Time & Absence systems: - ukg-pro-wfm --- # Description Enables managers and employees to view PTO requests and team calendars, including pending requests, scheduled time off, and past leave history for better planning and visibility. # 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%22Show+my+PTO%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%3EValidating+employee+identity...%3C%2Fp%3E%22%2C%22connectorName%22%3A%22ukg%22%7D%2C%7B%22status%22%3A%22success%22%2C%22richText%22%3A%22%3Cp%3ERetrieving+personal+time+off+requests...%3C%2Fp%3E%22%2C%22connectorName%22%3A%22ukg%22%7D%5D%7D%2C%7B%22richText%22%3A%22%3Cp%3EI+found+3+time+off+requests+for+you+in+%3Cstrong%3EUKG+WFM%3C%2Fstrong%3E%3A%3C%2Fp%3E%3Cul%3E%3Cli%3E%3Cp%3E%3Cstrong%3EPTO-942%3C%2Fstrong%3E+%7C+Vacation+%7C+Oct+12+-+Oct+14%2C+2024+%7C+Family+trip+%28Approved%29%3C%2Fp%3E%3C%2Fli%3E%3Cli%3E%3Cp%3E%3Cstrong%3EPTO-955%3C%2Fstrong%3E+%7C+Personal+%7C+Nov+05%2C+2024+%7C+Appointment+%28Pending%29%3C%2Fp%3E%3C%2Fli%3E%3Cli%3E%3Cp%3E%3Cstrong%3EPTO-981%3C%2Fstrong%3E+%7C+Sick+Leave+%7C+Dec+02+-+Dec+03%2C+2024+%7C+Recovery+%28Pending%29%3C%2Fp%3E%3C%2Fli%3E%3C%2Ful%3E%22%7D%5D%7D%2C%7B%22role%22%3A%22user%22%2C%22parts%22%3A%5B%7B%22richText%22%3A%22I%27d+like+to+see+more+details+on+%3Cb%3EPTO-955%3C%2Fb%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%3EFetching+detailed+record+for+%3Cb%3EPTO-955%3C%2Fb%3E+from+%3Cb%3EUKG+WFM%3C%2Fb%3E...%3C%2Fp%3E%22%2C%22connectorName%22%3A%22ukg%22%7D%5D%7D%2C%7B%22richText%22%3A%22%3Cp%3EHere+are+the+details+for+your+request+%3Cstrong%3EPTO-955%3C%2Fstrong%3E%3A%3C%2Fp%3E%3Cul%3E%3Cli%3E%3Cstrong%3EType%3A%3C%2Fstrong%3E+Personal+Time+Off%3C%2Fli%3E%3Cli%3E%3Cstrong%3EStatus%3A%3C%2Fstrong%3E+Pending+Approval%3C%2Fli%3E%3Cli%3E%3Cstrong%3EDate%3A%3C%2Fstrong%3E+November+5%2C+2024+%28Full+Day%29%3C%2Fli%3E%3Cli%3E%3Cstrong%3ETotal+Hours%3A%3C%2Fstrong%3E+8.0%3C%2Fli%3E%3Cli%3E%3Cstrong%3EComment%3A%3C%2Fstrong%3E+%5C%22Dentist+appointment+in+the+morning%5C%22%3C%2Fli%3E%3Cli%3E%3Cstrong%3EApprover%3A%3C%2Fstrong%3E+Sarah+Jenkins%3C%2Fli%3E%3C%2Ful%3E%22%7D%5D%7D%2C%7B%22role%22%3A%22user%22%2C%22parts%22%3A%5B%7B%22richText%22%3A%22Can+you+show+me+any+pending+PTO+requests+for+my+team%3F%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%3EVerifying+manager+permissions...%3C%2Fp%3E%22%2C%22connectorName%22%3A%22ukg%22%7D%2C%7B%22status%22%3A%22success%22%2C%22richText%22%3A%22%3Cp%3EFetching+pending+requests+for+direct+reports+from+%3Cb%3EUKG+WFM%3C%2Fb%3E...%3C%2Fp%3E%22%2C%22connectorName%22%3A%22ukg%22%7D%5D%7D%2C%7B%22richText%22%3A%22%3Cp%3EHere+are+the+5+pending+requests+for+your+team+in+%3Cstrong%3EUKG+WFM%3C%2Fstrong%3E%3A%3C%2Fp%3E%3Cul%3E%3Cli%3E%3Cp%3E%3Cstrong%3EPTO-101%3C%2Fstrong%3E+%7C+%3Cb%3EJordan+Smith%3C%2Fb%3E+%7C+Vacation+%7C+Oct+08+-+Oct+10%2C+2024+%7C+Camping+trip%3C%2Fp%3E%3C%2Fli%3E%3Cli%3E%3Cp%3E%3Cstrong%3EPTO-102%3C%2Fstrong%3E+%7C+%3Cb%3EElena+Rodriguez%3C%2Fb%3E+%7C+Personal+%7C+Oct+12%2C+2024+%7C+Moving+day%3C%2Fp%3E%3C%2Fli%3E%3Cli%3E%3Cp%3E%3Cstrong%3EPTO-103%3C%2Fstrong%3E+%7C+%3Cb%3EMarcus+Chen%3C%2Fb%3E+%7C+Vacation+%7C+Oct+14+-+Oct+15%2C+2024+%7C+Short+break%3C%2Fp%3E%3C%2Fli%3E%3Cli%3E%3Cp%3E%3Cstrong%3EPTO-104%3C%2Fstrong%3E+%7C+%3Cb%3ESarah+Miller%3C%2Fb%3E+%7C+Vacation+%7C+Oct+25+-+Oct+27%2C+2024+%7C+Visit+parents%3C%2Fp%3E%3C%2Fli%3E%3Cli%3E%3Cp%3E%3Cstrong%3EPTO-105%3C%2Fstrong%3E+%7C+%3Cb%3EDavid+Wilson%3C%2Fb%3E+%7C+Sick+Leave+%7C+Nov+02%2C+2024+%7C+Minor+surgery%3C%2Fp%3E%3C%2Fli%3E%3C%2Ful%3E%22%7D%2C%7B%22citations%22%3A%5B%7B%22connectorName%22%3A%22ukg%22%2C%22citationTitle%22%3A%22PTO-101%22%7D%2C%7B%22connectorName%22%3A%22ukg%22%2C%22citationTitle%22%3A%22PTO-102%22%7D%2C%7B%22connectorName%22%3A%22ukg%22%2C%22citationTitle%22%3A%22PTO-103%22%7D%2C%7B%22connectorName%22%3A%22ukg%22%2C%22citationTitle%22%3A%22PTO-104%22%7D%2C%7B%22connectorName%22%3A%22ukg%22%2C%22citationTitle%22%3A%22PTO-105%22%7D%5D%7D%5D%7D%2C%7B%22role%22%3A%22user%22%2C%22parts%22%3A%5B%7B%22richText%22%3A%22Can+you+show+me+upcoming+approved+PTO+for+my+team%3F%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%3EVerifying+manager+permissions+for+team+calendar...%3C%2Fp%3E%22%2C%22connectorName%22%3A%22ukg%22%7D%2C%7B%22status%22%3A%22success%22%2C%22richText%22%3A%22%3Cp%3EFiltering+approved+requests+for+the+next+90+days+in+%3Cb%3EUKG+WFM%3C%2Fb%3E...%3C%2Fp%3E%22%2C%22connectorName%22%3A%22ukg%22%7D%5D%7D%2C%7B%22richText%22%3A%22%3Cp%3EI+found+7+upcoming+approved+requests+for+your+team+over+the+next+3+months%3A%3C%2Fp%3E%3Cul%3E%3Cli%3E%3Cp%3E%3Cstrong%3EPTO-201%3C%2Fstrong%3E+%7C+%3Cb%3EJordan+Smith%3C%2Fb%3E+%7C+Vacation+%7C+Oct+05+-+Oct+06%2C+2024+%7C+Weekend+trip%3C%2Fp%3E%3C%2Fli%3E%3Cli%3E%3Cp%3E%3Cstrong%3EPTO-202%3C%2Fstrong%3E+%7C+%3Cb%3EElena+Rodriguez%3C%2Fb%3E+%7C+Vacation+%7C+Oct+15+-+Oct+18%2C+2024+%7C+Hiking%3C%2Fp%3E%3C%2Fli%3E%3Cli%3E%3Cp%3E%3Cstrong%3EPTO-203%3C%2Fstrong%3E+%7C+%3Cb%3EDavid+Wilson%3C%2Fb%3E+%7C+Vacation+%7C+Oct+28%2C+2024+%7C+Birthday%3C%2Fp%3E%3C%2Fli%3E%3Cli%3E%3Cp%3E%3Cstrong%3EPTO-204%3C%2Fstrong%3E+%7C+%3Cb%3EMarcus+Chen%3C%2Fb%3E+%7C+Vacation+%7C+Nov+10+-+Nov+12%2C+2024+%7C+City+break%3C%2Fp%3E%3C%2Fli%3E%3Cli%3E%3Cp%3E%3Cstrong%3EPTO-205%3C%2Fstrong%3E+%7C+%3Cb%3ESarah+Miller%3C%2Fb%3E+%7C+Vacation+%7C+Nov+22+-+Nov+24%2C+2024+%7C+Thanksgiving%3C%2Fp%3E%3C%2Fli%3E%3Cli%3E%3Cp%3E%3Cstrong%3EPTO-206%3C%2Fstrong%3E+%7C+%3Cb%3EJordan+Smith%3C%2Fb%3E+%7C+Vacation+%7C+Dec+05+-+Dec+08%2C+2024+%7C+Ski+trip%3C%2Fp%3E%3C%2Fli%3E%3Cli%3E%3Cp%3E%3Cstrong%3EPTO-207%3C%2Fstrong%3E+%7C+%3Cb%3EElena+Rodriguez%3C%2Fb%3E+%7C+Vacation+%7C+Dec+24+-+Dec+26%2C+2024+%7C+Holidays%3C%2Fp%3E%3C%2Fli%3E%3C%2Ful%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 **View PTO Requests & Calendar** 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 requests through this plugin, employees must already have permission to search PTO records in UKG WFM — the same permissions required to search PTO records through the UKG WFM UI. At a minimum, end users must have: - **Time Off permissions** that allow: - Viewing available Time Off Types - Viewing own Time Off requests - Access to their own **employee profile and time account balances** ### **End User Permissions (Manager Persona)** To look up PTO requests through this plugin, managers must already have permission to search PTO records in UKG WFM — the same permissions required to search PTO records through the UKG WFM UI. At a minimum, end users must have: - **Time Off permissions** that allow: - Viewing available Time Off Types - Viewing own Time Off requests - Viewing Time Off requests for direct reports - Access to their own and **direct reports’ 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 WFM. > # **Implementation details** ## Visual Representation of How the Plugin Works This plugin caters to three use cases: 1. Scheduled and Past PTO - retrieves a list of upcoming approved PTO and past PTO requests (employee) ![image.png](View%20PTO%20Requests%20&%20Calendar/image.png) 1. Pending PTO Requests - retrieves a list of pending PTO requests awaiting approval by logged in user (manager) ![image.png](View%20PTO%20Requests%20&%20Calendar/image%201.png) 1. Team PTO Calendar - retrieves a list of approved PTO requests for direct reports (manager) ![image.png](View%20PTO%20Requests%20&%20Calendar/image%202.png) ## API Details Before running the cURL examples below, replace `` 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 `` in the cURL commands. ### **API #1: Get a User’s UKG ID** This REST API is used to fetch employee details for the current logged in user. ```bash curl --request GET \ --url 'https:///api/v1/commons/persons/current_user_info?include_contact_information=true' \ --header 'Authorization: ' \ --header 'Content-Type: application/json' ``` **Query Parameters:** - None. ### **API #2: Retrieve User’s available Hyperfind Queries** This REST API is used to check if the logged in user is a manager in UKG WFM. If the user has the hyperfind query “**My Direct Reports**” in returned list, then the user is a manager. ```bash curl --request GET \ --url https:///api/v1/commons/hyperfind \ --header 'Authorization: ' \ --header 'Content-Type: application/json' ``` **Query Parameters:** - None. ### **API #3: Retrieve User’s List of Direct Reports** This REST API is used to retrieve the list of direct reports for the logged in user (expected to be a manager). ```bash curl --request POST \ --url https:///api/v1/commons/hyperfind/execute \ --header 'Authorization: ' \ --header 'Content-Type: application/json' \ --data '{ "dateRange": { "symbolicPeriod": { "qualifier": "Current_Payperiod" } }, "hyperfind": { "qualifier": "My Direct Reports" } }' ``` **Query Parameters:** - None. ### API #4: Retrieve PTO Requests This API retrieves PTO requests filtered by: - **Employee list** (array of person IDs) - **Completion state** (`INCOMPLETE` / `COMPLETE`) - **Date range** It is used in the following scenarios: 1. **Scheduled & Past PTO (Employee View)** - `ARRAY_OF_PERSON_IDS`: Logged-in user’s person ID (wrapped in an array) - `COMPLETION_STATE`: `COMPLETE` - Returns approved upcoming and past PTO requests 2. **Pending PTO Requests (Manager View)** - `ARRAY_OF_PERSON_IDS`: Direct reports’ person IDs - `COMPLETION_STATE`: `INCOMPLETE` - Returns pending requests awaiting approval 3. **Team PTO Calendar (Manager View)** - `ARRAY_OF_PERSON_IDS`: Direct reports’ person IDs - `COMPLETION_STATE`: `COMPLETE` - Returns approved PTO requests for the team ```bash curl --request POST \ --url https:///api/v1/scheduling/timeoff/multi_read \ --header 'Authorization: ' \ --header 'Content-Type: application/json' \ --data '{ "where": { "states": { "employeeRefs": { "ids": }, "completionState": "", "endDate": "", "startDate": "" } } }' ``` **Filter Parameters:** - `ARRAY_OF_PERSON_IDS` *(string):* This will be a list of direct reports (manager) or just the logged in user’s person ID (employee) - `COMPLETION_STATE` *(string):* This will be the completion state of the PTO request (INCOMPLETE/COMPLETE). - `START_DATE` *(string):* This will be the start date to search for PTO requests. If user has not specified a date, it defaults to 3 months prior to the current date. - `END_DATE` *(string):* This will be the end date to search for PTO requests. If user has not specified a date, it defaults to 3 months after the current date. **Key nuances:** - `COMPLETION_STATE` results and filtering: - When `COMPLETION_STATE` = “**COMPLETE**” the results returned will include APPROVED, REFUSED and CANCELLED requests and the plugin will filter on APPROVED requests only. ### 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: - Searching for PTO requests for **limited leave types** (e.g., Vacation, Sick Leave, Casual Leave, Earned Leave, Comp Time). - Restricted to PTO requests that are currently pending and require a manager’s approval. - The plugin is intended to provide visibility only. # **What Is Out of Scope for This Plugin?** This plugin does **not** support the following: - Searching for PTO requests for **non-limited or leave-of-absence types**, such as parental leave, FMLA, or long-term disability. - The UKG Connector API does not support an employee acting on behalf of a manager (i.e., manager delegation/proxy approver). - Retrieval of PTO Balances are handled by a separate plugin. - Approving, rejecting, editing, or cancelling PTO are handled by separate plugins. - Coverage or capacity analysis (e.g., overlap warnings, staffing impact).