---
updatedAt: 2026-09-16T11:42:28.000Z
agentTools:
  projectIndex: https://developers.intandem.tech/llms.txt
---

# Get Staff Availability

## Overview
Returns available time slots for one or more staff members. The endpoint considers staff weekly availability schedules, calendar sync conflicts, blocked times, and existing bookings to compute open appointment or event slots.

The response can be aggregated by date (default) or by staff member using the `aggregate_by` parameter.

Authentication is optional. When a valid client token is provided, availability may be filtered based on the client's context. When no token is provided, the endpoint returns availability without client-specific filtering.

Available for **Staff, Directory, and Client tokens**. Also accessible without authentication.

# OpenAPI definition

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "Scheduling",
    "description": "Unified OpenAPI specification for scheduling domain",
    "version": "3.0",
    "x-generated": {
      "sourceFiles": [
        "legacy_v1_scheduling.json",
        "scheduling.json",
        "availability.json",
        "availability_slots.json",
        "resource_management.json"
      ],
      "pathNormalizations": [
        {
          "file": "legacy_v1_scheduling.json",
          "basePath": "/platform/v1",
          "transformations": [
            {
              "original": "/scheduling/appointments",
              "normalized": "/platform/v1/scheduling/appointments",
              "basePath": "/platform/v1"
            },
            {
              "original": "/scheduling/appointments/{appointment_id}",
              "normalized": "/platform/v1/scheduling/appointments/{appointment_id}",
              "basePath": "/platform/v1"
            },
            {
              "original": "/scheduling/bookings",
              "normalized": "/platform/v1/scheduling/bookings",
              "basePath": "/platform/v1"
            },
            {
              "original": "/scheduling/bookings/cancel",
              "normalized": "/platform/v1/scheduling/bookings/cancel",
              "basePath": "/platform/v1"
            },
            {
              "original": "/scheduling/bookings/{booking_uid}/update_rsvp_state",
              "normalized": "/platform/v1/scheduling/bookings/{booking_uid}/update_rsvp_state",
              "basePath": "/platform/v1"
            },
            {
              "original": "/scheduling/event_attendances/{event_attendance_uid}",
              "normalized": "/platform/v1/scheduling/event_attendances/{event_attendance_uid}",
              "basePath": "/platform/v1"
            },
            {
              "original": "/scheduling/event_instance/{event_instance_id}",
              "normalized": "/platform/v1/scheduling/event_instance/{event_instance_id}",
              "basePath": "/platform/v1"
            },
            {
              "original": "/scheduling/scheduling_forms/get_form",
              "normalized": "/platform/v1/scheduling/scheduling_forms/get_form",
              "basePath": "/platform/v1"
            },
            {
              "original": "/scheduling/waitlist",
              "normalized": "/platform/v1/scheduling/waitlist",
              "basePath": "/platform/v1"
            },
            {
              "original": "/scheduling/waitlist/cancel",
              "normalized": "/platform/v1/scheduling/waitlist/cancel",
              "basePath": "/platform/v1"
            },
            {
              "original": "/services",
              "normalized": "/platform/v1/services",
              "basePath": "/platform/v1"
            },
            {
              "original": "/staff/availability",
              "normalized": "/platform/v1/staff/availability",
              "basePath": "/platform/v1"
            }
          ]
        },
        {
          "file": "scheduling.json",
          "basePath": "/business/scheduling",
          "transformations": [
            {
              "original": "/v1/appointments",
              "normalized": "/business/scheduling/v1/appointments",
              "basePath": "/business/scheduling"
            },
            {
              "original": "/v1/bookings",
              "normalized": "/business/scheduling/v1/bookings",
              "basePath": "/business/scheduling"
            },
            {
              "original": "/v1/bookings/accept",
              "normalized": "/business/scheduling/v1/bookings/accept",
              "basePath": "/business/scheduling"
            },
            {
              "original": "/v1/bookings/cancel",
              "normalized": "/business/scheduling/v1/bookings/cancel",
              "basePath": "/business/scheduling"
            },
            {
              "original": "/v1/bookings/complete",
              "normalized": "/business/scheduling/v1/bookings/complete",
              "basePath": "/business/scheduling"
            },
            {
              "original": "/v1/bookings/{booking_id}",
              "normalized": "/business/scheduling/v1/bookings/{booking_id}",
              "basePath": "/business/scheduling"
            },
            {
              "original": "/v1/external_calendar_items/bulk_create",
              "normalized": "/business/scheduling/v1/external_calendar_items/bulk_create",
              "basePath": "/business/scheduling"
            },
            {
              "original": "/v1/external_calendar_items/bulk_deactivate",
              "normalized": "/business/scheduling/v1/external_calendar_items/bulk_deactivate",
              "basePath": "/business/scheduling"
            },
            {
              "original": "/v1/external_calendar_items/connect",
              "normalized": "/business/scheduling/v1/external_calendar_items/connect",
              "basePath": "/business/scheduling"
            },
            {
              "original": "/v1/external_calendar_items/deactivate_external_calendar",
              "normalized": "/business/scheduling/v1/external_calendar_items/deactivate_external_calendar",
              "basePath": "/business/scheduling"
            },
            {
              "original": "/v1/external_calendar_items/disable",
              "normalized": "/business/scheduling/v1/external_calendar_items/disable",
              "basePath": "/business/scheduling"
            },
            {
              "original": "/v1/external_calendar_items/disconnect",
              "normalized": "/business/scheduling/v1/external_calendar_items/disconnect",
              "basePath": "/business/scheduling"
            },
            {
              "original": "/v1/external_calendar_items/report_sync_status",
              "normalized": "/business/scheduling/v1/external_calendar_items/report_sync_status",
              "basePath": "/business/scheduling"
            },
            {
              "original": "/v1/external_calendar_items/start_export",
              "normalized": "/business/scheduling/v1/external_calendar_items/start_export",
              "basePath": "/business/scheduling"
            },
            {
              "original": "/v1/external_calendar_items/stop_import",
              "normalized": "/business/scheduling/v1/external_calendar_items/stop_import",
              "basePath": "/business/scheduling"
            },
            {
              "original": "/v1/time_slots",
              "normalized": "/business/scheduling/v1/time_slots",
              "basePath": "/business/scheduling"
            },
            {
              "original": "/v1/time_slots/{time_slot_uid}",
              "normalized": "/business/scheduling/v1/time_slots/{time_slot_uid}",
              "basePath": "/business/scheduling"
            }
          ]
        }
      ],
      "pathConflicts": [],
      "componentConflicts": [],
      "totalPaths": 35,
      "totalComponents": 4
    }
  },
  "servers": [
    {
      "url": "https://api.vcita.biz",
      "description": "Unified API Gateway server"
    }
  ],
  "paths": {
    "/platform/v1/staff/availability": {
      "get": {
        "description": "## Overview\nReturns available time slots for one or more staff members. The endpoint considers staff weekly availability schedules, calendar sync conflicts, blocked times, and existing bookings to compute open appointment or event slots.\n\nThe response can be aggregated by date (default) or by staff member using the `aggregate_by` parameter.\n\nAuthentication is optional. When a valid client token is provided, availability may be filtered based on the client's context. When no token is provided, the endpoint returns availability without client-specific filtering.\n\nAvailable for **Staff, Directory, and Client tokens**. Also accessible without authentication.",
        "parameters": [
          {
            "description": "The start date of the availability window in `YYYY-MM-DD` format (e.g., \"2026-03-03\"). Must be a valid date string that can be parsed into a timezone-aware datetime.",
            "in": "query",
            "name": "start_date",
            "required": true,
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "description": "The end date of the availability window in `YYYY-MM-DD` format (e.g., \"2026-03-10\"). Must be a valid date string that can be parsed into a timezone-aware datetime. The range between `start_date` and `end_date` determines the window for which availability slots are returned.",
            "in": "query",
            "name": "end_date",
            "required": true,
            "schema": {
              "type": "string",
              "format": "date"
            }
          },
          {
            "description": "Comma-separated list of staff member UIDs to query availability for (e.g., \"j9c1xh0vzvkr2g0g\" or \"j9c1xh0vzvkr2g0g, abc123def456\"). If the value is a comma-separated string, it will be split into an array internally. At least one staff UID should be provided for meaningful results.",
            "in": "query",
            "name": "staff_ids_array",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "IANA time zone identifier used to localize the returned availability slots (e.g., \"UTC\", \"America/New_York\", \"Asia/Jerusalem\"). Defaults to \"UTC\" if not provided. The time zone affects the `start_time` formatting and date grouping in the response.",
            "in": "query",
            "name": "time_zone",
            "required": false,
            "schema": {
              "type": "string",
              "default": "UTC"
            }
          },
          {
            "description": "Controls how the availability slots are grouped in the response. When set to \"date\" (the default), slots are grouped by date string (e.g., \"2026-03-03\"). When set to \"staff\", slots are grouped first by staff UID and then by date, and the `staff_id` field is removed from individual slot objects.",
            "in": "query",
            "name": "aggregate_by",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "date",
                "staff"
              ],
              "default": "date"
            }
          },
          {
            "description": "An existing booking instance UID to exclude from the availability calculation. This is useful when rescheduling an appointment — the time currently occupied by this booking will be treated as available. (e.g., \"bk_abc123\")",
            "in": "query",
            "name": "booking_instance_id",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "When set to \"true\", the returned `start_time` values will include daylight saving time (DST) offset adjustments for the specified time zone. When \"false\" or omitted, DST adjustments may not be applied.",
            "in": "query",
            "name": "include_dst",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "true",
                "false"
              ]
            }
          },
          {
            "description": "When set to \"true\", includes availability slots that fall before the current time. By default (\"false\"), only future availability is returned.",
            "in": "query",
            "name": "show_past_availabilities",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "true",
                "false"
              ],
              "default": "false"
            }
          },
          {
            "description": "When set to \"true\", ignores the business's minimum scheduling notice (the minimum amount of time before an appointment can be booked). Useful for internal tools or admin-level booking where the minimum lead time should not apply.",
            "in": "query",
            "name": "ignore_min_schedule",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "true",
                "false"
              ],
              "default": "false"
            }
          },
          {
            "description": "The type of service to check availability for. \"AppointmentService\" returns individual appointment slots based on staff schedules. \"EventService\" returns event instance availability with additional fields such as pricing and interaction details.",
            "in": "query",
            "name": "type",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "AppointmentService",
                "EventService"
              ],
              "default": "AppointmentService"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Availability slots retrieved successfully. The structure of `availabilities` depends on the `aggregate_by` parameter.",
            "content": {
              "application/json": {
                "example": {
                  "status": "OK",
                  "data": {
                    "availabilities": {
                      "2026-03-03": [
                        {
                          "staff_id": "j9c1xh0vzvkr2g0g",
                          "spots_total": 1,
                          "spots_open": 1,
                          "start_time": "2026-03-03T10:00:00+00:00",
                          "duration_minutes": 30,
                          "event_instance_id": null
                        },
                        {
                          "staff_id": "j9c1xh0vzvkr2g0g",
                          "spots_total": 1,
                          "spots_open": 1,
                          "start_time": "2026-03-03T10:30:00+00:00",
                          "duration_minutes": 30,
                          "event_instance_id": null
                        }
                      ],
                      "2026-03-04": [
                        {
                          "staff_id": "j9c1xh0vzvkr2g0g",
                          "spots_total": 1,
                          "spots_open": 1,
                          "start_time": "2026-03-04T09:00:00+00:00",
                          "duration_minutes": 60,
                          "event_instance_id": null
                        }
                      ]
                    },
                    "time_zone": "UTC"
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad Request - A required parameter is missing.",
            "content": {
              "application/json": {
                "example": {
                  "status": "Error",
                  "error": "Mandatory parameter start_date is missing",
                  "error_code": "PARAMETER_MISSING"
                }
              }
            }
          },
          "422": {
            "description": "Unprocessable Entity - The request parameters are invalid (e.g., invalid date range or time zone).",
            "content": {
              "application/json": {
                "example": {
                  "status": "Error",
                  "message": "Invalid time zone"
                }
              }
            }
          }
        },
        "summary": "Get Staff Availability",
        "tags": [
          "Staff Availability"
        ],
        "x-amazon-apigateway-integration": {
          "httpMethod": "GET",
          "requestParameters": {},
          "responses": {
            "default": {
              "statusCode": "200"
            }
          },
          "type": "http_proxy",
          "uri": "https:///platform/v1/staff/availability"
        },
        "x-response-aggregate-by-staff": {
          "description": "When aggregate_by=staff, the availabilities object is keyed by staff UID instead of date. Each staff UID maps to an object of dates, each containing an array of slots. The staff_id field is removed from individual slot objects in this mode.",
          "example": {
            "status": "OK",
            "data": {
              "availabilities": {
                "j9c1xh0vzvkr2g0g": {
                  "2026-03-03": [
                    {
                      "spots_total": 1,
                      "spots_open": 1,
                      "start_time": "2026-03-03T10:00:00+00:00",
                      "duration_minutes": 30,
                      "event_instance_id": null
                    }
                  ]
                },
                "abc123def456": {
                  "2026-03-03": [
                    {
                      "spots_total": 1,
                      "spots_open": 1,
                      "start_time": "2026-03-03T11:00:00+00:00",
                      "duration_minutes": 45,
                      "event_instance_id": null
                    }
                  ]
                }
              },
              "time_zone": "UTC"
            }
          }
        },
        "security": [
          {
            "Bearer": []
          }
        ]
      }
    }
  },
  "components": {
    "securitySchemes": {
      "Bearer": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "description": "Provide a valid bearer token in the Authorization header. Example: 'Authorization: Bearer {app_token}'"
      }
    }
  }
}
```