Skip to main content
GHL MCP Guide
SLT

Free Slots

Calendars & Scheduling · Basic · Updated March 2026

Check calendar availability and retrieve free time slots for a given date range. Powers booking widgets and scheduling automation with real-time availability.

Before you can book an appointment, you need to know what’s available. Free Slots queries a calendar’s availability rules, existing appointments, and blocked time to return the actual open slots for a given date range. This powers custom booking experiences, AI scheduling assistants, and any automation that needs to offer time options to a prospect.

What This MCP Tool Does

Retrieve available time slots for a specific calendar within a date range. The endpoint factors in the calendar’s availability rules, existing bookings, buffer times, and blocked slots to return only genuinely open times.

Endpoint Reference

Get available slots: GET /calendars/{calendarId}/free-slots Returns available time slots for the specified date range, formatted with start and end times.

Authentication

Requires a Private Integration Token (PIT) with the calendars scope enabled.

Key Parameters

  • calendarId — the calendar to check availability on
  • startDate — beginning of the date range to check
  • endDate — end of the date range to check
  • timezone — the timezone to return slots in (visitor’s timezone)

Important Notes

The response respects all calendar rules: availability windows, slot duration, buffer times between appointments, maximum appointments per slot (for class bookings), and any Block Slots applied.

Timezone handling is critical. Request slots in the visitor’s timezone so they see times relevant to their location. GHL handles the conversion internally.

Free slots are calculated in real-time. Between checking availability and booking, a slot could be taken by another booker. Build your booking flow to handle the case where a slot shown as available is no longer open when the booking request is made.

For round-robin calendars, free slots represent the combined availability of all assigned team members. At least one team member must be available for a slot to appear.

Common Questions

How far in advance can I check availability? Depends on the calendar’s booking window configuration. Most calendars allow booking 30-90 days out. The endpoint respects whatever limit the calendar is configured with.

Do buffer times affect available slots? Yes. If a calendar has a 15-minute buffer between appointments, the free slots calculation accounts for that gap.

Can I check multiple calendars at once? Not in a single call. Check each calendar individually and merge results client-side if needed.

What if a slot shows as available but is taken when I try to book? Your booking attempt will either fail or create a double-booking depending on the calendar’s overlap settings. Build retry logic or slot-locking into your booking flow.

Back to GHL MCP Guide