Get Staff Availability

get

https://api.vcita.biz/platform/v1/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.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Query Params

start_date

date

required

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.

end_date

date

required

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.

staff_ids_array

string

required

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.

time_zone

string

Defaults to UTC

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.

aggregate_by

string

enum

Defaults to date

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.

Allowed:

booking_instance_id

string

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

include_dst

string

enum

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.

Allowed:

show_past_availabilities

string

enum

Defaults to false

When set to "true", includes availability slots that fall before the current time. By default ("false"), only future availability is returned.

Allowed:

ignore_min_schedule

string

enum

Defaults to false

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.

Allowed:

type

string

enum

Defaults to AppointmentService

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.

Allowed:

Responses

Language

Credentials

Bearer

JWT

Loading…

Response

Click Try It! to start a request and see the response here! Or choose an example:

application/json

200Availability slots retrieved successfully. The structure of availabilities depends on the aggregate_by parameter.

400Bad Request - A required parameter is missing.

422Unprocessable Entity - The request parameters are invalid (e.g., invalid date range or time zone).