---
updatedAt: 2026-07-13T09:16:22.000Z
---

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

# Policy Types & Balances

Retrieve policy types to understand your organization's time-off structure, and manage user balances.

## Endpoints

| Method | Endpoint                                                   | Description          |
| :----- | :--------------------------------------------------------- | :------------------- |
| GET    | /time-off/v1/policy-types                                  | Get all policy types |
| GET    | /time-off/v1/policy-types/{policyTypeId}/balances          | Get user balances    |
| PUT    | /time-off/v1/policy-types/{policyTypeId}/balances/{userId} | Update user balance  |

***

## Get Policy Types

Retrieve all policy types and their associated policies.

### Example Request

```bash
curl --request GET \
  --url https://api.connecteam.com/time-off/v1/policy-types \
  --header 'X-API-KEY: YOUR_API_KEY'
```

### Response

```json
{
  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "data": {
    "policyTypes": [
      {
        "id": "pt-vacation-001",
        "name": "Vacation",
        "policies": [
          {
            "id": "pol-vac-ft-001",
            "name": "Vacation - Full-time",
            "unit": "days",
            "accrualType": "fixed"
          },
          {
            "id": "pol-vac-pt-001",
            "name": "Vacation - Part-time",
            "unit": "hours",
            "accrualType": "fixed"
          }
        ]
      },
      {
        "id": "pt-sick-001",
        "name": "Sick Leave",
        "policies": [
          {
            "id": "pol-sick-001",
            "name": "Sick Leave - All Employees",
            "unit": "hours",
            "accrualType": "hourly"
          }
        ]
      }
    ]
  }
}
```

### Response Fields

**Policy Type:**

| Field    | Type   | Description                       |
| :------- | :----- | :-------------------------------- |
| id       | string | Unique policy type identifier     |
| name     | string | Policy type display name          |
| policies | array  | List of policies within this type |

**Policy:**

| Field       | Type   | Description                                            |
| :---------- | :----- | :----------------------------------------------------- |
| id          | string | Unique policy identifier (use for assignments)         |
| name        | string | Policy display name                                    |
| unit        | string | Balance unit: `hours` or `days`                        |
| accrualType | string | Policy accrual type: `fixed`, `hourly`, or `unlimited` |

> 📝 Save Policy IDs
>
> Store the `policyTypeId` for balance operations and the policy `id` for user assignments.

***

## Get User Balances

Retrieve time-off balances for users within a policy type.

### Path Parameters

| Parameter    | Type   | Required | Description        |
| :----------- | :----- | :------- | :----------------- |
| policyTypeId | string | Yes      | The policy type ID |

### Query Parameters

| Parameter | Type    | Required | Default | Description                 |
| :-------- | :------ | :------- | :------ | :-------------------------- |
| userIds   | array   | No       | -       | Filter by specific user IDs |
| limit     | integer | No       | 10      | Results per page (1-100)    |
| offset    | integer | No       | 0       | Pagination offset           |

### Example: Get All Balances

```bash
curl --request GET \
  --url 'https://api.connecteam.com/time-off/v1/policy-types/pt-vacation-001/balances?limit=50' \
  --header 'X-API-KEY: YOUR_API_KEY'
```

### Example: Get Specific Users

```bash
curl --request GET \
  --url 'https://api.connecteam.com/time-off/v1/policy-types/pt-vacation-001/balances?userIds=9170357&userIds=9170358' \
  --header 'X-API-KEY: YOUR_API_KEY'
```

### Response

```json
{
  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "data": {
    "balances": [
      {
        "userId": 9170357,
        "units": "days",
        "balance": 15.5,
        "policyId": "pol-vac-ft-001"
      },
      {
        "userId": 9170358,
        "units": "days",
        "balance": 12.0,
        "policyId": "pol-vac-ft-001"
      }
    ]
  },
  "paging": {
    "offset": 2
  }
}
```

### Response Fields

| Field    | Type    | Description                              |
| :------- | :------ | :--------------------------------------- |
| userId   | integer | User's unique identifier                 |
| units    | string  | Balance unit: `hours` or `days`          |
| balance  | number  | Remaining balance (can be decimal)       |
| policyId | string  | ID of the policy this balance belongs to |

***

## Update User Balance

Set a user's time-off balance for a policy type.

> ⚠️ Replaces Balance
>
> This operation **sets** the balance to the specified value. It does not add to or subtract from the existing balance.

### Path Parameters

| Parameter    | Type    | Required | Description        |
| :----------- | :------ | :------- | :----------------- |
| policyTypeId | string  | Yes      | The policy type ID |
| userId       | integer | Yes      | The user's ID      |

### Request Body

| Field   | Type   | Required | Description           |
| :------ | :----- | :------- | :-------------------- |
| balance | number | Yes      | The new balance value |

### Example Request

```bash
curl --request PUT \
  --url https://api.connecteam.com/time-off/v1/policy-types/pt-vacation-001/balances/9170357 \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: YOUR_API_KEY' \
  --data '{
    "balance": 20.0
  }'
```

### Response

```json
{
  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "data": {
    "balance": {
      "userId": 9170357,
      "units": "days",
      "balance": 20.0,
      "policyId": "pol-vac-ft-001"
    }
  }
}
```

***

## Pagination Example

```javascript
async function getAllBalances(policyTypeId) {
  const balances = [];
  let offset = 0;
  const limit = 100;
  
  while (true) {
    const response = await fetch(
      `https://api.connecteam.com/time-off/v1/policy-types/${policyTypeId}/balances?limit=${limit}&offset=${offset}`,
      { headers: { 'X-API-KEY': 'YOUR_API_KEY' } }
    );
    
    const result = await response.json();
    balances.push(...result.data.balances);
    
    if (result.data.balances.length < limit) {
      break;
    }
    
    offset = result.paging.offset;
  }
  
  return balances;
}
```

***

## Error Responses

### 404 Not Found

```json
{
  "detail": "Policy type not found"
}
```

### 422 Validation Error

```json
{
  "detail": [
    {
      "loc": ["body", "balance"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}
```

***

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