---
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 and Calendar
installation_asset_uuid: 5eeb24b9-805e-4525-a1d4-23be0f5319e7
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%22Validating+employee+identity+in+%3Cb%3ESAP+SuccessFactors%3C%2Fb%3E...%22%2C%22connectorName%22%3A%22sap-success-factors%22%7D%2C%7B%22status%22%3A%22success%22%2C%22richText%22%3A%22Retrieving+personal+time+off+requests...%22%2C%22connectorName%22%3A%22sap-success-factors%22%7D%5D%7D%2C%7B%22richText%22%3A%22%3Cp%3EI+found+3+time+off+requests+for+you%3A%3C%2Fp%3E%3Cul%3E%3Cli%3E%3Cb%3EPTO-942%3C%2Fb%3E+%7C+Vacation+%7C+Oct+12+-+Oct+14%2C+2024+%7C+Family+trip+%28Approved%29%3C%2Fli%3E%3Cli%3E%3Cb%3EPTO-955%3C%2Fb%3E+%7C+Personal+%7C+Nov+05%2C+2024+%7C+Appointment+%28Pending%29%3C%2Fli%3E%3Cli%3E%3Cb%3EPTO-981%3C%2Fb%3E+%7C+Sick+Leave+%7C+Dec+02+-+Dec+03%2C+2024+%7C+Recovery+%28Pending%29%3C%2Fli%3E%3C%2Ful%3E%22%7D%2C%7B%22citations%22%3A%5B%7B%22connectorName%22%3A%22sap-success-factors%22%2C%22citationTitle%22%3A%22PTO-942%22%7D%2C%7B%22connectorName%22%3A%22sap-success-factors%22%2C%22citationTitle%22%3A%22PTO-955%22%7D%2C%7B%22connectorName%22%3A%22sap-success-factors%22%2C%22citationTitle%22%3A%22PTO-981%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+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%22Verifying+manager+permissions+in+%3Cb%3ESAP+SuccessFactors%3C%2Fb%3E...%22%2C%22connectorName%22%3A%22sap-success-factors%22%7D%2C%7B%22status%22%3A%22success%22%2C%22richText%22%3A%22Fetching+pending+requests+for+direct+reports...%22%2C%22connectorName%22%3A%22sap-success-factors%22%7D%5D%7D%2C%7B%22richText%22%3A%22%3Cp%3EHere+are+the+5+pending+requests+for+your+team%3A%3C%2Fp%3E%3Cul%3E%3Cli%3E%3Cb%3EPTO-101%3C%2Fb%3E+%7C+Vacation+%7C+Oct+08+-+Oct+10%2C+2024+%7C+Camping+trip%3C%2Fli%3E%3Cli%3E%3Cb%3EPTO-102%3C%2Fb%3E+%7C+Personal+%7C+Oct+12%2C+2024+%7C+Moving+day%3C%2Fli%3E%3Cli%3E%3Cb%3EPTO-103%3C%2Fb%3E+%7C+Vacation+%7C+Oct+14+-+Oct+15%2C+2024+%7C+Short+break%3C%2Fli%3E%3Cli%3E%3Cb%3EPTO-104%3C%2Fb%3E+%7C+Vacation+%7C+Oct+25+-+Oct+27%2C+2024+%7C+Visit+parents%3C%2Fli%3E%3Cli%3E%3Cb%3EPTO-105%3C%2Fb%3E+%7C+Sick+Leave+%7C+Nov+02%2C+2024+%7C+Minor+surgery%3C%2Fli%3E%3C%2Ful%3E%3Cp%3EWould+you+like+to+approve+any+of+these%3F%3C%2Fp%3E%22%7D%2C%7B%22citations%22%3A%5B%7B%22connectorName%22%3A%22sap-success-factors%22%2C%22citationTitle%22%3A%22PTO-101%22%7D%2C%7B%22connectorName%22%3A%22sap-success-factors%22%2C%22citationTitle%22%3A%22PTO-102%22%7D%2C%7B%22connectorName%22%3A%22sap-success-factors%22%2C%22citationTitle%22%3A%22PTO-103%22%7D%2C%7B%22connectorName%22%3A%22sap-success-factors%22%2C%22citationTitle%22%3A%22PTO-104%22%7D%2C%7B%22connectorName%22%3A%22sap-success-factors%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%22Not+at+this+time.%22%7D%5D%7D%2C%7B%22role%22%3A%22user%22%2C%22parts%22%3A%5B%7B%22richText%22%3A%22Can+you+show+me+the+upcoming+approved+vacation+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%22Verifying+manager+permissions+for+team+calendar...%22%2C%22connectorName%22%3A%22sap-success-factors%22%7D%2C%7B%22status%22%3A%22success%22%2C%22richText%22%3A%22Filtering+approved+requests+for+the+next+90+days...%22%2C%22connectorName%22%3A%22sap-success-factors%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%3Cb%3EPTO-201%3C%2Fb%3E+%7C+Vacation+%7C+Oct+05+-+Oct+06%2C+2024+%7C+Weekend+trip%3C%2Fli%3E%3Cli%3E%3Cb%3EPTO-202%3C%2Fb%3E+%7C+Vacation+%7C+Oct+15+-+Oct+18%2C+2024+%7C+Hiking%3C%2Fli%3E%3Cli%3E%3Cb%3EPTO-203%3C%2Fb%3E+%7C+Vacation+%7C+Oct+28%2C+2024+%7C+Birthday%3C%2Fli%3E%3Cli%3E%3Cb%3EPTO-204%3C%2Fb%3E+%7C+Vacation+%7C+Nov+10+-+Nov+12%2C+2024+%7C+City+break%3C%2Fli%3E%3Cli%3E%3Cb%3EPTO-205%3C%2Fb%3E+%7C+Vacation+%7C+Nov+22+-+Nov+24%2C+2024+%7C+Thanksgiving%3C%2Fli%3E%3Cli%3E%3Cb%3EPTO-206%3C%2Fb%3E+%7C+Vacation+%7C+Dec+05+-+Dec+08%2C+2024+%7C+Ski+trip%3C%2Fli%3E%3Cli%3E%3Cb%3EPTO-207%3C%2Fb%3E+%7C+Vacation+%7C+Dec+24+-+Dec+26%2C+2024+%7C+Holidays%3C%2Fli%3E%3C%2Ful%3E%22%7D%2C%7B%22citations%22%3A%5B%7B%22connectorName%22%3A%22sap-success-factors%22%2C%22citationTitle%22%3A%22PTO-201%22%7D%2C%7B%22connectorName%22%3A%22sap-success-factors%22%2C%22citationTitle%22%3A%22PTO-202%22%7D%2C%7B%22connectorName%22%3A%22sap-success-factors%22%2C%22citationTitle%22%3A%22PTO-203%22%7D%2C%7B%22connectorName%22%3A%22sap-success-factors%22%2C%22citationTitle%22%3A%22PTO-204%22%7D%2C%7B%22connectorName%22%3A%22sap-success-factors%22%2C%22citationTitle%22%3A%22PTO-205%22%7D%2C%7B%22connectorName%22%3A%22sap-success-factors%22%2C%22citationTitle%22%3A%22PTO-206%22%7D%2C%7B%22connectorName%22%3A%22sap-success-factors%22%2C%22citationTitle%22%3A%22PTO-207%22%7D%5D%7D%5D%7D%5D%7D
solution_tags:
- HR - Other
- HR - Time & Absence
systems:
- sap-success-factors
---
# 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%22Validating+employee+identity+in+%3Cb%3ESAP+SuccessFactors%3C%2Fb%3E...%22%2C%22connectorName%22%3A%22sap-success-factors%22%7D%2C%7B%22status%22%3A%22success%22%2C%22richText%22%3A%22Retrieving+personal+time+off+requests...%22%2C%22connectorName%22%3A%22sap-success-factors%22%7D%5D%7D%2C%7B%22richText%22%3A%22%3Cp%3EI+found+3+time+off+requests+for+you%3A%3C%2Fp%3E%3Cul%3E%3Cli%3E%3Cb%3EPTO-942%3C%2Fb%3E+%7C+Vacation+%7C+Oct+12+-+Oct+14%2C+2024+%7C+Family+trip+%28Approved%29%3C%2Fli%3E%3Cli%3E%3Cb%3EPTO-955%3C%2Fb%3E+%7C+Personal+%7C+Nov+05%2C+2024+%7C+Appointment+%28Pending%29%3C%2Fli%3E%3Cli%3E%3Cb%3EPTO-981%3C%2Fb%3E+%7C+Sick+Leave+%7C+Dec+02+-+Dec+03%2C+2024+%7C+Recovery+%28Pending%29%3C%2Fli%3E%3C%2Ful%3E%22%7D%2C%7B%22citations%22%3A%5B%7B%22connectorName%22%3A%22sap-success-factors%22%2C%22citationTitle%22%3A%22PTO-942%22%7D%2C%7B%22connectorName%22%3A%22sap-success-factors%22%2C%22citationTitle%22%3A%22PTO-955%22%7D%2C%7B%22connectorName%22%3A%22sap-success-factors%22%2C%22citationTitle%22%3A%22PTO-981%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+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%22Verifying+manager+permissions+in+%3Cb%3ESAP+SuccessFactors%3C%2Fb%3E...%22%2C%22connectorName%22%3A%22sap-success-factors%22%7D%2C%7B%22status%22%3A%22success%22%2C%22richText%22%3A%22Fetching+pending+requests+for+direct+reports...%22%2C%22connectorName%22%3A%22sap-success-factors%22%7D%5D%7D%2C%7B%22richText%22%3A%22%3Cp%3EHere+are+the+5+pending+requests+for+your+team%3A%3C%2Fp%3E%3Cul%3E%3Cli%3E%3Cb%3EPTO-101%3C%2Fb%3E+%7C+Vacation+%7C+Oct+08+-+Oct+10%2C+2024+%7C+Camping+trip%3C%2Fli%3E%3Cli%3E%3Cb%3EPTO-102%3C%2Fb%3E+%7C+Personal+%7C+Oct+12%2C+2024+%7C+Moving+day%3C%2Fli%3E%3Cli%3E%3Cb%3EPTO-103%3C%2Fb%3E+%7C+Vacation+%7C+Oct+14+-+Oct+15%2C+2024+%7C+Short+break%3C%2Fli%3E%3Cli%3E%3Cb%3EPTO-104%3C%2Fb%3E+%7C+Vacation+%7C+Oct+25+-+Oct+27%2C+2024+%7C+Visit+parents%3C%2Fli%3E%3Cli%3E%3Cb%3EPTO-105%3C%2Fb%3E+%7C+Sick+Leave+%7C+Nov+02%2C+2024+%7C+Minor+surgery%3C%2Fli%3E%3C%2Ful%3E%3Cp%3EWould+you+like+to+approve+any+of+these%3F%3C%2Fp%3E%22%7D%2C%7B%22citations%22%3A%5B%7B%22connectorName%22%3A%22sap-success-factors%22%2C%22citationTitle%22%3A%22PTO-101%22%7D%2C%7B%22connectorName%22%3A%22sap-success-factors%22%2C%22citationTitle%22%3A%22PTO-102%22%7D%2C%7B%22connectorName%22%3A%22sap-success-factors%22%2C%22citationTitle%22%3A%22PTO-103%22%7D%2C%7B%22connectorName%22%3A%22sap-success-factors%22%2C%22citationTitle%22%3A%22PTO-104%22%7D%2C%7B%22connectorName%22%3A%22sap-success-factors%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%22Not+at+this+time.%22%7D%5D%7D%2C%7B%22role%22%3A%22user%22%2C%22parts%22%3A%5B%7B%22richText%22%3A%22Can+you+show+me+the+upcoming+approved+vacation+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%22Verifying+manager+permissions+for+team+calendar...%22%2C%22connectorName%22%3A%22sap-success-factors%22%7D%2C%7B%22status%22%3A%22success%22%2C%22richText%22%3A%22Filtering+approved+requests+for+the+next+90+days...%22%2C%22connectorName%22%3A%22sap-success-factors%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%3Cb%3EPTO-201%3C%2Fb%3E+%7C+Vacation+%7C+Oct+05+-+Oct+06%2C+2024+%7C+Weekend+trip%3C%2Fli%3E%3Cli%3E%3Cb%3EPTO-202%3C%2Fb%3E+%7C+Vacation+%7C+Oct+15+-+Oct+18%2C+2024+%7C+Hiking%3C%2Fli%3E%3Cli%3E%3Cb%3EPTO-203%3C%2Fb%3E+%7C+Vacation+%7C+Oct+28%2C+2024+%7C+Birthday%3C%2Fli%3E%3Cli%3E%3Cb%3EPTO-204%3C%2Fb%3E+%7C+Vacation+%7C+Nov+10+-+Nov+12%2C+2024+%7C+City+break%3C%2Fli%3E%3Cli%3E%3Cb%3EPTO-205%3C%2Fb%3E+%7C+Vacation+%7C+Nov+22+-+Nov+24%2C+2024+%7C+Thanksgiving%3C%2Fli%3E%3Cli%3E%3Cb%3EPTO-206%3C%2Fb%3E+%7C+Vacation+%7C+Dec+05+-+Dec+08%2C+2024+%7C+Ski+trip%3C%2Fli%3E%3Cli%3E%3Cb%3EPTO-207%3C%2Fb%3E+%7C+Vacation+%7C+Dec+24+-+Dec+26%2C+2024+%7C+Holidays%3C%2Fli%3E%3C%2Ful%3E%22%7D%2C%7B%22citations%22%3A%5B%7B%22connectorName%22%3A%22sap-success-factors%22%2C%22citationTitle%22%3A%22PTO-201%22%7D%2C%7B%22connectorName%22%3A%22sap-success-factors%22%2C%22citationTitle%22%3A%22PTO-202%22%7D%2C%7B%22connectorName%22%3A%22sap-success-factors%22%2C%22citationTitle%22%3A%22PTO-203%22%7D%2C%7B%22connectorName%22%3A%22sap-success-factors%22%2C%22citationTitle%22%3A%22PTO-204%22%7D%2C%7B%22connectorName%22%3A%22sap-success-factors%22%2C%22citationTitle%22%3A%22PTO-205%22%7D%2C%7B%22connectorName%22%3A%22sap-success-factors%22%2C%22citationTitle%22%3A%22PTO-206%22%7D%2C%7B%22connectorName%22%3A%22sap-success-factors%22%2C%22citationTitle%22%3A%22PTO-207%22%7D%5D%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. SAP SuccessFactors Connector**
This plugin requires an active **SAP SuccessFactors connector** to communicate with your SAP SuccessFactors instance.
- If you have not already configured the connector, please follow the [**SAP SuccessFactors Connector Guide**](https://marketplace.moveworks.com/connectors/sap-success-factors#client-credentials) available in the Moveworks Marketplace.
- The connector must be fully set up and 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**.
## **2. SAP SuccessFactors System Requirements**
### **a. End User Permissions (Employee Persona)**
To look up PTO requests through this plugin, employees must already have permission to view PTO records in SAP SuccessFactors — the same permissions required to view PTO through the SuccessFactors UI.
At a minimum, end users must have:
- **Time Off permissions** that allow:
- Viewing available Time Off Types
- Viewing own Time Off / PTO requests
- Access to their own **employee profile and time account balances**
### **b. End User Permissions (Manager Persona)**
To look up PTO requests through this plugin, managers must already have permission to view PTO records in SAP SuccessFactors — the same permissions required to view PTO through the SuccessFactors UI.
At a minimum, end users must have:
- **Time Off permissions** that allow:
- Viewing available Time Off Types
- Viewing own Time Off / PTO 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 users in SAP SuccessFactors.
### **b. API Permissions (via Integration User)**
The SuccessFactors connector uses an **integration user** **auth** to view PTO requests through SAP SuccessFactors APIs.
That admin/integration user must have permissions to:
- View and search Time Off requests on behalf of employees
- Read Time Off Types and Time Account information
- Validate employee eligibility (as required by your configuration)
These permissions are typically configured through [**Role-Based Permissions (RBP)**](https://learning.sap.com/courses/sap-successfactors-employee-central-core-administration/configuring-role-based-permissions) in SAP SuccessFactors.
# **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)
1. Pending PTO Requests - retrieves a list of pending PTO requests awaiting approval by logged in user (manager)
1. Team PTO Calendar - retrieves a list of approved PTO requests for direct reports (manager)
## API Details
For a complete list of SAP SuccessFactors API servers(tenantURL) by region and environment, refer to the [**SAP API Server Directory**](https://help.sap.com/docs/successfactors-platform/sap-successfactors-api-reference-guide-odata-v2/list-of-sap-successfactors-api-servers).
### **API #1: Get a User’s SAP SF ID based on their Email**
This OData API is used to fetch employee and manager identifiers from SAP SuccessFactors using the employee’s email address. The returned **User IDs** are required for downstream API calls.
```bash
curl -X GET "https://<tenantURL>/odata/v2/User?$filter=(email eq '{{emailAddress}}')&$select=userId,email,firstName,lastName,defaultFullName&$format=json" \
-H "Content-Type: application/json"
```
**Query Parameters**
- `emailAddress` *(string):* Email address of the employee whose SAP SuccessFactors user record needs to be retrieved.
- `$filter=email eq '{{emailAddress}}'`: Filters the User entity to match the provided email address.
- `$select`:Limits the response to required user fields only:
- `userId`
- `email`
- `firstName`
- `lastName`
- `defaultFullName`
### **API #2: Retrieve Available PTO Time 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 both limited and non-limited leave types. Within the plugin, non-limited leave types are filtered out so that only limited leave types associated with PTO are presented to the employee.
```bash
curl -X GET "https://<tenantURL>/rest/timemanagement/absence/v1/availableTimeTypes?$at={{as_of_date}}" \
-H "Content-Type: application/json"
```
**Query Parameters:**
- `AS_OF_DATE` *(string):* The date (ISO format: `YYYY-MM-DD`) used to determine which PTO time types are valid and available to the employee.
**Key nuances:**
- **Returns all leave types**
- The API returns both **limited** (PTO) and **non-limited** (e.g., leave of absence) time types.
- The plugin filters the response to include **only limited time types** eligible for PTO requests.
- **Effective-dated results**
- Available time types depend on the **“as of date”** passed to the API.
- Different dates may return different eligible PTO types due to policy changes or employee eligibility.
### **API #3: Fetch pending PTO requests**
This API calls SAP SuccessFactors **EmployeeTime** (OData) to retrieve leave requests that are awaiting action from the current user in their role as a manager. The query uses the manager’s user ID along with request status, date filters, and leave types to return PTO entries that are **pending approval** and require review.
```bash
curl --request GET 'https://<tenantURL>/odata/v2/EmployeeTime?$filter=approvalStatus eq 'PENDING' and {{{user_IDs}}} and {{{externalCode}}} and startDate ge datetime'{{start_date}}T00:00:00' and endDate le datetime'{{end_date}}T23:59:59'&$format=json&$expand=userIdNav,timeTypeNav&$select=userId,startDate,endDate,timeTypeNav/externalCode,timeTypeNav/externalName_defaultValue,approvalStatus,userIdNav/defaultFullName,userIdNav/country,workflowRequestId,externalCode,createdDateTime,quantityInHours&$orderby=startDate asc'
```
---
**Query Parameters:**
- `user_IDs` *(string):* SAP SF user Identifier of the logged in user.
- `externalCode` *(string):* This is needed to make sure that API only returns the PTOs with limited leave type. **Example value is in the format as**: timeTypeNav/externalCode eq 'TT_SICK_REC' or timeTypeNav/externalCode eq 'TT_VAC_REC'
- `start_date` *(string):* The start date (ISO format: `YYYY-MM-DD`) used to determine which PTO time types are valid and available to the employee.
- `end_date` *(string):* The date (ISO format: `YYYY-MM-DD`) used to determine which PTO time types are valid and available to the employee.
- `$expand`: This is a mandatory query param is order to make sure we are getting all the details related to user including user’s full name, country and Timetype code and name value to show to the user
- `$filter=approvalStatus eq 'PENDING' and {{{user_IDs}}} and {{{externalCode}}} and startDate ge datetime'{{start_date}}T00:00:00' and endDate le datetime'{{end_date}}T23:59:59':` Filters for ‘PENDING’ records between specified dates.
- `$select`: Limits the response to required user fields only:
- `userId`
- `startDate`
- `endDate`
- `timeTypeNav/externalCode`
- `timeTypeNav/externalName_defaultValue`
- `approvalStatus`
- `userIdNav/defaultFullName`
- `userIdNav/country`
- `workflowRequestId`
- `externalCode`
- `createdDateTime`
- `quantityInHours`
- `$orderby=startDate asc`: Sort results by start date in ascending order.
**Key nuances:**
- **Returns all leave types**
- The API returns both **limited** (PTO) and **non-limited** (e.g., leave of absence) time types.
- The plugin filters the response to include **only limited time types** eligible for PTO requests.
- **Effective-dated results**
- Available time types depend on the **“as of date”** passed to the API.
- Different dates may return different eligible PTO types due to policy changes or employee eligibility.
### **API #4: Fetch approved PTO requests**
This OData API is used to retrieve an employee’s approved PTOs from SAP SuccessFactors. The query uses the employee’s user ID together with approval status and date filters to return **current and historical approved PTO** for self-service viewing.
```bash
curl --request GET 'https://<tenantURL>/odata/v2/EmployeeTime?$filter=approvalStatus eq 'APPROVED' and userId eq '{{userId}}' and startDate ge datetime'{{start_date}}T00:00:00' and endDate le datetime'{{end_date}}T23:59:59' and {{{externalCode}}}&$format=json&$expand=userIdNav,timeTypeNav&$select=userId,startDate,endDate,timeTypeNav/externalCode,timeTypeNav/externalName_defaultValue,approvalStatus,userIdNav/defaultFullName,userIdNav/country,workflowRequestId,externalCode,createdDateTime,quantityInHours,comment&$orderby=startDate asc'
```
**Query Parameters:**
- `user_IDs` *(string):* SAP SF user Identifier of the logged in user.
- `externalCode` *(string):* This is needed to make sure that API only returns the PTOs with limited leave type. **Example value is in the format as**: timeTypeNav/externalCode eq 'TT_SICK_REC' or timeTypeNav/externalCode eq 'TT_VAC_REC'
- `start_date` *(string):* The start date (ISO format: `YYYY-MM-DD`) used to determine which PTO time types are valid and available to the employee.
- `end_date` *(string):* The date (ISO format: `YYYY-MM-DD`) used to determine which PTO time types are valid and available to the employee.
- `$expand`: This is a mandatory query param is order to make sure we are getting all the details related to user including user’s full name, country and Timetype code and name value to show to the user
- `$filter=approvalStatus eq 'APPROVED' and userId eq '{{userId}}' and startDate ge datetime'{{start_date}}T00:00:00' and endDate le datetime'{{end_date}}T23:59:59' and {{{externalCode}}}`: Filters for ‘APPROVED’ records between specified dates.
- `$select`: Limits the response to required user fields only:
- `userId`
- `startDate`
- `endDate`
- `timeTypeNav/externalCode`
- `timeTypeNav/externalName_defaultValue`
- `approvalStatus`
- `userIdNav/defaultFullName`
- `userIdNav/country`
- `workflowRequestId`
- `externalCode`
- `createdDateTime`
- `quantityInHours`
- `comment`
- `$orderby=startDate asc`: Sort results by start date in ascending order.
**Key nuances:**
- **Returns all leave types**
- The API returns both **limited** (PTO) and **non-limited** (e.g., leave of absence) time types.
- The plugin filters the response to include **only limited time types** eligible for PTO requests.
- **Effective-dated results**
- Available time types depend on the **“as of date”** passed to the API.
- Different dates may return different eligible PTO types due to policy changes or employee eligibility.
### **API #5: Fetch Team approved PTO requests**
This OData API is used to retrieve leave requests that have already been approved for employees reporting to the current user. The query uses the manager’s user ID, along with approval status and date filters, to return the team’s schedule for visibility and planning.
```bash
curl --request GET 'https://apisalesdemo8.successfactors.com/odata/v2/EmployeeTime?$filter=approvalStatus eq 'APPROVED' and {{{user_IDs}}} and {{{externalCode}}} and startDate ge datetime'{{start_date}}T00:00:00' and endDate le datetime'{{end_date}}T23:59:59'&$format=json&$expand=userIdNav,timeTypeNav&$select=userId,startDate,endDate,timeTypeNav/externalCode,timeTypeNav/externalName_defaultValue,approvalStatus,userIdNav/defaultFullName,userIdNav/country,workflowRequestId,externalCode,createdDateTime,quantityInHours,comment&$orderby=startDate asc'
```
---
**Query Parameters:**
- `user_IDs` *(string):* SAP SF user Identifier of the logged in user.
- `externalCode` *(string):* This is needed to make sure that API only returns the PTOs with limited leave type. **Example value is in the format as**: timeTypeNav/externalCode eq 'TT_SICK_REC' or timeTypeNav/externalCode eq 'TT_VAC_REC'
- `start_date` *(string):* The start date (ISO format: `YYYY-MM-DD`) used to determine which PTO time types are valid and available to the employee.
- `end_date` *(string):* The date (ISO format: `YYYY-MM-DD`) used to determine which PTO time types are valid and available to the employee.
- `$expand`: This is a mandatory query param is order to make sure we are getting all the details related to user including user’s full name, country and Timetype code and name value to show to the user
- `$filter=approvalStatus eq 'APPROVED' and {{{user_IDs}}} and {{{externalCode}}} and startDate ge datetime'{{start_date}}T00:00:00' and endDate le datetime'{{end_date}}T23:59:59':` Filters for ‘APPROVED’ records between specified dates.
- `$select`: Limits the response to required user fields only:
- `userId`
- `startDate`
- `endDate`
- `timeTypeNav/externalCode`
- `timeTypeNav/externalName_defaultValue`
- `approvalStatus`
- `userIdNav/defaultFullName`
- `userIdNav/country`
- `workflowRequestId`
- `externalCode`
- `createdDateTime`
- `quantityInHours`
- `comment`
- `$orderby=startDate asc`: Sort results by start date in ascending order.
**Key nuances:**
- **Returns all leave types**
- The API returns both **limited** (PTO) and **non-limited** (e.g., leave of absence) time types.
- The plugin filters the response to include **only limited time types** eligible for PTO requests.
- **Effective-dated results**
- Available time types depend on the **“as of date”** passed to the API.
- Different dates may return different eligible PTO types due to policy changes or employee eligibility.
### API References
This plugin uses a combination of **SAP SuccessFactors OData APIs** and **Time Management REST APIs** to retrieve employee information, determine eligible PTO time types, and submit PTO requests.
For detailed information on request parameters, response formats, error handling, and versioning, please refer to the **official SAP SuccessFactors API documentation** provided by SAP.
# **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).
- Retrieve approved PTO only for the requesting employee (employee persona)
- Retrieve approved PTO only for direct reports for the requesting manager (manager persona)
- Restricted to PTO requests that are currently pending and require a manager’s approval (manager persona)
- The plugin is intended to provide visibility only.
- Coverage or capacity analysis (e.g., overlap warnings, staffing impact).
# **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.
- Retrieval of PTO Balances are handled by a separate plugin.
- Approving, rejecting, editing, or cancelling PTO are handled by separate plugins.