---
updatedAt: 2026-01-28T13:59:21.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 Assignments

Assign users to time-off policies with optional initial balance configuration.

## Endpoint

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

***

## Assign User to Policy

Assign a user to a specific time-off policy. This enables the user to request time off under that policy and have a balance tracked.

> 📝 Policy ID vs Policy Type ID
>
> Use the **policy ID** (not policy type ID) for assignments. Get policy IDs from the [Get Policy Types](time-off-policies-balances) endpoint - they're in the `policies[].id` field.

### Path Parameters

| Parameter       | Type   | Required | Description                                          |
| :-------------- | :----- | :------- | :--------------------------------------------------- |
| timeOffPolicyId | string | Yes      | The policy ID (from policies array, not policy type) |

### Request Body

| Field   | Type    | Required | Description                     |
| :------ | :------ | :------- | :------------------------------ |
| userId  | integer | Yes      | The user's ID to assign         |
| balance | number  | No       | Initial balance to set          |
| unit    | string  | No       | Balance unit: `hours` or `days` |

> 💡 Setting Initial Balance
>
> If you provide `balance` and `unit`, the user will be assigned with that initial balance. If omitted, the user is assigned with the policy's default balance rules.

***

## Examples

### Basic Assignment

Assign a user to a policy with default balance:

```bash
curl --request PUT \
  --url https://api.connecteam.com/time-off/v1/time-off-policies/pol-vac-ft-001/assignments \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: YOUR_API_KEY' \
  --data '{
    "userId": 9170357
  }'
```

### Assignment with Initial Balance (Days)

Assign a user with a specific starting balance in days:

```bash
curl --request PUT \
  --url https://api.connecteam.com/time-off/v1/time-off-policies/pol-vac-ft-001/assignments \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: YOUR_API_KEY' \
  --data '{
    "userId": 9170357,
    "balance": 15.0,
    "unit": "days"
  }'
```

### Assignment with Initial Balance (Hours)

Assign a user with a specific starting balance in hours:

```bash
curl --request PUT \
  --url https://api.connecteam.com/time-off/v1/time-off-policies/pol-sick-001/assignments \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: YOUR_API_KEY' \
  --data '{
    "userId": 9170357,
    "balance": 40.0,
    "unit": "hours"
  }'
```

### Response

```json
{
  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "data": {}
}
```

***

## Bulk Assignment Example

Assign multiple users to a policy:

```javascript
async function assignUsersToPolicy(policyId, userIds, initialBalance, unit) {
  const results = [];
  
  for (const userId of userIds) {
    const response = await fetch(
      `https://api.connecteam.com/time-off/v1/time-off-policies/${policyId}/assignments`,
      {
        method: 'PUT',
        headers: {
          'X-API-KEY': 'YOUR_API_KEY',
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          userId: userId,
          balance: initialBalance,
          unit: unit
        })
      }
    );
    
    results.push({
      userId,
      success: response.ok
    });
  }
  
  return results;
}

// Example usage
assignUsersToPolicy('pol-vac-ft-001', [9170357, 9170358, 9170359], 15, 'days');
```

***

## Onboarding New Employees

When onboarding new employees, assign them to relevant policies:

```javascript
async function onboardEmployee(userId, employeeType) {
  const policies = {
    'full-time': [
      { id: 'pol-vac-ft-001', balance: 15, unit: 'days' },
      { id: 'pol-sick-001', balance: 40, unit: 'hours' }
    ],
    'part-time': [
      { id: 'pol-vac-pt-001', balance: 40, unit: 'hours' },
      { id: 'pol-sick-001', balance: 20, unit: 'hours' }
    ]
  };
  
  const assignments = policies[employeeType] || [];
  
  for (const policy of assignments) {
    await fetch(
      `https://api.connecteam.com/time-off/v1/time-off-policies/${policy.id}/assignments`,
      {
        method: 'PUT',
        headers: {
          'X-API-KEY': 'YOUR_API_KEY',
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          userId: userId,
          balance: policy.balance,
          unit: policy.unit
        })
      }
    );
  }
}
```

***

## Error Responses

### 404 Not Found

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

```json
{
  "detail": "User not found"
}
```

### 422 Validation Error

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

***

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