Free Slots Setup

Check calendar availability and retrieve open time slots before booking appointments. The free slots endpoint handles timezone conversion, buffer times, and existing booking conflicts automatically.

Prerequisites

Before you begin, confirm the following:

• A GoHighLevel sub-account with at least one calendar configured
• A Private Integration Token (PIT) with the calendars scope enabled
• Your locationId from Settings > Business Info
• A valid calendarId (retrieve via GET /calendars)
• The calendar should have availability hours configured (otherwise all slots return empty)

Set Up Authentication

The free slots endpoint uses the same Bearer token as all calendar operations.

1. Go to Settings > Integrations > Private Integrations
2. Select or create a PIT with calendars scope (read access is sufficient)
3. Copy the token:

export GHL_TOKEN="your-private-integration-token"
export LOCATION_ID="your-location-id"

Required headers:

Authorization: Bearer $GHL_TOKEN
Version: 2021-07-28

Make Your First Call

The endpoint is GET /calendars/{calendarId}/free-slots with date range and timezone parameters.

Get free slots for a date range:

curl -X GET "https://services.leadconnectorhq.com/calendars/{calendarId}/free-slots?\
startDate=2026-03-10&\
endDate=2026-03-14&\
timezone=America/New_York" \
  -H "Authorization: Bearer $GHL_TOKEN" \
  -H "Version: 2021-07-28"

Get slots for a single day:

curl -X GET "https://services.leadconnectorhq.com/calendars/{calendarId}/free-slots?\
startDate=2026-03-10&\
endDate=2026-03-10&\
timezone=America/Chicago" \
  -H "Authorization: Bearer $GHL_TOKEN" \
  -H "Version: 2021-07-28"

The timezone parameter is critical. It determines how availability windows are interpreted and how the returned slot times display. Use IANA timezone names like America/New_York, America/Chicago, America/Los_Angeles, or Europe/London.

The startDate and endDate use YYYY-MM-DD format. Keep the range reasonable (7-14 days maximum) to get fast responses.

Handle the Response

A successful 200 response returns a JSON object keyed by date strings. Each date maps to an array of available time slots:

{
  "2026-03-10": [
    "2026-03-10T10:00:00-05:00",
    "2026-03-10T10:30:00-05:00",
    "2026-03-10T11:00:00-05:00",
    "2026-03-10T14:00:00-05:00",
    "2026-03-10T14:30:00-05:00"
  ],
  "2026-03-11": [
    "2026-03-11T09:00:00-05:00",
    "2026-03-11T09:30:00-05:00"
  ]
}

Each timestamp represents the start time of an available slot. The slot duration matches the calendar’s slotDuration setting. Gaps in the sequence indicate times already booked, blocked, or outside availability hours.

If a date key has an empty array, that day has no available slots. Days with no availability at all may be omitted from the response entirely.

The endpoint automatically accounts for:

• Existing appointments on the calendar
• Blocked time periods
• Buffer times between appointments
• Calendar availability hours (business hours configuration)
• The appoinmentPerSlot limit

Common errors:

• 401 — Token invalid or expired.
• 404 — Calendar ID not found.
• 422 — Missing startDate or endDate. Both parameters are required.
• 400 — Invalid date format. Use YYYY-MM-DD.

Test Your Setup

Validate that free slots reflect real availability:

1. Query free slots for the next 3 days on a calendar you control
2. Compare the returned slots against the calendar’s availability settings in the GHL dashboard
3. Book an appointment at one of the returned slots using the Appointment CRUD endpoint
4. Re-query free slots for the same date range. Confirm the booked slot no longer appears.
5. Test timezones by running the same query with America/New_York and then America/Los_Angeles. Verify the slot times shift by 3 hours.

If all slots return empty, check the calendar’s availability hours in the dashboard. A calendar with no configured hours has no bookable slots.

Next Steps

Read the full Free Slots guide for patterns like pre-filtering slots by team member and building custom booking widgets. Use the slots with Appointment CRUD to book meetings, or check Block Slots to manage temporary availability blocks.