Skip to main content
GHL MCP Guide
APT

Appointment CRUD

Calendars & Scheduling · Intermediate · Updated March 2026

Book, update, and cancel appointments linked to contacts and calendars. Supports timezone handling, status changes, and calendar sync integration.

Appointments are where leads become conversations and conversations become clients. Every booking is a commitment — from the business and the prospect. Managing appointments through MCP means you can build custom booking flows, sync appointments from external systems, and automate the entire pre-appointment and post-appointment experience.

What This MCP Tool Does

Create, retrieve, update, and cancel appointments. Each appointment links a contact to a specific time slot on a calendar. Supports timezone-aware scheduling, status management, and integration with the contact’s activity timeline.

Endpoint Reference

Create an appointment: POST /appointments Book a contact into a specific calendar time slot. Requires the calendar ID, contact ID, start time, and end time.

Get an appointment: GET /appointments/{appointmentId} Retrieve the full appointment record including contact, calendar, time, status, and metadata.

Update an appointment: PUT /appointments/{appointmentId} Modify appointment details — reschedule, reassign, or update status.

Cancel/delete an appointment: DELETE /appointments/{appointmentId} Cancel the appointment. Depending on calendar settings, this may trigger cancellation notifications.

Authentication

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

Key Parameters

  • calendarId — which calendar the appointment is booked on
  • contactId — the contact attending the appointment
  • startTime — appointment start in ISO 8601 with timezone
  • endTime — appointment end in ISO 8601 with timezone
  • title — optional appointment title
  • appointmentStatus — confirmed, showed, noshow, cancelled, invalid
  • assignedUserId — the team member handling the appointment

Important Notes

Always include timezone information in date/time parameters. GHL handles timezone conversion, but only if you provide timezone-aware timestamps. Sending naive datetimes without timezone data leads to scheduling errors.

Verify slot availability before booking using Free Slots. Creating an appointment for an unavailable time slot may succeed but could create double-bookings depending on calendar configuration.

Appointment status changes (confirmed to no-show, for example) can trigger workflows. Use this for automated no-show follow-up, post-appointment review requests, and rebooking sequences.

Cancellation behavior depends on the calendar’s notification settings. If reminders are configured through Calendar Notifications, cancellation may trigger notification messages to the contact.

Common Questions

Should I check availability before booking? Yes. Use Free Slots to verify the time slot is open before creating the appointment.

Can I book appointments on behalf of a contact without them using the booking page? Yes. MCP appointment creation bypasses the booking page entirely. You provide the time and contact, and the appointment is created.

How do I handle no-shows? Update the appointment status to “noshow” via the update endpoint. This triggers any no-show workflows configured on the calendar.

Can I reschedule an appointment via MCP? Yes. Update the startTime and endTime on the existing appointment record.

Back to GHL MCP Guide