---
updatedAt: 2026-06-08T14:09:05.000Z
---

Fetch the complete documentation index at: https://developer.connecteam.com/llms.txt. Use this file to discover all available pages before exploring further.

# Overview

The Time Off API enables you to manage time-off policies, user balances, and time-off requests programmatically. Integrate with your HR systems to automate leave management.

## Key Concepts

### Policy Types

Policy types are categories of time off (e.g., Vacation, Sick Leave, Personal Days). Each policy type can contain multiple policies with different accrual rules.

### Policies

Policies define the rules for a specific time-off type, including:

* Name (e.g., "Vacation - Full-time Employees")
* Unit (hours or days)
* Accrual and balance rules

### Balances

Each user assigned to a policy has a balance - the amount of time off available to them.

### Requests

Time-off requests are submitted by users (or on their behalf) and can be approved, pending, or denied.

***

## Available Endpoints

### Policy Types

| Method | Endpoint                  | Description                             |
| :----- | :------------------------ | :-------------------------------------- |
| GET    | /time-off/v1/policy-types | Get all policy types and their policies |

### Balances

| Method | Endpoint                                                   | Description                         |
| :----- | :--------------------------------------------------------- | :---------------------------------- |
| GET    | /time-off/v1/policy-types/{policyTypeId}/balances          | Get user balances for a policy type |
| PUT    | /time-off/v1/policy-types/{policyTypeId}/balances/{userId} | Update a user's balance             |

### Requests

| Method | Endpoint                          | Description               |
| :----- | :-------------------------------- | :------------------------ |
| GET    | /time-off/v1/requests             | Get time-off requests     |
| POST   | /time-off/v1/requests             | Create a time-off request |
| PUT    | /time-off/v1/requests/{requestId} | Update a time-off request |

### Policy Assignments

| Method | Endpoint                                                     | Description             |
| :----- | :----------------------------------------------------------- | :---------------------- |
| PUT    | /time-off/v1/time-off-policies/{timeOffPolicyId}/assignments | Assign user to a policy |

***

## Request Statuses

| Status     | Description                  |
| :--------- | :--------------------------- |
| `approved` | Request has been approved    |
| `pending`  | Request is awaiting approval |
| `denied`   | Request has been denied      |

***

## Balance Units

| Unit    | Description              |
| :------ | :----------------------- |
| `hours` | Balance tracked in hours |
| `days`  | Balance tracked in days  |

***

## Constraints

| Constraint           | Value                               |
| :------------------- | :---------------------------------- |
| Max balances per GET | 100                                 |
| Date format          | YYYY-MM-DD                          |
| Time format          | HH:MM:SS                            |
| Timezone             | Tz format (e.g., America/New\_York) |

***

## Authentication

All endpoints require authentication via API key or OAuth 2.0.

### Required Scopes

| Scope           | Operations                                          |
| :-------------- | :-------------------------------------------------- |
| time\_off.read  | GET policy types, GET balances, GET requests        |
| time\_off.write | PUT balances, POST/PUT requests, policy assignments |

***

## Workflow

1. **Get policy types** to understand available time-off categories
2. **Assign users to policies** with initial balances
3. **Create requests** for time off (as approved or pending)
4. **Retrieve requests** for a date range to sync with external systems
5. **Manage balances** by updating as needed

> 📝 Note
>
> Users must be assigned to a policy before you can create time-off requests or manage their balances for that policy type.

***

## Guide Pages

| Page                                                    | Description                                 |
| :------------------------------------------------------ | :------------------------------------------ |
| [Policy Types & Balances](time-off-policies-balances)   | Get policies and manage user balances       |
| [Get Time Off Requests](time-off-get-time-off-requests) | Retrieve time-off requests for a date range |
| [Time Off Requests](time-off-requests)                  | Create and update time-off requests         |
| [Policy Assignments](time-off-assignments)              | Assign users to policies                    |

***

[API Reference](https://developer.connecteam.com/reference/)