Employee TimeOff Policy Setup

Before an employee can accrue time off or submit time off requests, they must be enrolled in a time off policy. This page covers enrolling an employee in a policy and retrieving the policies an employee is currently enrolled in, along with their balances.

Auth

Requires a bearer access token (see How to Get API Access). Both endpoints on this page require a System-wide or Admin-level token.

Endpoints overview

Method	Name	Endpoint
POST	Assign Employee to Time Off Policy	`https://api.worklio.com/wep/companies/{CLIENT_ID}/employees/{EMPLOYEE_ID}/timeoff-policy-setups/{TIMEOFF_POLICY_ID}`
GET	List Employee's Time Off Policies	`https://api.worklio.com/wep/companies/{CLIENT_ID}/employees/{EMPLOYEE_ID}/timeoff-policies`

CLIENT_ID is the company identifier returned as id when you create the company. EMPLOYEE_ID is the employee identifier returned as id when you create the employee. TIMEOFF_POLICY_ID is the policy identifier returned as id when you create a time off policy.

Assign Employee to Time Off Policy

POST https://api.worklio.com/wep/companies/{CLIENT_ID}/employees/{EMPLOYEE_ID}/timeoff-policy-setups/{TIMEOFF_POLICY_ID}

Enrolls the employee in the policy so they start accruing time off under its rules.

Request fields

Field	Type	Required	Description
`ruleStartDate`	string (date, `YYYY-MM-DD`)	Yes	Date the employee starts accruing under this policy's rules.

Example request

require("dotenv").config();

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

const payload = {
  ruleStartDate: "2026-09-11"
};

async function assignEmployeeToTimeOffPolicy() {
  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());
}

assignEmployeeToTimeOffPolicy();

curl -s -X POST "https://api.worklio.com/wep/companies/$CLIENT_ID/employees/$EMPLOYEE_ID/timeoff-policy-setups/$TIMEOFF_POLICY_ID" \
  -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 '{
    "ruleStartDate": "2026-09-11"
  }' | jq .

Example response

{
  "id": 14,
  "policyId": 63,
  "code": "PTO_3",
  "name": "Standard PTO",
  "currentRolloverYearBeginsOn": "2026-01-01",
  "currentBalance": 0,
  "availableBalance": 0,
  "totalHoursWorked": 0,
  "totalHoursUsed": 0,
  "totalHoursAccrued": 0,
  "hoursRolledOver": 0,
  "annualLimitLoss": 0,
  "balanceLimitLoss": 0,
  "payPeriodLimitLoss": 0,
  "usageLimitLoss": 0,
  "ruleStartDate": "2026-09-11",
  "hireDateRule": "2026-09-11",
  "participationLimits": {
    "accrualRate": {
      "value": 100,
      "isOverridden": false
    },
    "annualLimit": {
      "value": 100,
      "isOverridden": false
    },
    "balanceLimit": {
      "value": 100,
      "isOverridden": false
    },
    "usageLimit": {
      "value": 100,
      "isOverridden": false
    },
    "rolloverLimit": {
      "value": 100,
      "isOverridden": false
    }
  }
}

Error response

{
  "status": 0,
  "code": "400",
  "errorCode": "EmployeeHasAnyTimeOffPolicy",
  "message": "9/17/2026 - 2:58:52 PM : Active Policy for this Employee Already Exists",
  "stackTrace": "",
  "pagination": {
    "pageNo": 0,
    "pageSize": 0,
    "totalRecords": 0,
    "totalPages": 0,
    "dataToken": ""
  },
  "validationErrors": null
}

Returned when the employee already has an active policy enrollment — an employee can only be enrolled in one policy at a time.

List Employee's Time Off Policies

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

Returns the policies an employee is enrolled in, with their current balances.

Example request

require("dotenv").config();

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

async function listEmployeeTimeOffPolicies() {
  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);
  console.log(await response.text());
}

listEmployeeTimeOffPolicies();

curl -s -X GET "https://api.worklio.com/wep/companies/$CLIENT_ID/employees/$EMPLOYEE_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" | jq .

Example response

[
  {
    "id": 13,
    "policyId": 60,
    "policyName": "TEST",
    "policyAccrualAmount": 80,
    "policyPeriodUnit": 4,
    "existData": true,
    "balanceUpdatedThrough": "2026-09-16T00:00:00Z",
    "annualEntitlement": 4800,
    "balance": 300,
    "availableBalance": 300,
    "totalUsed": 0
  },
  {
    "id": 14,
    "policyId": 63,
    "policyName": "Standard PTO",
    "policyAccrualAmount": 6.67,
    "policyPeriodUnit": 2,
    "existData": true,
    "balanceUpdatedThrough": "2026-09-11T00:00:00Z",
    "annualEntitlement": 4800,
    "balance": 0,
    "availableBalance": 0,
    "totalUsed": 0
  }
]

Returns an array, one entry per policy the employee is enrolled in.

Response fields

Field	Type	Description
`id`	integer	Unique identifier for this policy enrollment — matches the `id` returned by Assign Employee to Time Off Policy.
`policyId`	integer	The time off policy's id.
`policyName`	string	The policy's name.
`policyAccrualAmount`	number	The policy's `serviceYear.accrualAmount` (see Time Off Policies).
`policyPeriodUnit`	integer (enum)	The policy's accrual period unit — see Period Unit values in Time Off Policies.
`existData`	boolean	Whether balance data exists for this enrollment.
`balanceUpdatedThrough`	string (date)	Date through which the balance figures below were last calculated.
`annualEntitlement`	number	Minutes the employee is entitled to accrue this accrual year under the policy.
`balance`	number	Employee's current accrued balance, in minutes.
`availableBalance`	number	Minutes currently available for the employee to use.
`totalUsed`	number	Total minutes used under this policy to date.