Sign in

v1

latestOpenAPI 3.1.02026-07-243113441.2 MB
Time Off Policies

Create a time off policy

Create a time off policy

scope: time_off_policies:write

post/v1/companies/{company_uuid}/time_off_policies

Path parameters

company_uuidstring required

The UUID of the company

Headers

X-Gusto-API-Version'2026-06-15'

Determines the date-based API version associated with your API call. If none is provided, your application's minimum API version is used.

Request body

namestring required

Name of the time off policy

policy_type'vacation' | 'sick' required

Type of the time off policy. Currently only "vacation" and "sick" are supported

accrual_method'unlimited' | 'per_pay_period' | 'per_calendar_year' | 'per_anniversary_year' | 'per_hour_worked' | 'per_hour_worked_no_overtime' | 'per_hour_paid' | 'per_hour_paid_no_overtime' required

Accrual method of the time off policy

accrual_ratestring nullable

The rate at which the time off hours will accrue for an employee on the policy. Represented as a float, e.g. "40.0".

accrual_rate_unitstring nullable

The number of hours an employee has to work or be paid for to accrue the number of hours set in the accrual rate. Only used for hourly policies (per_hour_paid, per_hour_paid_no_overtime, per_hour_work, per_hour_worked_no_overtime). Represented as a float, e.g. "40.0".

paid_out_on_terminationboolean

Boolean representing if an employee's accrued time off hours will be paid out on termination. If accrual_method is unlimited, then paid_out_on_termination must be false.

accrual_waiting_period_daysinteger nullable

Number of days before an employee on the policy will begin accruing time off hours. If accrual_method is per_anniversary_year, per_calendar_year, or unlimited, then accrual_waiting_period_days should be 0.

carryover_limit_hoursstring nullable

The max number of hours an employee can carryover from one year to the next. If accrual_method is unlimited, then carryover_limit_hours must be blank.

max_accrual_hours_per_yearstring nullable

The max number of hours an employee can accrue in a year. If accrual_method is yearly (per_anniversary_year, per_calendar_year) or unlimited, then max_accrual_hours_per_year must be blank.

max_hoursstring nullable

The max number of hours an employee can accrue. If accrual_method is unlimited, then max_hours must be blank.

policy_reset_datestring nullable

The date the policy resets. Format MM-DD

completeboolean

boolean representing if a policy has completed configuration

Example request

{
  "name": "Vacation Policy"
}

Response

created

uuidstring required

Unique identifier of a time off policy

company_uuidstring required

Unique identifier for the company owning the time off policy

namestring required

Name of the time off policy

policy_type'vacation' | 'sick' | 'bereavement' | 'custom' | 'floating_holiday' | 'jury_duty' | 'learning_and_development' | 'parental_leave' | 'personal_day' | 'volunteer' | 'weather' required

Type of the time off policy. Only "vacation" and "sick" can be created through the API, but other types may be present if the company was previously a Gusto.com customer.

accrual_methodstring required

Policy time off accrual method

accrual_ratestring float nullable

The rate at which the time off hours will accrue for an employee on the policy. Represented as a float, e.g. "40.0".

accrual_rate_unitstring float nullable

The number of hours an employee has to work or be paid for to accrue the number of hours set in the accrual rate. Only used for hourly policies (per_hour_paid, per_hour_paid_no_overtime, per_hour_work, per_hour_worked_no_overtime). Represented as a float, e.g. "40.0".

paid_out_on_terminationboolean

Boolean representing if an employee's accrued time off hours will be paid out on termination

accrual_waiting_period_daysinteger nullable

Number of days before an employee on the policy will begin accruing time off hours

carryover_limit_hoursstring float nullable

The max number of hours an employee can carryover from one year to the next

max_accrual_hours_per_yearstring float nullable

The max number of hours an employee can accrue in a year

max_hoursstring float nullable

The max number of hours an employee can accrue

policy_reset_datestring nullable

The date the policy resets. Format MM-DD

completeboolean

boolean representing if a policy has completed configuration

versionstring nullable

The current version of the object. See the versioning guide for information on how to use this field. The version will be null if the policy is no longer active.

is_activeboolean required

boolean representing if a policy is active or not