The time off policy object

Represents a company's rules for how hours accrue automatically on time off balances, and the limits, rollover, and waiting periods that apply.

🚧

Sandbox beta only

The Time Off API is in beta and is only available in Sandbox. For more details, see Working with Time Off Policies.

{
    "id": "top_4fKq8Wz1mN2pR7sT",
    "company": "com_sx3svU6K8c5ZkSFlOh5p",
    "label": "PTO — years 1-5",
    "status": "active",
    "policy_year": {
        "basis": "fixed_date",
        "date": "01-01"
    },
    "accrual_method": "per_payroll",
    "annual_grant_options": null,
    "per_payroll_options": {
        "hours_per_year": "120.00"
    },
    "per_hour_worked_options": null,
    "limits": {
        "max_balance": null,
        "min_balance": "0.00",
        "max_rollover": "80.00",
        "max_accrual_per_policy_year": null
    },
    "accrual_waiting_period_days": 90,
    "usage_waiting_period_days": 120,
    "metadata": {}
}
AttributeDescription
id
string
Unique identifier for the policy.
company
string
ID of the company the policy belongs to.
label
string
Name of the policy.
status
string
active or archived. This is the only field that can be changed after the policy is created.
policy_year
object
The annual cycle of the policy. basis is fixed_date to reset on the same calendar date for every employee, set in date as MM-DD, or enrollment to reset on the anniversary of each balance's first enrollment.
accrual_method
string
How hours accrue automatically. One of annual_grant, per_payroll, per_hour_worked, or none.
annual_grant_options
object
Settings for annual_grant policies, otherwise null. hours is granted on the first day of each policy year. partial_year_method is prorate or full, and controls the grant when an enrollment starts partway through a policy year.
per_payroll_options
object
Settings for per_payroll policies, otherwise null. hours_per_year is divided evenly across regular payrolls based on pay frequency. Off-cycle payrolls accrue only when off_cycle_options.apply_time_off_policies is true.
per_hour_worked_options
object
Settings for per_hour_worked policies, otherwise null. The employee accrues hours for every per_hours_worked hours worked. Overtime hours count only when include_overtime is true.
limits
object
max_balance, min_balance, max_rollover, and max_accrual_per_policy_year. A null limit isn't enforced.
accrual_waiting_period_days
integer
Days after the balance's first enrollment before automatic accrual starts. Changing policies doesn't restart it.
usage_waiting_period_days
integer
Days after the balance's first enrollment before spending hours stops returning a warning.
metadata
object
Additional loosely structured information to associate with the policy.
📘

All hour values are decimal strings, such as "40.00". A policy isn't tied to an earning type: the same policy can govern a PTO balance or a sick balance.