Time Off Policies

Time Off Policies provide detailed instructions and guidelines that outline the terms for which employees are entitled to take time away from work. You can set up multiple policies to guide your company's various time off. The policies also provide employees with a fair, structured approach to managing their time away from work.

Endpoints Overview

In setting up and managing your company time off policies, you call the following endpoints for different actions. The endpoints are:

Common Use Cases

The common use cases for calling the various time-off policies endpoints include the following:

Creating a Time Off Policy

Use the create time off policy to create your company's Time off policy. When calling the create policy endpoint, specify the preset ID from the Time Off policy presets list as a body parameter. Adding the presetID means the system sets all policy values according to the selected preset.

To get the list of policy presets and their policy details, call the list of preset endpoint. If you specify other information for a policy alongside a PresetID, the system ignores all the other details and will use only the policy details from the presetID.

Other body parameters to define when creating a time off policy include the following:

• Name - Specify the policy's name
• Accrual Year Type: Choose from two options: Calendar Year or Employment Anniversary, and specify when the time off accruals should begin.
• Accrual Year Start On Month - Select the month when the time off accruals should start.
• Accrual Available On Delay - Define how long a new employee must wait before using their accrued time off.
• Accrual Start On Delay - Specify when the accrual starts for a new employee.

A successful call returns a 201 response code indicating you created your time off policy. The call returns the following essential items as an object:

• PolicyID
• Name - Name of the policy
• Valid To - Expiration date of the policy.
• PayCode Type - Define under which pay code the time off hours from the selected policy will be transferred to the payroll run.
• Accrual Year Type - Definition for when the time off accruals should begin.

Reference other 201 response objects in the API reference docs.

📘

NOTE

Only a System-wide and Admin level user can call this endpoint, with an employee call returning a forbidden request.

Retrieving Time Off Policies

To get the list of your company's time off policies, call the get list of time off policies. This call returns an array of objects with details that include:

• Name - Name of the policy.
• Valid To - Expiration date of the policy.
• Pay Code Type - Define under which pay code the time Off hours from the selected policy will be transferred to the payroll run.

You can also retrieve specific time off policy information for particular companies and policyID by calling this endpoint. This means that it is paramount to specify both the companyID and policyID as path parameters.

📘

NOTE

Only a System and Admin level users can call these endpoints.

Deleting a Time Off Policy

You can deactivate any of your company's time off policies by calling the deactivate TimeOff policy. To deactivate a particular policy, you must specify the companyID and policyID in the path parameters of your request. A successful call returns an object containing information about the policy you want to deactivate.