GuidesAPI ReferenceChangelogAPI PolicyGusto Security
Guides
Start typing to search…

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

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"
}
'
const fetch = require('node-fetch');

const url = 'https://api.gusto-demo.com/v1/companies/{company_uuid}/time_off_policies';
const options = {
  method: 'POST',
  headers: {
    accept: 'application/json',
    'content-type': 'application/json',
    authorization: 'Bearer <<COMPANY_API_TOKEN>>'
  },
  body: JSON.stringify({
    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'
  })
};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error('error:' + err));

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

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"
          }
     ]
}
'
const fetch = require('node-fetch');

const url = 'https://api.gusto-demo.com/v1/time_off_policies/{time_off_policy_uuid}/add_employees';
const options = {
  method: 'PUT',
  headers: {
    accept: 'application/json',
    'content-type': 'application/json',
    authorization: 'Bearer <<COMPANY_API_TOKEN>>'
  },
  body: JSON.stringify({
    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'}
    ]
  })
};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error('error:' + err));

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.

🚧

This is not a deletion

This call deactivates a time off policy, but does not delete it.

If a new time off policy is created with a name previously used for a deactivated time off policy, this reactivates the previous time off policy and uses the previous UUID.

Sample request

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

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"
}
'
const fetch = require('node-fetch');

const url = 'https://api.gusto-demo.com/v1/companies/{company_uuid}/payrolls/{pay_period_start_date}/{pay_period_end_date}';
const options = {
  method: 'PUT',
  headers: {
    accept: 'application/json',
    'content-type': 'application/json',
    authorization: 'Bearer <<COMPANY_API_TOKEN>>'
  },
  body: JSON.stringify({
    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'
  })
};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error('error:' + err));

Updated 7 days ago