---
updatedAt: 2026-10-19T12:34:37.000Z
agentTools:
  projectIndex: https://apidocs.worklio.com/llms.txt
---

# Employee TimeOff Policy Setup

Before an employee can accrue time off or submit [time off requests](https://apidocs.worklio.com/docs/timeoff-requests), they must be enrolled in a [time off policy](https://apidocs.worklio.com/docs/timeoff-policies). 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](https://apidocs.worklio.com/docs/getting-an-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](https://apidocs.worklio.com/docs/create-a-company). `EMPLOYEE_ID` is the employee identifier returned as `id` when you [create the employee](https://apidocs.worklio.com/docs/create-an-employee). `TIMEOFF_POLICY_ID` is the policy identifier returned as `id` when you [create a time off policy](https://apidocs.worklio.com/docs/timeoff-policies).

## 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

```javascript Node.js
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
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

```json 201 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

```json 400 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

```javascript Node.js
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
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

```json 200 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.&#x20;

### 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](/timeoff-policies)).                          |
| `policyPeriodUnit`      | integer (enum) | The policy's accrual period unit — see Period Unit values in [Time Off Policies](/timeoff-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.                                                                   |