Skip to content
Developer docsChannel Automation Developers
First requestVisit website ↗
Navigation

Get available appointment slots across a date range

Multi-day availability in one call, so a booking UI or agent can show the next open days without one request per date. Each day carries the same slot objects the single-day endpoint returns. Days with no availability are still present with has_slots false, so the caller can render a full calendar strip.

GET
https://api.channelautomation.com/api/calendar/availability/range

Query parameters

  • workspace_id
    string
    required

    Workspace the calendar belongs to

  • admin_id
    string
    required

    Admin/agent whose calendar is being queried

  • days
    optional
    integer

    Number of consecutive days to return, starting at start_date

    maximum: 14 · minimum: 1 · default: 7
  • start_date
    optional
    string

    First day of the window. Defaults to today in the calendar's timezone.

    format: date
  • event_type_id
    optional
    string

    Restrict to a single event type. Defaults to the workspace's oldest enabled type.

    format: uuid
  • service_appointment_id
    optional
    string

    Required for workspaces backed by an external availability provider. Those workspaces return 400 without it rather than falling back to the native schedule, which would offer times the provider cannot honor.

  • format
    optional
    simple

    simple returns the compact shape built for a live voice or text agent: every time is already rendered in the calendar's own timezone in 12-hour form, so the agent never converts or does date arithmetic. Fully booked times and days with nothing free are omitted. Pass the id of any entry straight back to the booking endpoint as slot_id. Omit this parameter for the detailed default shape.

Returns

200

Range availability retrieved successfully

JSON
  • success
    optional
    boolean
  • timezone
    optional
    string
  • start_date
    optional
    string
    format: date
  • days
    optional
    integer
  • event_type_id
    optional
    string
    format: uuid
  • source
    optional
    native
    or
    external
  • available_dates
    optional
    array of
    string

    External source only. Every date the provider reported slots for.

    format: date
  • dates
    optional
    array of
    object
    • date
      optional
      string
      format: date
    • label
      optional
      string

      today, tomorrow, or the date itself

    • has_slots
      optional
      boolean
    • count
      optional
      integer

      Number of slots that are not fully booked

    • slots
      optional
      array of
      object
      • id
        optional
        string

        Unique identifier for the calendar slot

      • start_time
        optional
        string

        Start time of the appointment slot

        format: date-time
      • end_time
        optional
        string

        End time of the appointment slot

        format: date-time
      • is_booked
        optional
        boolean

        Whether the slot is already booked

      • admin_id
        optional
        string

        ID of the admin/agent assigned to this slot

      • title
        optional
        string

        Title/name of the appointment slot

      • description
        optional
        string

        Description of what this slot is for

      • location
        optional
        string

        Location where the appointment will take place

      • booking_type
        optional
        string

        Type of booking allowed

      • max_bookings
        optional
        integer

        Maximum number of bookings allowed for this slot

400

Invalid days or start_date, missing workspace_id/admin_id, or an external-source workspace queried without service_appointment_id
JSON
  • success
    optional
    boolean
  • error
    optional
    string

500

Internal server error
JSON
  • error
    optional
    string
  • details
    optional
    string
  • success
    optional
    boolean

502

External availability provider unavailable. No native fallback is served.

503

Existing bookings could not be read, so capacity cannot be verified

Type to search…

↑↓ navigate↵ selectEsc close