Skip to main content

​
🔹 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 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 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 to assign a policy. Inputs:
  • companyId
  • timeOffPolicyId
  • userId
Use updateTimeOffPolicyAssignment to adjust assignment balance. Accruals will continue based on the policy.

​
🔹 4. Employee Submits a PTO Request

Use addTimeOffRequest. Inputs:
  • companyId
  • userId
  • timeOffPolicyId
  • startDate
  • endDate
  • requestReason

​
🔹 5. Employee Cancels or Deletes a Request

Use cancelTimeOffRequest and 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 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).