Calendars and booking

Booking is the one thing a voice agent does that needs somewhere to put the appointment. A sub-account with GoHighLevel books into a GHL calendar. A sub-account without one books into a Team Follow Up calendar, described here. The two are the same shape. Availability comes back as days of start times either way, and a booking answers with the time it actually took, so an integration written against one reads the other unchanged.

What a calendar is

A calendar is a bookable resource with hours and rules. A sub-account can have several, and a campaign names the one its agent books into.

Setting	What it does	Default
`timezone`	The calendar’s own zone. Opening hours are read in it, and a booking anchors to it. Required.	none
`weeklyHours`	`{ mon: [{ start: "09:00", end: "17:00" }], ... }`. A day left out is closed.	none
`dateOverrides`	Named days that differ: `{ date, closed: true }`, or different windows.	none
`slotDurationMinutes`	How long an appointment lasts.	`30`
`slotIntervalMinutes`	How often a slot starts. Shorter than the duration gives overlapping starts.	`30`
`slotBufferMinutes`	Quiet time held either side of a booking.	`0`
`appointmentsPerSlot`	Seats per slot. More than one is a group booking.	`1`
`minNoticeMinutes`	How soon the first offered slot may be.	`180`
`maxDaysOut`	How far ahead it will offer.	`31`

In the dashboard, open Calendars and pick a calendar. These settings are Opening hours, Appointment length, Start every, Buffer between, Bookings per slot, Minimum notice (minutes), How far ahead (days) and Dated exceptions.

Hours are validated as a whole. A window that ends at or before it starts is refused rather than wrapped past midnight, because a slot that crossed midnight would land under a different date than anyone expects. A calendar with no hours, or an appointment longer than a window, is saved but offers nothing there, so check it with Preview slots below.

Creating one

curl -X POST "https://api.teamfollowup.ai/api/native-calendar/calendars?locationId={locationId}" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Consultations",
    "timezone": "America/Chicago",
    "weeklyHours": {
      "mon": [{"start":"09:00","end":"12:00"},{"start":"13:00","end":"17:00"}],
      "tue": [{"start":"09:00","end":"17:00"}]
    },
    "slotDurationMinutes": 30,
    "minNoticeMinutes": 180
  }'

Try a definition before you save it with Preview slots: it validates the definition and returns the slots it would offer. Pass an existing calendarId as well and what is already booked is counted, so the preview shows what would really be left.

Slots and seats

Free slots answers day by day:

{
  "success": true,
  "data": {
    "timezone": "America/Chicago",
    "slots": {
      "2026-09-24": { "slots": ["2026-09-24T14:00:00.000Z", "2026-09-24T14:30:00.000Z"] },
      "2026-09-25": { "slots": ["2026-09-25T14:00:00.000Z"] }
    }
  }
}

It is computed per request against live bookings and is never cached, because a cached slot is one somebody else may already have taken. A slot holds as many seats as appointmentsPerSlot. confirmed and showed occupy a seat; cancelled and noshow free it. A past appointment that happened keeps its seat, so a second booking can never land on a slot that was genuinely used.

Booking

curl -X POST "https://api.teamfollowup.ai/api/native-calendar/appointments?locationId={locationId}" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"calendarId":"cal_...","contactId":"nct_...","startTime":"2026-09-24T15:00:00.000Z"}'

Three things are worth knowing before you write the call:

startTime without an offset is read in the calendar’s zone. Epoch milliseconds and a full ISO instant are both accepted and are unambiguous. A bare 2026-09-24T15:00:00 is read as 15:00 where the calendar lives, which is usually what you meant.
The seat is checked, then claimed as the booking is written, so two callers racing for the last seat cannot both win. The loser gets 409 with a message that every seat on the slot is taken. A time outside the hours, inside the notice window or past the lookahead also gets 409, with a message saying why.
Read bookedStartTime from the response rather than assuming the time you asked for is the time it took.

Two people try to book the last seat at Tuesday 10:00 at the same moment. One is booked; the other is told the time is taken.

On a call, the agent tells the second caller that time was just taken and offers others. Booking ends any chase that contact was in, exactly as when an agent books them on a call, and starts the confirmation campaign on that calendar. Rescheduling claims the new time the same way and only gives up the old seat once the new one is held. The reminders that belonged to the old time are re-anchored to the new one rather than left pointing at a time that has passed.

Time that is not a booking

An event is an entry with no contact: a meeting, a reminder, an hour held back. It carries no lead, starts no campaign and tells nobody. What it does do is occupy the seats it covers, so the agent stops offering that time.

Retiring a calendar

A delete refuses while people still have appointments on it, answering 409 with upcomingCount, so a calendar cannot quietly strand everyone who booked. force=true goes ahead and cancels them, and cancelling a booking tells the attendee.

Calendars that live somewhere else

A sub-account can connect a calendar product it already uses, such as Cal.com. List connections says which calendar systems can be connected, how each one is connected, and whether this sub-account has done it.

Paste the credential

Connect a calendar system checks the key with that product first, then stores it in token mode. A key the product refuses is not saved and answers CalendarKeyRefused. If the product cannot be reached, nothing is saved either and the answer is CalendarKeyCheckUnavailable, so try again in a minute.

Cancellations are registered at connect time

A cancellation made in that product reaches us only because the connection registered for it, with a webhook in that product. cancellations in the answer says how that went: watched when registered, pending while it is still being tried, failed with the reason in cancellationsError, or unsupported. Reconnect the system if it is not watched.

Read, never write

Their calendars and bookings are read through their own API and shown beside yours. Nothing here writes into that product, because the calendar is managed there.

A reconnect replaces the stored key, and the old one is gone. The webhook registered under the old key is removed first; if that fails, it is tried again with the new key. One that neither key can remove stays in your account in that product until you remove it there, and what it sends is refused.

Start here

How it works

How-to guides

Agents

TFU Live

In-call Capabilities

Campaigns

Master agent

Phone Numbers

Caller ID

Voices

CRM connections

Projects

Calls

Contacts

Native Contacts

Native Calendar

Analytics

Billing

What a calendar is

Creating one

Slots and seats

Booking

Time that is not a booking

Retiring a calendar

Calendars that live somewhere else

Where to go next

Why the agent found nothing

Native Calendar API