> ## Documentation Index
> Fetch the complete documentation index at: https://developer.rollfi.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Paid Time Off (PTO)

## 🔹 Overview

This guide covers the end-to-end Paid Time Off (PTO) flow using the Time Off APIs.

It includes:

* Policy setup
* Policy assignment
* Employee request lifecycle
* Approval workflow

***

## 🔹 1. Create a Time Off Policy

Use [addTimeOffPolicy](https://developer.rollfi.xyz/api-reference/adminportal/addTimeOffPolicy) to create a policy.

Required base fields for policy creation:

* companyId
* policyType
* policyName
* maxAccumulatedHours
* canCarryoverHours
* waitingPeriod
* whenTimeOffReceived (required for non-Unpaid Leave policies)
* earningMethod (required for non-Unpaid Leave policies)

Conditional fields by earningMethod:

* Lump Sum:

* lumpSumHoursEarned is required.

* Accrual:

* accrualRatePerHour is required.

* proratedByStartDate is required.

Carryover rule:

* If canCarryoverHours is true, maximumCarryoverHours is required.

***

## 🔹 2. Update an Existing Policy

Use [updateTimeOffPolicy](https://developer.rollfi.xyz/api-reference/adminportal/updateTimeOffPolicy) when you need to adjust a policy.

* Include timeOffPolicyId.
* If updating earningMethod, include the required conditional fields for that method in the same request.

***

## 🔹 3. Assign a Policy to an Employee

Use [addTimeOffPolicyAssignment](https://developer.rollfi.xyz/api-reference/adminportal/addTimeOffPolicyAssignment) to assign a policy.

Inputs:

* companyId
* timeOffPolicyId
* userId

Use [updateTimeOffPolicyAssignment](https://developer.rollfi.xyz/api-reference/adminportal/updateTimeOffPolicyAssignment) to adjust assignment balance. Accruals will continue based on the policy.

***

## 🔹 4. Employee Submits a PTO Request

Use [addTimeOffRequest](https://developer.rollfi.xyz/api-reference/userportal/addTimeOffRequest).

Inputs:

* companyId
* userId
* timeOffPolicyId
* startDate
* endDate
* requestReason

***

## 🔹 5. Employee Cancels or Deletes a Request

Use [cancelTimeOffRequest](https://developer.rollfi.xyz/api-reference/userportal/cancelTimeOffRequest) and [deleteTimeOffRequest](https://developer.rollfi.xyz/api-reference/userportal/deleteTimeOffRequest) for different lifecycle scenarios.

### When to use cancelTimeOffRequest

* Use this when a request has already been approved and needs to be reversed.
* This keeps the request in history and changes status to `Cancelled`.

📝 Note: Time off requests can be cancelled during PTO. The spent balance is removed, and the unspent balance is restored to the employee's account.

### When to use deleteTimeOffRequest

* Use this when a request is still pre-approval and should be removed from active workflows.
* Approved requests cannot be deleted; use `cancelTimeOffRequest` instead.

### ⚠️ Quick Rule

* Approved request: cancel it.
* Pending/denied draft-style request you want removed: delete it.

***

## 🔹 6. Approve a PTO Request

Use [approveTimeOffRequest](https://developer.rollfi.xyz/api-reference/adminportal/approveTimeOffRequest) to approve or change request status.

📝 Note: Send `isApproved: false` in `approveTimeOffRequest` to deny a PTO request.

***

## 📝 End-to-End Sequence

1. Create policy (addTimeOffPolicy)
2. Assign policy (addTimeOffPolicyAssignment)
3. Employee submits request (addTimeOffRequest)
4. Admin reviews/approves (approveTimeOffRequest)

Update or cancel requests as needed (updateTimeOffRequest, cancelTimeOffRequest, deleteTimeOffRequest).