---
updatedAt: 2026-01-28T13:27:02.000Z
---

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

# Unavailability

Manage user unavailability to prevent scheduling conflicts. Unavailability entries indicate when users cannot work, whether from manual entries or approved time-off requests.

## Get User Unavailabilities

Retrieve unavailabilities, time-off, and existing shifts for a user across all schedulers. Useful for checking availability before scheduling.

### Query Parameters

| Parameter | Type    | Required | Description                          |
| :-------- | :------ | :------- | :----------------------------------- |
| userId    | integer | Yes      | User ID to check                     |
| startTime | integer | Yes      | Start of date range (Unix timestamp) |
| endTime   | integer | Yes      | End of date range (Unix timestamp)   |

### Example

```bash
curl --request GET \
  --url 'https://api.connecteam.com/scheduler/v1/schedulers/user-unavailability?userId=9170357&startTime=1736899200&endTime=1737504000' \
  --header 'X-API-KEY: YOUR_API_KEY'
```

### Response

```json
{
  "requestId": "abc123...",
  "data": {
    "userUnavailabilities": [
      {
        "userId": 9170357,
        "unavailabilities": [
          {
            "id": "unav-001",
            "type": "unavailability",
            "startTime": {
              "timestamp": 1736935200,
              "timezone": "America/New_York"
            },
            "endTime": {
              "timestamp": 1736978400,
              "timezone": "America/New_York"
            },
            "note": "Doctor appointment",
            "instanceId": 9454799
          },
          {
            "id": null,
            "type": "timeOff",
            "startTime": {
              "timestamp": 1737108000,
              "timezone": "America/New_York"
            },
            "endTime": {
              "timestamp": 1737194400,
              "timezone": "America/New_York"
            },
            "note": "Vacation",
            "policyName": "Annual Leave"
          }
        ],
        "shifts": [
          {
            "id": "shift-001",
            "startTime": {
              "timestamp": 1737021600,
              "timezone": "America/New_York"
            },
            "endTime": {
              "timestamp": 1737050400,
              "timezone": "America/New_York"
            },
            "instanceId": 9454799
          }
        ]
      }
    ]
  }
}
```

### Response Fields

| Field                          | Type    | Description                             |
| :----------------------------- | :------ | :-------------------------------------- |
| userId                         | integer | User ID                                 |
| unavailabilities               | array   | List of unavailability entries          |
| unavailabilities\[].type       | string  | `unavailability` or `timeOff`           |
| unavailabilities\[].instanceId | integer | Scheduler ID (for unavailability type)  |
| unavailabilities\[].policyName | string  | Time-off policy name (for timeOff type) |
| shifts                         | array   | User's existing shift assignments       |

***

## Get Schedule Unavailabilities

Retrieve unavailabilities for a specific scheduler.

### Query Parameters

| Parameter | Type    | Required | Description                          |
| :-------- | :------ | :------- | :----------------------------------- |
| startTime | integer | Yes      | Start of date range (Unix timestamp) |
| endTime   | integer | Yes      | End of date range (Unix timestamp)   |
| limit     | integer | No       | Max results (1-500, default: 10)     |
| offset    | integer | No       | Pagination offset                    |

### Example

```bash
curl --request GET \
  --url 'https://api.connecteam.com/scheduler/v1/schedulers/9454799/unavailabilities?startTime=1736899200&endTime=1737504000&limit=50' \
  --header 'X-API-KEY: YOUR_API_KEY'
```

### Response

```json
{
  "requestId": "abc123...",
  "data": {
    "unavailabilities": [
      {
        "id": "unav-001",
        "userId": 9170357,
        "isAllDay": true,
        "unavailabilityDate": "2025-01-15",
        "startTime": null,
        "endTime": null,
        "timezone": "America/New_York",
        "note": "Personal day"
      },
      {
        "id": "unav-002",
        "userId": 9170358,
        "isAllDay": false,
        "unavailabilityDate": "2025-01-16",
        "startTime": "09:00:00",
        "endTime": "13:00:00",
        "timezone": "America/New_York",
        "note": "Morning appointment"
      }
    ]
  },
  "paging": {
    "offset": 2
  }
}
```

***

## Create Unavailability

Create a new unavailability entry for a user.

### Request Body

| Field              | Type    | Required    | Description                                |
| :----------------- | :------ | :---------- | :----------------------------------------- |
| userId             | integer | Yes         | User ID                                    |
| unavailabilityDate | string  | Yes         | Date in ISO format (YYYY-MM-DD)            |
| isAllDay           | boolean | Yes         | Whether all-day unavailability             |
| startTime          | string  | Conditional | Start time (HH:MM:SS) if not all-day       |
| endTime            | string  | Conditional | End time (HH:MM:SS) if not all-day         |
| timezone           | string  | No          | Tz format (defaults to scheduler timezone) |
| note               | string  | No          | Optional description                       |

### Example: All-Day Unavailability

```bash
curl --request POST \
  --url https://api.connecteam.com/scheduler/v1/schedulers/9454799/unavailability \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: YOUR_API_KEY' \
  --data '{
    "userId": 9170357,
    "unavailabilityDate": "2025-01-20",
    "isAllDay": true,
    "note": "Family event"
  }'
```

### Example: Partial Day Unavailability

```bash
curl --request POST \
  --url https://api.connecteam.com/scheduler/v1/schedulers/9454799/unavailability \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: YOUR_API_KEY' \
  --data '{
    "userId": 9170357,
    "unavailabilityDate": "2025-01-21",
    "isAllDay": false,
    "startTime": "14:00:00",
    "endTime": "18:00:00",
    "timezone": "America/New_York",
    "note": "Afternoon appointment"
  }'
```

### Response

```json
{
  "requestId": "abc123...",
  "data": {
    "id": "unav-003",
    "userId": 9170357,
    "isAllDay": false,
    "unavailabilityDate": "2025-01-21",
    "startTime": "14:00:00",
    "endTime": "18:00:00",
    "timezone": "America/New_York",
    "note": "Afternoon appointment"
  }
}
```

> 📝 Note
>
> Repeating unavailabilities are not currently supported via API. Each entry must be created individually.

***

## Delete Unavailability

Remove an unavailability entry.

```bash
curl --request DELETE \
  --url https://api.connecteam.com/scheduler/v1/schedulers/9454799/unavailability/unav-003 \
  --header 'X-API-KEY: YOUR_API_KEY'
```

### Response

```json
{
  "requestId": "abc123...",
  "data": {}
}
```

***

## Unavailability vs Time-Off

| Type           | Source                    | Editable via API |
| :------------- | :------------------------ | :--------------- |
| unavailability | Manual entry              | Yes              |
| timeOff        | Approved time-off request | No (read-only)   |

Time-off entries come from the Time Off feature and are automatically reflected in user unavailabilities. They cannot be created or deleted through the Scheduler API.

***

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