Time Off Policies

A time off policy defines the rules for how employees accrue and use paid time off: what they accrue against (hours worked, pay period, calendar month, etc.), how much, any waiting period before newly-accrued time can be used, and limits on balance and rollover. You can create multiple policies to cover different types of time off or different employee groups within a company.

Once a policy exists, employees are assigned to it (see employee setup) and start accruing time off under its rules. Employees submit time off requests against a policy's balance — see Time Off Requests and Time Off Balances for that side of the flow.

Auth

Requires a bearer access token (see How to Get API Access). Creating, listing, and reading policies requires a System-wide or Admin-level token — a call made with an employee-level token returns a 403.

Endpoints overview

Method	Name	Endpoint
POST	Create Time Off Policy	`https://api.worklio.com/wep/companies/{CLIENT_ID}/timeoff-policies`
GET	List Time Off Policies	`https://api.worklio.com/wep/companies/{CLIENT_ID}/timeoff-policies`
GET	Get Time Off Policy	`https://api.worklio.com/wep/companies/{CLIENT_ID}/timeoff-policies/{POLICY_ID}`
PUT	Deactivate Time Off Policy	`https://api.worklio.com/wep/companies/{CLIENT_ID}/timeoff-policy-deactivations/{POLICY_ID}`
GET	List Time Off Policy Presets	`https://api.worklio.com/wep/timeoff-policy-presets`

CLIENT_ID is the company identifier returned as id when you create the company. POLICY_ID is the policy identifier returned as id when you create a policy (below).

Create Time Off Policy

POST https://api.worklio.com/wep/companies/{CLIENT_ID}/timeoff-policies

You can create a policy two ways:

From a preset. Pass presetId alone.
From scratch. Pass presetId alongside other fields. If otherfields are present, every field you send rewrites field in preset. Call List Time Off Policy Presets first to see the available presets and their values.

Request fields

Field	Type	Required	Description
`presetId`	integer \| null	See above	ID of a preset from List Time Off Policy Presets. If present, all other fields below are ignored and the policy is created from the preset's values instead.
`name`	string \| null	No	Name of the policy.
`accrualYearType`	integer (enum)	Yes	When the accrual year begins. See Accrual Year Type values below.
`accrualYearStartOnMonth`	integer \| null	Required if `accrualYearType` is `1`	Month (`1`–`12`) the accrual year starts on. Only applies to `accrualYearType: 1` (Calendar Year).
`accrualStartOnDelay`	integer \| null (≥ 0)	No	Days after hire before a new employee starts accruing time off under this policy.
`accrualAvailableOnDelay`	integer \| null (≥ 0)	No	Days after hire before a new employee can use time off they've already accrued under this policy.
`serviceYear`	object	Yes	Accrual amount and limits. See Service Year object below.
`legislative`	integer (enum)	No	Legislative region this policy applies to. See Legislative values below.

Service Year object

Field	Type	Required	Description
`accrualAmount`	number (0–1000)	Yes	Hours accrued per period, where the period is defined by `periodLength`/`periodUnit`.
`periodLength`	integer (1–31000)	Yes	Number of `periodUnit` units per accrual period.
`periodUnit`	integer (enum)	Yes	The unit `periodLength` is counted in. See Period Unit values below.
`annualLimit`	number \| null	No	Maximum hours an employee can accrue under this policy within one accrual year.
`balanceLimit`	number \| null	No	Maximum hours an employee can have available at any time under this policy.
`rolloverLimit`	number \| null	No	Maximum hours that carry over into the next accrual year.

Accrual Year Type values

Value	Name	Meaning
1	`CalendarYear`	Accrual year runs on a fixed calendar schedule, starting on `accrualYearStartOnMonth`.
2	`EmploymentAnniversary`	Accrual year is anchored to each employee's hire date.

Period Unit values

Value	Name
1	`HoursWorked`
2	`PayPeriod`
3	`CalendarMonthFirstDay`
4	`AccrualYearFirstDay`
5	`CalendarMonthLastDay`
6	`CalendarQuarterFirstDay`
7	`CalendarQuarterLastDay`
8	`RolloverYear_DailyAccruals`

