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

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

{
  "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

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

{
  "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

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

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

{
  "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.

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

Response

{
  "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