---
availability: INSTALLABLE
description: Streamlines the time-off request process by allowing employees to submit, validate, and check the status of PTO through the AI Assistant.
installation_asset_uuid: ba9db61b-2a74-4d06-b636-2e9e8017bcec
name: Submit PTO Request
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%22%3Cp%3EI+want+to+take+time+off%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%3EI+can+help+you+with+that.+Could+you+please+provide+the+%3Cb%3Eleave+type%3C%2Fb%3E+%28e.g.%2C+Vacation%2C+Sick+Leave%29%2C+and+the+%3Cb%3Estart+and+end+dates%3C%2Fb%3E+for+your+request%3F%3C%2Fp%3E%22%7D%5D%7D%2C%7B%22role%22%3A%22user%22%2C%22parts%22%3A%5B%7B%22richText%22%3A%22I+want+to+submit+a+vacation+leave+from+Jan+25-27.+I+am+planning+for+a+trip+this+month.%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+leave+balance+and+dates+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%3EAlright%2C+I%27ve+prepared+your+request%3A%3C%2Fp%3E%3Cul%3E%3Cli%3E%3Cb%3ELeave+Type%3A%3C%2Fb%3E+Vacation%3C%2Fli%3E%3Cli%3E%3Cb%3EStart+Date%3A%3C%2Fb%3E+January+25%2C+2025%3C%2Fli%3E%3Cli%3E%3Cb%3EEnd+Date%3A%3C%2Fb%3E+January+27%2C+2025%3C%2Fli%3E%3C%2Ful%3E%3Cp%3EDoes+this+look+right%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%22Submitting+request+to+%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%3E%E2%9A%A0%EF%B8%8F+%3Cb%3EError+from+SAP+SuccessFactors%3A%3C%2Fb%3E+Your+request+could+not+be+submitted+because+of+a+scheduling+conflict.+You+already+have+an+approved+%27Personal+Day%27+on+January+25%2C+2025.+Please+correct+the+dates+and+try+again.%3C%2Fp%3E%22%7D%5D%7D%2C%7B%22role%22%3A%22user%22%2C%22parts%22%3A%5B%7B%22richText%22%3A%22Oh%2C+okay.+Let%27s+change+the+dates+to+January+28-30+instead.%22%7D%5D%7D%2C%7B%22role%22%3A%22assistant%22%2C%22parts%22%3A%5B%7B%22richText%22%3A%22%3Cp%3EUpdated.+I%27ll+submit+a+%3Cb%3EVacation%3C%2Fb%3E+request+for+%3Cb%3EJanuary+28%2C+2025%3C%2Fb%3E+to+%3Cb%3EJanuary+30%2C+2025%3C%2Fb%3E.+Ready+to+proceed%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%22Finalizing+request+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+Your+PTO+request+has+been+submitted+for+approval.%3C%2Fp%3E%3Cul%3E%3Cli%3E%3Cb%3ELeave+Type%3A%3C%2Fb%3E+Vacation%3C%2Fli%3E%3Cli%3E%3Cb%3EStart+Date%3A%3C%2Fb%3E+January+28%2C+2025%3C%2Fli%3E%3Cli%3E%3Cb%3EEnd+Date%3A%3C%2Fb%3E+January+30%2C+2025%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%22Time+Off+Request%3A+Vacation+%28Jan+28+-+Jan+30%29%22%7D%5D%7D%5D%7D%5D%7D
solution_tags:
- HR - Other
- HR - Time & Absence
systems:
- sap-success-factors
---
# Description
Streamlines the time-off request process by allowing employees to submit, validate, and check the status of PTO through the AI Assistant.
# 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%22%3Cp%3EI+want+to+take+time+off%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%3EI+can+help+you+with+that.+Could+you+please+provide+the+%3Cb%3Eleave+type%3C%2Fb%3E+%28e.g.%2C+Vacation%2C+Sick+Leave%29%2C+and+the+%3Cb%3Estart+and+end+dates%3C%2Fb%3E+for+your+request%3F%3C%2Fp%3E%22%7D%5D%7D%2C%7B%22role%22%3A%22user%22%2C%22parts%22%3A%5B%7B%22richText%22%3A%22I+want+to+submit+a+vacation+leave+from+Jan+25-27.+I+am+planning+for+a+trip+this+month.%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+leave+balance+and+dates+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%3EAlright%2C+I%27ve+prepared+your+request%3A%3C%2Fp%3E%3Cul%3E%3Cli%3E%3Cb%3ELeave+Type%3A%3C%2Fb%3E+Vacation%3C%2Fli%3E%3Cli%3E%3Cb%3EStart+Date%3A%3C%2Fb%3E+January+25%2C+2025%3C%2Fli%3E%3Cli%3E%3Cb%3EEnd+Date%3A%3C%2Fb%3E+January+27%2C+2025%3C%2Fli%3E%3C%2Ful%3E%3Cp%3EDoes+this+look+right%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%22Submitting+request+to+%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%3E%E2%9A%A0%EF%B8%8F+%3Cb%3EError+from+SAP+SuccessFactors%3A%3C%2Fb%3E+Your+request+could+not+be+submitted+because+of+a+scheduling+conflict.+You+already+have+an+approved+%27Personal+Day%27+on+January+25%2C+2025.+Please+correct+the+dates+and+try+again.%3C%2Fp%3E%22%7D%5D%7D%2C%7B%22role%22%3A%22user%22%2C%22parts%22%3A%5B%7B%22richText%22%3A%22Oh%2C+okay.+Let%27s+change+the+dates+to+January+28-30+instead.%22%7D%5D%7D%2C%7B%22role%22%3A%22assistant%22%2C%22parts%22%3A%5B%7B%22richText%22%3A%22%3Cp%3EUpdated.+I%27ll+submit+a+%3Cb%3EVacation%3C%2Fb%3E+request+for+%3Cb%3EJanuary+28%2C+2025%3C%2Fb%3E+to+%3Cb%3EJanuary+30%2C+2025%3C%2Fb%3E.+Ready+to+proceed%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%22Finalizing+request+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+Your+PTO+request+has+been+submitted+for+approval.%3C%2Fp%3E%3Cul%3E%3Cli%3E%3Cb%3ELeave+Type%3A%3C%2Fb%3E+Vacation%3C%2Fli%3E%3Cli%3E%3Cb%3EStart+Date%3A%3C%2Fb%3E+January+28%2C+2025%3C%2Fli%3E%3Cli%3E%3Cb%3EEnd+Date%3A%3C%2Fb%3E+January+30%2C+2025%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%22Time+Off+Request%3A+Vacation+%28Jan+28+-+Jan+30%29%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 **Submit 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 submit a PTO request through this plugin, employees must already have permission to request time off in SAP SuccessFactors—the same permissions required to submit PTO through the SuccessFactors UI.
At a minimum, end users must have:
- **Time Off permissions** that allow:
- Viewing available Time Off Types
- Creating Time Off / PTO requests
- Access to their own **employee profile and time account balances**
- Eligibility to submit 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 submit PTO requests through SAP SuccessFactors APIs.
That admin/integration user must have permissions to:
- Create 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 Submit 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: Submit PTO Request**
This OData API is used to submit a PTO request on behalf of an employee (via an integration user) in SAP SuccessFactors. It creates an **EmployeeTime** record using the specified PTO type and date range, and triggers the configured approval workflow in SAP SuccessFactors.
```bash
curl --location \
'https://<YOUR_SF_HOST>/odata/v2/EmployeeTime' \
--header'Authorization: Bearer <ACCESS_TOKEN>' \
--header'Content-Type: application/json' \
--header'Accept: application/json' \
--data '{
"userId": "{{USER_ID}}",
"startDate": "/Date({{START_DATE}})/",
"endDate": "/Date({{END_DATE}})/",
"timeType": "{{TIME_TYPE}}",
"userIdNav": {
"__metadata": {
"uri": "https://<YOUR_SF_HOST>/odata/v2/User(''{{USER_ID}}'')"
}
},
"timeTypeNav": {
"__metadata": {
"uri": "https://<YOUR_SF_HOST>/odata/v2/TimeType(externalCode=''{{TIME_TYPE}}'')"
}
}
}'
```
**API Body Parameters:**
- `USER_ID` *(string):* SAP SuccessFactors User ID of the employee requesting PTO (received from API #1).
- `START_DATE` *(string):* Start date of the PTO request, expressed as milliseconds since epoch (SAP OData date format).
- `END_DATE` *(string):* End date of the PTO request, expressed as milliseconds since epoch (SAP OData date format).
- `TIME_TYPE` *(string):* External code of the selected PTO time type (received from API #2).
**Key Nuances:**
- **Strict validation**
- PTO submission is fully validated by SuccessFactors.
- Requests may fail due to:
- Insufficient balance
- Overlapping time-off requests
- Invalid date ranges
- Policy restrictions
- **Date format requirements**
- Dates must be always provided in SAP’s OData date format (milliseconds since epoch). Ex: `/Date(14560000002)/`
- Incorrect formatting will result in request failure.
- **Approval workflows**
- Submitting a PTO request automatically triggers the existing approval workflow.
- The plugin does not bypass or modify approval chains.
- **No partial success**
- PTO requests are created atomically.
- If any validation fails, the request is not created.
- **Audit and ownership**
- The request is submitted using a technical integration user.
- SuccessFactors audit logs will reflect the system user, while the business context remains tied to the employee.
### 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:
- Submit PTO requests for **limited leave types** (e.g., Vacation, Sick Leave, Casual Leave, Earned Leave, Comp Time).
- Request PTO for **past, current, or future dates**, including unplanned absences.
- 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
- Submit **multiple PTO requests** within a single interaction (each request must be explicitly confirmed), provided all requests are for supported leave types.
- Be **warned when the requested PTO exceeds the available or projected balance** for the selected dates, so employees can avoid unintentionally requesting unpaid leave.
- Submit PTO requests that respect **existing SAP SuccessFactors policies, validations, and approval workflows**.
- Proactively surfacing **public holidays, weekends, or scheduled time-off conflicts** before submission.
# **What Is Out of Scope for This Plugin?**
This plugin does **not** support the following:
- Submitting PTO requests **on behalf of another employee**, including direct reports.
- Submitting **multiple PTO requests** **in bulk** with a single confirmation.
- Requesting **non-limited or leave-of-absence types**, such as parental leave, FMLA, or long-term disability.
- Submitting **partial-day or hourly PTO requests** (e.g., half-day, first half/second half, or specific hours).
- Adding **comments or notes** to a PTO request.
- Uploading or linking **supporting documentation** (e.g., for Jury Duty).
- Viewing **complete PTO balances**, accrual schedules, or a full breakdown of all available leave types.
- Displaying detailed **approval chain** information.
- Editing, canceling, or modifying existing PTO requests after submission.