Legislative values

Value	Name
1	`US`
255	`Global`

Example requests and their responses

require("dotenv").config();

const TOKEN = process.env.API_KEY;
const CLIENT_ID = process.env.CLIENT_ID;
const url = `https://api.worklio.com/wep/companies/${CLIENT_ID}/timeoff-policies`;

// Using a preset — call "List Time Off Policy Presets" first to get a presetId
const payload = {
  presetId: 1,
  name: "MY POLICY"
};

async function createTimeOffPolicy() {
  const response = await fetch(url, {
    method: "POST",
    headers: {
      accept: "application/json",
      "api-version": "2.0",
      authorization: `Bearer ${TOKEN}`,
      "content-type": "application/json",
      "x-api-version": "2.0"
    },
    body: JSON.stringify(payload)
  });

  console.log(response.status);
  console.log(await response.text());
}

createTimeOffPolicy();

curl -s -X POST "https://api.worklio.com/wep/companies/$CLIENT_ID/timeoff-policies" \
  -H "accept: application/json" \
  -H "api-version: 2.0" \
  -H "authorization: Bearer $API_KEY" \
  -H "content-type: application/json" \
  -H "x-api-version: 2.0" \
  -d '{
    "presetId": 1,
    "name": "MY POLICY"
  }' | jq .

{
  "accrualYearType": 1,
  "accrualYearStartOnMonth": 1,
  "accrualStartOnDelay": 0,
  "accrualAvailableOnDelay": 90,
  "serviceYear": {
    "accrualAmount": 80,
    "periodLength": 1,
    "periodUnit": 4,
    "balanceLimit": 80,
    "rolloverLimit": 0
  },
  "employeeRules": [],
  "id": 61,
  "code": "PTO_1",
  "name": "MY POLICY",
  "payCodeType": 1,
  "legislative": 1
}

require("dotenv").config();

const TOKEN = process.env.API_KEY;
const CLIENT_ID = process.env.CLIENT_ID;
const url = `https://api.worklio.com/wep/companies/${CLIENT_ID}/timeoff-policies`;

// Using a preset — call "List Time Off Policy Presets" first to get a presetId
const payload = {
  presetId: 1,
  "name": "Standard PTO",
  "accrualYearType": 1,
  "accrualYearStartOnMonth": 1,
  "accrualStartOnDelay": 0,
  "accrualAvailableOnDelay": 90,
  "serviceYear": {
    "accrualAmount": 6.67,
    "periodLength": 1,
    "periodUnit": 2,
    "annualLimit": 80,
    "balanceLimit": 80,
    "rolloverLimit": 0
  },
  "legislative": 1
};

async function createTimeOffPolicy() {
  const response = await fetch(url, {
    method: "POST",
    headers: {
      accept: "application/json",
      "api-version": "2.0",
      authorization: `Bearer ${TOKEN}`,
      "content-type": "application/json",
      "x-api-version": "2.0"
    },
    body: JSON.stringify(payload)
  });

  console.log(response.status);
  console.log(await response.text());
}

createTimeOffPolicy();

curl -s -X POST "https://api.worklio.com/wep/companies/$CLIENT_ID/timeoff-policies" \
  -H "accept: application/json" \
  -H "api-version: 2.0" \
  -H "authorization: Bearer $API_KEY" \
  -H "content-type: application/json" \
  -H "x-api-version: 2.0" \
  -d '{
    "presetId": 1,
    "name": "Standard PTO",
    "accrualYearType": 1,
    "accrualYearStartOnMonth": 1,
    "accrualStartOnDelay": 0,
    "accrualAvailableOnDelay": 90,
    "serviceYear": {
      "accrualAmount": 6.67,
      "periodLength": 1,
      "periodUnit": 2,
      "annualLimit": 80,
      "balanceLimit": 80,
      "rolloverLimit": 0
    },
    "legislative": 1
  }' | jq .

