Manage time off policies

Create, manage, and add employees to time off policies

To support our partners with and without time-tracking solutions, Gusto Embedded offers the ability to create and manage time off policies.

At this time, we only support vacation and sick policy types.

Prerequisites

Before using this guide, you must have created a company. If you haven’t done this yet, use the Quickstart guide to do so.

1. Create a time off policy

To create a time off policy use the POST companies/{company_uuid}/time_off_policies endpoint.

Accrual methods

Consult our Accrual methods guide for guidance on which body parameters to send, depending on the accrual method you’re selecting for the time off policy.

Sample request

bash

curl --request POST \
     --url https://api.gusto-demo.com/v1/companies/{company_uuid}/time_off_policies \
     --header 'accept: application/json' \
     --header 'authorization: Bearer <<COMPANY_API_TOKEN>>' \
     --header 'content-type: application/json' \
     --data '
{
     "name": "Intermission Policy",
     "policy_type": "vacation",
     "accrual_method": "per_hour_paid",
     "accrual_rate": "4.0",
     "accrual_rate_unit": "80.0",
     "paid_out_on_termination": true,
     "accrual_waiting_period_days": 30,
     "carryover_limit_hours": "200.0",
     "max_accrual_hours_per_year": "120.0",
     "max_hours": "240.0"
}
'

2. Add employees to a time off policy

Once the policies are created, you can add employees to a policy by using the PUT time_off_policies/{time_off_policy_uuid}/add_employees endpoint.

The path requires the parameter time_off_policy_uuid, which is the uuid of the time off policy you created in the previous step.

Note: To add an employee to a time off policy they must have a job created and must not be terminated.

Sample request

bash

curl --request PUT \
     --url https://api.gusto-demo.com/v1/time_off_policies/{time_off_policy_uuid}/add_employees \
     --header 'accept: application/json' \
     --header 'authorization: Bearer <<COMPANY_API_TOKEN>>' \
     --header 'content-type: application/json' \
     --data '
{
     "employee": [
          {
               "uuid": "56c672b4-3918-45cd-a3bb-a62ae0ff1307",
               "balance": "40.0"
          },
          {
               "uuid": "28e7a45d-32dd-4925-a82a-9a3ccc6d302c",
               "balance": "40.0"
          },
          {
               "uuid": "f60650da-ba18-417a-b2ab-3c9b6f0fe4f2",
               "balance": "20.0"
          }
     ]
}
'

Remove an employee from a time off policy

You can always remove an employee from a time off policy using the PUT time_off_policies/{time_off_policy_uuid}/remove_employees endpoint.

Deactivate a time off policy

Deactivate a time off policy using the PUT time_off_policies/{time_off_policy_uuid}/deactivate endpoint.

Sample request

bash

curl --request PUT \
     --url https://api.gusto-demo.com/v1/time_off_policies/time_off_policy_uuid/deactivate \
     --header 'accept: application/json'

Update a payroll with paid time off

To update a payroll with PTO hours taken during a pay period, policy_uuid and/or name can be passed on to the paid_time_off array object.

Not necessary for flows

For flows, this step is not necessary, as the PTO hours will be available to edit in the run_payroll flow directly.

Sample request

bash

curl --request PUT \
     --url https://api.gusto-demo.com/v1/companies/{company_id}/payrolls/{payroll_id} \
     --header 'accept: application/json' \
     --header 'authorization: Bearer <<COMPANY_API_TOKEN>>' \
     --header 'content-type: application/json' \
     --data '
{
     "employee_compensations": [
          {
               "hourly_compensations": [
                    {
                         "name": "Overtime",
                         "hours": "10.000",
                         "job_id": 2,
                         "job_uuid": "9d3760f0-d1f9-4700-8817-0fe2dce5cf23"
                    }
               ],
               "paid_time_off": [
                    {
                         "name": "Intermission Hours",
                         "hours": "8.000",
                         "policy_uuid": "1bad01e2-140c-49ed-9542-2388ce4a19b3"
                    }
               ],
               "employee_id": 1123581321345589,
               "employee_uuid": "187412e1-3dbe-491a-bb2f-2f40323a7067"
          }
     ],
     "version": "19289df18e6e20f797de4a585ea5a91535c7ddf7"
}
'

---

Time off policies

Accrual methods