---
availability: INSTALLABLE
description: Enables employees to modify existing PTO entries—upcoming or completed—while automatically applying the correct policy, approval, and payroll workflows.
name: Modify PTO Request
installation_asset_uuid: 7a15616e-3061-44f0-82f8-709c54c0b318
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+need+to+modify+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%22Fetching+time-off+requests+from+%3Cb%3ESAP+SuccessFactors%3C%2Fb%3E...%22%2C%22connectorName%22%3A%22sap-success-factors%22%7D%5D%7D%2C%7B%22richText%22%3A%22%3Cp%3EI+found+2+upcoming+requests+in+%3Cstrong%3ESAP+SuccessFactors%3C%2Fstrong%3E.+Which+one+would+you+like+to+modify%3F%3C%2Fp%3E%3Cul%3E%3Cli%3E%3Cp%3E%3Cstrong%3ESick%3C%2Fstrong%3E%3A+Dec+10+-+Dec+12+%28Approved%29%3C%2Fp%3E%3C%2Fli%3E%3Cli%3E%3Cp%3E%3Cstrong%3EVacation%3C%2Fstrong%3E%3A+Dec+26+-+Dec+30+%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%22Can+you+change+the+Dec+26+-+30+vacation+to+Sick+leave+instead%3F%22%7D%5D%7D%2C%7B%22role%22%3A%22assistant%22%2C%22parts%22%3A%5B%7B%22richText%22%3A%22%3Cp%3EI+can+update+your+request+from+%3Cb%3EVacation%3C%2Fb%3E+to+%3Cb%3ESick+Leave%3C%2Fb%3E+in+%3Cb%3ESAP+SuccessFactors%3C%2Fb%3E.%3C%2Fp%3E%3Cul%3E%3Cli%3E%3Cb%3ERequest%3C%2Fb%3E%3A+Dec+26+-+Dec+30%3C%2Fli%3E%3Cli%3E%3Cb%3ENew+Type%3C%2Fb%3E%3A+Sick+Leave%3C%2Fli%3E%3C%2Ful%3E%3Cp%3E%3Cb%3EWould+you+like+to+proceed%3F%3C%2Fb%3E%3C%2Fp%3E%22%7D%2C%7B%22buttons%22%3A%5B%7B%22buttonText%22%3A%22Yes%22%2C%22style%22%3A%22filled%22%7D%2C%7B%22buttonText%22%3A%22Cancel%22%2C%22style%22%3A%22outlined%22%7D%5D%7D%5D%7D%2C%7B%22role%22%3A%22user%22%2C%22parts%22%3A%5B%7B%22richText%22%3A%22Yes%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%22Updating+request+type+in+%3Cb%3ESAP+SuccessFactors%3C%2Fb%3E...%22%2C%22connectorName%22%3A%22sap-success-factors%22%7D%5D%7D%2C%7B%22richText%22%3A%22Done%21+I%27ve+updated+the+request+type+to+Sick+Leave.%22%7D%5D%7D%2C%7B%22role%22%3A%22user%22%2C%22parts%22%3A%5B%7B%22richText%22%3A%22%3Cp%3ENow+for+the+Dec+10+-+12+Sick+leave%2C+I+need+to+split+it.+I+want+to+take+sick+leave+on+10th+and+vacation+on+12th.%3C%2Fp%3E%22%7D%5D%7D%2C%7B%22role%22%3A%22assistant%22%2C%22parts%22%3A%5B%7B%22richText%22%3A%22%3Cp%3ESAP+SuccessFactors+does+not+allow+direct+splitting+of+existing+PTOs.+I+can+modify+your+original+request+as+Sick+leave+on+%3Cstrong%3EDec+10%3C%2Fstrong%3E%2C+and+you+will+need+to+submit+a+new+Vacation+request+for+%3Cstrong%3EDec+12%3C%2Fstrong%3E.%3C%2Fp%3E%3Cul%3E%3Cli%3E%3Cp%3E%3Cstrong%3ELeave+Type%3A+Sickness%3C%2Fstrong%3E%3C%2Fp%3E%3C%2Fli%3E%3Cli%3E%3Cp%3E%3Cstrong%3EStart+Date%3A+Dec+10%3C%2Fstrong%3E%3C%2Fp%3E%3C%2Fli%3E%3Cli%3E%3Cp%3E%3Cstrong%3EEnd+Date%3A+Dec+10%3C%2Fstrong%3E%3C%2Fp%3E%3C%2Fli%3E%3C%2Ful%3E%3Cp%3E%3C%2Fp%3E%3Cp%3ECan+I+proceed+with+this+update%3F%3C%2Fp%3E%22%7D%2C%7B%22buttons%22%3A%5B%7B%22buttonText%22%3A%22Yes%22%2C%22style%22%3A%22filled%22%7D%2C%7B%22buttonText%22%3A%22Cancel%22%2C%22style%22%3A%22outlined%22%7D%5D%7D%5D%7D%2C%7B%22role%22%3A%22user%22%2C%22parts%22%3A%5B%7B%22richText%22%3A%22Yes%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%22Modifying+existing+request+and+creating+new+PTO+entry+in+%3Cb%3ESAP+SuccessFactors%3C%2Fb%3E...%22%2C%22connectorName%22%3A%22sap-success-factors%22%7D%5D%7D%2C%7B%22richText%22%3A%22%3Cp%3ESuccess%21+I%27ve+updated+the+first+part+of+your+time+off+to+Sick+leave.+Do+you+now+want+to+submit+a+new+Vacation+PTO+for+the+remaining+duration%3F%3C%2Fp%3E%22%7D%2C%7B%22citations%22%3A%5B%7B%22connectorName%22%3A%22sap-success-factors%22%2C%22citationTitle%22%3A%22Vacation%3A+Dec+10+%28Updated%29%22%7D%2C%7B%22connectorName%22%3A%22sap-success-factors%22%2C%22citationTitle%22%3A%22Vacation%3A+Dec+12+%28New%29%22%7D%5D%7D%5D%2C%22showFeedbackTray%22%3Atrue%7D%5D%7D
solution_tags:
- HR - Other
- HR - Time & Absence
systems:
- sap-success-factors
---
# Description
Enables employees to modify existing PTO entries—pending, upcoming or completed—while automatically applying the correct policy, approval, and payroll workflows.
# 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+need+to+modify+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%22Fetching+time-off+requests+from+%3Cb%3ESAP+SuccessFactors%3C%2Fb%3E...%22%2C%22connectorName%22%3A%22sap-success-factors%22%7D%5D%7D%2C%7B%22richText%22%3A%22%3Cp%3EI+found+2+upcoming+requests+in+%3Cstrong%3ESAP+SuccessFactors%3C%2Fstrong%3E.+Which+one+would+you+like+to+modify%3F%3C%2Fp%3E%3Cul%3E%3Cli%3E%3Cp%3E%3Cstrong%3ESick%3C%2Fstrong%3E%3A+Dec+10+-+Dec+12+%28Approved%29%3C%2Fp%3E%3C%2Fli%3E%3Cli%3E%3Cp%3E%3Cstrong%3EVacation%3C%2Fstrong%3E%3A+Dec+26+-+Dec+30+%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%22Can+you+change+the+Dec+26+-+30+vacation+to+Sick+leave+instead%3F%22%7D%5D%7D%2C%7B%22role%22%3A%22assistant%22%2C%22parts%22%3A%5B%7B%22richText%22%3A%22%3Cp%3EI+can+update+your+request+from+%3Cb%3EVacation%3C%2Fb%3E+to+%3Cb%3ESick+Leave%3C%2Fb%3E+in+%3Cb%3ESAP+SuccessFactors%3C%2Fb%3E.%3C%2Fp%3E%3Cul%3E%3Cli%3E%3Cb%3ERequest%3C%2Fb%3E%3A+Dec+26+-+Dec+30%3C%2Fli%3E%3Cli%3E%3Cb%3ENew+Type%3C%2Fb%3E%3A+Sick+Leave%3C%2Fli%3E%3C%2Ful%3E%3Cp%3E%3Cb%3EWould+you+like+to+proceed%3F%3C%2Fb%3E%3C%2Fp%3E%22%7D%2C%7B%22buttons%22%3A%5B%7B%22buttonText%22%3A%22Yes%22%2C%22style%22%3A%22filled%22%7D%2C%7B%22buttonText%22%3A%22Cancel%22%2C%22style%22%3A%22outlined%22%7D%5D%7D%5D%7D%2C%7B%22role%22%3A%22user%22%2C%22parts%22%3A%5B%7B%22richText%22%3A%22Yes%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%22Updating+request+type+in+%3Cb%3ESAP+SuccessFactors%3C%2Fb%3E...%22%2C%22connectorName%22%3A%22sap-success-factors%22%7D%5D%7D%2C%7B%22richText%22%3A%22Done%21+I%27ve+updated+the+request+type+to+Sick+Leave.%22%7D%5D%7D%2C%7B%22role%22%3A%22user%22%2C%22parts%22%3A%5B%7B%22richText%22%3A%22%3Cp%3ENow+for+the+Dec+10+-+12+Sick+leave%2C+I+need+to+split+it.+I+want+to+take+sick+leave+on+10th+and+vacation+on+12th.%3C%2Fp%3E%22%7D%5D%7D%2C%7B%22role%22%3A%22assistant%22%2C%22parts%22%3A%5B%7B%22richText%22%3A%22%3Cp%3ESAP+SuccessFactors+does+not+allow+direct+splitting+of+existing+PTOs.+I+can+modify+your+original+request+as+Sick+leave+on+%3Cstrong%3EDec+10%3C%2Fstrong%3E%2C+and+you+will+need+to+submit+a+new+Vacation+request+for+%3Cstrong%3EDec+12%3C%2Fstrong%3E.%3C%2Fp%3E%3Cul%3E%3Cli%3E%3Cp%3E%3Cstrong%3ELeave+Type%3A+Sickness%3C%2Fstrong%3E%3C%2Fp%3E%3C%2Fli%3E%3Cli%3E%3Cp%3E%3Cstrong%3EStart+Date%3A+Dec+10%3C%2Fstrong%3E%3C%2Fp%3E%3C%2Fli%3E%3Cli%3E%3Cp%3E%3Cstrong%3EEnd+Date%3A+Dec+10%3C%2Fstrong%3E%3C%2Fp%3E%3C%2Fli%3E%3C%2Ful%3E%3Cp%3E%3C%2Fp%3E%3Cp%3ECan+I+proceed+with+this+update%3F%3C%2Fp%3E%22%7D%2C%7B%22buttons%22%3A%5B%7B%22buttonText%22%3A%22Yes%22%2C%22style%22%3A%22filled%22%7D%2C%7B%22buttonText%22%3A%22Cancel%22%2C%22style%22%3A%22outlined%22%7D%5D%7D%5D%7D%2C%7B%22role%22%3A%22user%22%2C%22parts%22%3A%5B%7B%22richText%22%3A%22Yes%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%22Modifying+existing+request+and+creating+new+PTO+entry+in+%3Cb%3ESAP+SuccessFactors%3C%2Fb%3E...%22%2C%22connectorName%22%3A%22sap-success-factors%22%7D%5D%7D%2C%7B%22richText%22%3A%22%3Cp%3ESuccess%21+I%27ve+updated+the+first+part+of+your+time+off+to+Sick+leave.+Do+you+now+want+to+submit+a+new+Vacation+PTO+for+the+remaining+duration%3F%3C%2Fp%3E%22%7D%2C%7B%22citations%22%3A%5B%7B%22connectorName%22%3A%22sap-success-factors%22%2C%22citationTitle%22%3A%22Vacation%3A+Dec+10+%28Updated%29%22%7D%2C%7B%22connectorName%22%3A%22sap-success-factors%22%2C%22citationTitle%22%3A%22Vacation%3A+Dec+12+%28New%29%22%7D%5D%7D%5D%2C%22showFeedbackTray%22%3Atrue%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 **Modify PTO Request** 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 modify a PTO request through this plugin, employees must already have permission to edit their time off in SAP SuccessFactors—the same permissions required to edit PTO through the SuccessFactors UI.
At a minimum, end users must have:
- **Time Off permissions** that allow:
- Viewing available Time Off Types
- Editing Time Off / PTO requests
- Access to their own **employee profile and time account balances**
- Eligibility to edit PTO requests based on company time-off policies
**Note:** The plugin does not grant new permissions. It respects existing role-based permissions and policies granted to the user in SAP SuccessFactors.
### **b. API Permissions (via Integration User)**
The SuccessFactors connector uses a **integration user** **auth** to modify PTO requests through SAP SuccessFactors APIs.
That admin/integration user must have permissions to:
- Edit Time Off requests on behalf of employees
- Read Time Off Types and Time Account information
- Validate employee eligibility and balances (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
## 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 details (such as **User ID, name, and email**) from SAP SuccessFactors using the employee’s email address. The returned **User ID** is required for Modify PTO-related API call.
```bash
curl --location \
'https://<YOUR_SF_HOST>/odata/v2/User?$filter=email eq ''{{USER_EMAIL}}''&$select=userId,firstName,lastName,displayName,email&$top=50' \
--header 'Authorization: Bearer <ACCESS_TOKEN>' \
--header 'Accept: application/json'
```
**Query Parameters**
- `USER_EMAIL` *(string):* Email address of the employee whose SAP SuccessFactors user record needs to be retrieved.
- `$filter=email eq '{{USER_EMAIL}}'`: Filters the User entity to match the provided email address.
- `$select`: Limits the response to required user fields only:
- `userId`
- `firstName`
- `lastName`
- `displayName`
- `email`
- `$top=50`: Limits the response to a maximum of 50 records (email is typically unique).
### **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 --location \
'https://<YOUR_SF_HOST>/rest/timemanagement/absence/v1/availableTimeTypes?$at={{AS_OF_DATE}}' \
--header'Authorization: Bearer <ACCESS_TOKEN>' \
--header'Accept: 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: Retrieve Employee’s Pending and Approved PTO
This OData API retrieves an employee’s pending and approved PTO requests within a specified date range, restricted to limited leave types (as returned by API #2).
```bash
curl --request GET \
--url "https://<YOUR_SF_HOST>/odata/v2/EmployeeTime?$filter=(userId eq '{{userId}}') and (approvalStatus in 'PENDING','APPROVED') and (startDate ge datetime'{{minDate}}' and startDate le datetime'{{maxDate}}') and (timeTypeNav/externalCode in {{externalCode}})&$select=userId,startDate,endDate,timeTypeNav/externalCode,timeTypeNav/externalName_defaultValue,approvalStatus,userIdNav/defaultFullName,userIdNav/country,workflowRequestId,externalCode,createdDateTime,quantityInHours&$expand=userIdNav,timeTypeNav&$orderby=startDate asc" \
--header "Authorization: Bearer <ACCESS_TOKEN>" \
--header "Accept: application/json"
```
**Query Parameters:**
- `USER_ID` (*string)*: The employee’s user ID in SAP SuccessFactors.
- `MIN_DATE / MAX_DATE` (string): Format: `YYYY-MM-DD`
- Used to filter PTO requests within a specific date range.
- `approvalStatus`:
- Filters records to include:
- `PENDING`
- `APPROVED`
- `externalCode`:
- Used to filter PTO requests for limited leave types only (from API #2)
**Key Nuances:**
- **Returns Both Pending and Approved Requests**
- The API includes PTO requests that are:
- Awaiting approval (`PENDING`)
- Already approved (`APPROVED`)
- Rejected or cancelled requests are excluded unless explicitly added to the filter.
- **Date-Range Filtered Results**
- Only PTO requests within the specified start date range are returned.
- Adjusting the date window changes the visible PTO history.
- **Includes Workflow Metadata**
- Each record includes:
- Approval status
- Workflow request ID
- Leave type details
- Quantity (in hours)
- This enables downstream actions such as cancellation or workflow tracking.
### **API #4: Modify PTO Request**
This OData API is used to **modify a PTO request** in SAP SuccessFactors. It upserts an **Employee Time** record using the selected PTO type and date range, and triggers the existing approval workflow configured in SAP SuccessFactors.
```bash
curl --location --request POST \
'https://<YOUR_SF_HOST>/odata/v2/upsert' \
--header 'Authorization: Bearer <ACCESS_TOKEN>' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data-raw '{
"__metadata": {
"uri": "EmployeeTime('\''{{externalCode}}'\'')"
},
"timeType": "{{timeType}}",
"startDate": "{{startDate}}",
"endDate": "{{endDate}}"
}'
```
**API Body Parameters:**
- **externalCode** (*string*): Unique identifier of the `EmployeeTime` record. Used to determine whether to update an existing record or create a new one.
- **timeType** (*string*): The leave type external code (e.g., Vacation, Sick Leave) received from API #2.
- **startDate** (*datetime*): PTO start date. Passed in OData datetime format (e.g., `/Date(1735689600000)/`).
- **endDate** (*datetime*): PTO end date date. Passed in OData datetime format (e.g., `/Date(1735689600000)/`).
**Key Nuances:**
- **Upsert Behavior (Create or Update)**
- If `externalCode` exists → the PTO request is updated.
- If `externalCode` does not exist → a new PTO request is created.
- Operation is atomic per record (not bulk unless using `$batch`).
- **Validation Rules Apply**
- The request may fail if:
- The employee does not have sufficient balance.
- The leave overlaps with existing absences.
- The time type is not eligible for the employee.
- Workflow or approval rules are triggered.
- **Approval Workflow Impact**
- Updating certain fields (e.g., dates or leave type) may retrigger workflow approval depending on tenant configuration.
- **Date Format Requirement**
- API expects OData datetime format (`/Date(epoch)/`).
- Incorrect date formats result in validation errors.
### 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:
- Modify PTO requests for **limited leave types** (e.g., Vacation, Sick Leave, Casual Leave, Earned Leave, Comp Time).
- Specify PTO using **natural language date expressions**, such as:
- A specific date or date range
- Days of the week or weeks within a month
- Number of days within a given period
- Modify only a single PTO at a time.
- Modification PTO requests that respect **existing SAP SuccessFactors policies, validations, and approval workflows**.
- Allow modification and resubmission when a user wants to split an existing PTO request into multiple requests (e.g., change Dec 28–30 PTO to Dec 28 as Sick Leave and the remaining days as Vacation).
- Proactively surface **public holidays, weekends, or scheduled time-off conflicts** before modification.
# **What Is Out of Scope for This Plugin?**
This plugin does **not** support the following:
- Modification of PTO requests **on behalf of another employee**, including direct reports.
- Modification of PTO for **non-limited or leave-of-absence types**, such as parental leave, FMLA, or long-term disability.
- **Partial-day** or **hourly modifications** to existing PTO requests are not supported (e.g., half-day, first half/second half, or specific hours).
- Adding **comments or notes** to a PTO request.
- Viewing **complete PTO balances**, accrual schedules, or a full breakdown of all available leave types.
- Displaying detailed **approval chain** information.
- **Does not automatically submit PTO** if a user chooses to split an existing PTO request into multiple requests.