{
  "accrualYearType": 1,
  "accrualYearStartOnMonth": 1,
  "accrualStartOnDelay": 0,
  "accrualAvailableOnDelay": 90,
  "serviceYear": {
    "accrualAmount": 6.67,
    "periodLength": 1,
    "periodUnit": 2,
    "annualLimit": 80,
    "balanceLimit": 80,
    "rolloverLimit": 0
  },
  "employeeRules": [],
  "id": 62,
  "code": "PTO_2",
  "name": "Standard PTO",
  "payCodeType": 1,
  "legislative": 1
}

id is the policy's unique identifier — this is the POLICY_ID used in the other endpoints below, and what you'll assign employees to.

code is a short policy code Worklio generates automatically (e.g. PTO_1); it isn't a request field.

payCodeType identifies the pay code this policy's hours are transferred to in a payroll run. It's set from the preset (or company defaults) rather than passed directly in the request — it isn't in the request fields list above.

List Time Off Policies

GET https://api.worklio.com/wep/companies/{CLIENT_ID}/timeoff-policies

Returns an array of the company's time off policies.

Get Time Off Policy

GET https://api.worklio.com/wep/companies/{CLIENT_ID}/timeoff-policies/{POLICY_ID}

Returns a single policy by id.

Deactivate Time Off Policy

PUT https://api.worklio.com/wep/companies/{CLIENT_ID}/timeoff-policy-deactivations/{POLICY_ID}

Deactivates a policy. A successful call returns the deactivated policy.

List Time Off Policy Presets

GET https://api.worklio.com/wep/timeoff-policy-presets

require("dotenv").config();
const TOKEN = process.env.API_KEY
const CLIENT_ID = process.env.CLIENT_ID
const url  = `https://api.worklio.com/wep/timeoff-policy-presets`; 



async function listTimeoffPresets() {
  const response = await fetch(url, {
    method: "GET",
    headers: {
      accept: "application/json",
      "api-version": "2.0",
      authorization: `Bearer ${TOKEN}`,
      "content-type": "application/json",
      "x-api-version": "2.0"
    },
  });


  console.log(response.status);
  const raw = await response.text();
  console.log(JSON.stringify(JSON.parse(raw), null, 2));

}

listTimeoffPresets();

Example response

{
  "items": [
    {
      "id": 1,
      "name": "Vacation",
      "code": "PTO",
      "payCodeType": 1,
      "accrualYearType": 1,
      "accrualYearStartOnMonth": 1,
      "accrualStartOnDelay": 0,
      "accrualAvailableOnDelay": 90,
      "serviceYear": {
        "accrualAmount": 80,
        "periodLength": 1,
        "periodUnit": 4,
        "balanceLimit": 80,
        "rolloverLimit": 0
      }
    },
    {
      "id": 2,
      "name": "Sick Time",
      "code": "SICK",
      "payCodeType": 2,
      "accrualYearType": 1,
      "accrualYearStartOnMonth": 1,
      "accrualStartOnDelay": 0,
      "accrualAvailableOnDelay": 90,
      "serviceYear": {
        "accrualAmount": 24,
        "periodLength": 1,
        "periodUnit": 4,
        "balanceLimit": 24
      }
    },
    {
      "id": 3,
      "name": "Unpaid Time Off",
      "code": "UNPAID",
      "payCodeType": 4,
      "accrualYearType": 1,
      "accrualYearStartOnMonth": 1,
      "accrualStartOnDelay": 0,
      "accrualAvailableOnDelay": 90,
      "serviceYear": {
        "accrualAmount": 90,
        "periodLength": 1,
        "periodUnit": 4
      }
    },
    {
      "id": 4,
      "name": "TEST RULE",
      "code": "TEST",
      "payCodeType": 3,
      "accrualYearType": 2,
      "accrualStartOnDelay": 0,
      "accrualAvailableOnDelay": 0,
      "serviceYear": {
        "accrualAmount": 1,
        "periodLength": 1,
        "periodUnit": 1,
        "annualLimit": 1,
        "balanceLimit": 1
      }
    }
  ]
}

Returns the available presets and their policy values, for use as presetId when creating a policy.