GoHighLevel - Calendar Integration

This guide explains how to set up and use Atlas Actions to integrate GoHighLevel functionality into your campaigns. Atlas Actions allow your AI assistant to interact with GoHighLevel's CRM, calendars, and appointments automatically.

📋 Table of Contents

Overview

Prerequisites

Available Atlas Actions

Setup Process

Action Details

1. GHL Upsert Contact

2. GHL Calendar Free Slots

3. GHL Create Appointment

Adding Actions to Campaigns

Common Use Cases

Troubleshooting

Overview

Atlas Actions are pre-built integrations that allow your AI assistant to perform specific tasks in external systems like GoHighLevel. These actions use templates that you configure once and then add to your campaigns.

Key Benefits:

No coding required

Secure credential management

Reusable across multiple campaigns

Easy to configure and maintain

Prerequisites

Before setting up Atlas Actions for GoHighLevel, ensure you have:

Active GoHighLevel Account

Access to Settings and API Keys

Sub-account (Location) access

GoHighLevel API Access

Ability to create Private Integration Tokens (V2 API - Recommended)

Or API Keys (V1 API - Legacy)

Required Information

Location ID

Calendar ID (for calendar-related actions)

API Key or Access Token

Available Atlas Actions

Atlas provides three main GoHighLevel actions:

Action Name	Purpose	When to Use
GHL Upsert Contact	Create or update contacts in CRM	Before scheduling appointments, managing customer data
GHL Calendar Free Slots	Retrieve available time slots	When showing availability to customers
GHL Create Appointment	Book appointments in calendar	After confirming time slot with customer

Setup Process

Step 1: Obtain GoHighLevel Credentials

Getting Your Location ID

Your Location ID can be found in the URL when viewing your GoHighLevel dashboard.

Example URL:

https://crmpage.com/v2/location/eDv3Z93Fnte6jr7ytj/

In this URL, your Location ID is: eDv3Z93Fnte6jr7ytj

Steps:

Navigate to your sub-account/location

Copy the Location ID from the browser URL

Add Tool this ID - you'll need it when creating tools

Getting Your API Key (V2 API - Recommended)

The V2 API uses Private Integration Tokens which provide better security and granular permissions.

Steps:

Navigate to Private Integrations

In GoHighLevel, go to Settings > Private Integrations

Create New Integration

Click Create new integration

Configure Integration Details

Name: e.g., "Atlas Actions Integration"

Description: "Integration for Atlas AI assistant actions"

Select Required Scopes

Depending on which actions you plan to use, select the appropriate scopes:

Action	Required Scopes
GHL Upsert Contact	`contacts.write`
GHL Calendar Free Slots	`calendars.readonly` (or `calendars.write`)
GHL Create Appointment	`calendars/events.write`

For all three actions, select:

✅ contacts.write - Create and update contacts

✅ calendars.readonly - View calendar availability

✅ calendars/events.write - Create appointments

Copy Your Token

After creating the integration, copy the generated token

⚠️ IMPORTANT: This token provides access to your account data - keep it secure!

Add Tool the token in a secure location

Getting Your Calendar ID

If you plan to use calendar-related actions, you'll need your Calendar ID.

Steps:

In GoHighLevel, go to Calendars

Click on the calendar you want to integrate

The Calendar ID appears in the URL or calendar settings

Example URL:

https://crmpage.com/v2/location/eDv3Z93Fnte6jr7ytj/calendar/CVokAlI8fgw4WYWoCtQz

Calendar ID: CVokAlI8fgw4WYWoCtQz

Step 2: Create Actions from Templates

Now that you have your credentials, you'll create actions from the provided templates.

Where to create actions:

Navigate to Global Actions section in Atlas

Look for the Use this Template option

For each action you need:

Creating GHL Upsert Contact Action

Select template: GHL Upsert Contact

Configure the following fields:

Field	Value	Description
Tool Name	"GHL Upsert Contact"	A friendly name for your action
API Key	`[Your API Token]`	The token you created in Private Integrations
Location ID	`[Your Location ID]`	From your GHL URL
API Version	`2021-04-15`	Default version (pre-selected)

Click Add Tool

Creating GHL Calendar Free Slots Action

Select template: GHL Calendar Free Slots

Configure the following fields:

Field	Value	Description
Tool Name	"GHL Calendar Availability"	A friendly name for your action
API Key	`[Your API Token]`	The token you created in Private Integrations
Calendar ID	`[Your Calendar ID]`	From your calendar settings
API Version	`2021-04-15`	Default version (pre-selected)

Click Add Tool

Creating GHL Create Appointment Action

Select template: GHL Create Appointment

Configure the following fields:

Field	Value	Description
Tool Name	"GHL Book Appointment"	A friendly name for your action
API Key	`[Your API Token]`	The token you created in Private Integrations
Calendar ID	`[Your Calendar ID]`	From your calendar settings
Location ID	`[Your Location ID]`	From your GHL URL
API Version	`2021-04-15`	Default version (pre-selected)

Click Add Tool

To use the GHL calendar you will need the three tools below, so you can just add this pressing the Use All Button
alt text

Action Details

1. GHL Upsert Contact

Purpose: Create new contacts or update existing ones in your GoHighLevel CRM.

When to Use:

Before scheduling appointments (to get the Contact ID)

When collecting customer information

To update customer details

Required Scopes:

contacts.write

How It Works:

Matches existing contacts by email or phone (based on your duplicate settings)

Updates the contact if found

Creates a new contact if not found

Returns the Contact ID (required for booking appointments)

Key Parameters:

Parameter	Required	Description	Example
`locationId`	✅ Yes	Your GHL Location ID (auto-filled from template)	`eDv3Z93Fnte6jr7ytj`
`email`	⚠️ One Required	Contact email address	`john@example.com`
`phone`	⚠️ One Required	Phone with country code	`+1 888-888-8888`
`firstName`	No	First name	`John`
`lastName`	No	Last name	`Doe`
`name`	No	Full name	`John Doe`
`address1`	No	Street address	`123 Main St`
`city`	No	City	`New York`
`state`	No	State/Province	`NY`
`postalCode`	No	ZIP/Postal code	`10001`
`country`	No	Country code	`US`
`timezone`	No	IANA timezone	`America/New_York`
`tags`	No	Array of tags	`["customer", "vip"]`
`customFields`	No	Custom field values	See docs for format

⚠️ Important Notes:

You must provide at least ONE of: email OR phone

The tags parameter overwrites all existing tags - use the Add/Remove Tag API for incremental updates

Custom fields require the field ID from GoHighLevel

Date of birth accepts multiple formats: YYYY/MM/DD, MM/DD/YYYY, YYYY-MM-DD, etc.

Response:

{
  "contact": {
    "id": "0007BWpSzSwfiuSl0tR2",
    "locationId": "eDv3Z93Fnte6jr7ytj",
    "email": "john@example.com",
    "phone": "+18888888888",
    ...
  },
  "new": false
}

The id field is the Contact ID you'll need for creating appointments.

2. GHL Calendar Free Slots

Purpose: Retrieve available time slots from your GoHighLevel calendar.

When to Use:

Before showing appointment options to customers

To check calendar availability

When a customer asks "when are you available?"

Required Scopes:

calendars.readonly (or calendars.write)

How It Works:

Queries your calendar for available slots within a date range

Returns slots grouped by date

Respects your calendar's availability settings and existing bookings

Key Parameters:

Parameter	Required	Description	Example
`startDate`	✅ Yes	Start of search window (Unix epoch milliseconds)	`1548898600000`
`endDate`	✅ Yes	End of search window (Unix epoch milliseconds)	`1549503400000`
`timezone`	No	IANA timezone name for interpreting dates	`America/New_York`

⚠️ Important Notes:

startDate must be in the future

endDate should be within 7 days of startDate for best results

Times must be in Unix epoch milliseconds format

The AI assistant should handle time conversion automatically

Response:

{
  "2021-06-23": {
    "slots": [
      "09:00 AM - 09:30 AM",
      "10:00 AM - 10:30 AM",
      "02:00 PM - 02:30 PM"
    ]
  },
  "2021-06-24": {
    "slots": [
      "09:00 AM - 09:30 AM",
      "11:00 AM - 11:30 AM"
    ]
  }
}

Best Practices:

Always check availability before creating an appointment

Show the customer multiple slot options

Confirm the selected slot before booking

3. GHL Create Appointment

Purpose: Create or book appointments in your GoHighLevel calendar.

When to Use:

After confirming a time slot with the customer

Only after obtaining the Contact ID from Upsert Contact

Only after checking slot availability

Required Scopes:

calendars/events.write

⚠️ CRITICAL WORKFLOW:

This action requires a specific workflow to prevent booking failures:

STEP 1: Call Upsert Contact to get the Contact ID

→ Customer provides their details
→ AI calls "GHL Upsert Contact"
→ Response contains contactId: "0007BWpSzSwfiuSl0tR2"

STEP 2: Call Get Calendar Free Slots to show availability

→ Customer asks "when are you available?"
→ AI calls "GHL Calendar Free Slots"
→ Shows available time slots to customer

STEP 3: Customer chooses a slot and confirms details

→ Customer: "I'll take the 2 PM slot on June 23rd"
→ AI confirms: date, time, duration

STEP 4: Call Create Appointment with Contact ID and confirmed slot

→ AI calls "GHL Create Appointment"
→ Uses contactId from Step 1
→ Uses confirmed time slot from Steps 2-3
→ Appointment is booked!

Key Parameters:

Parameter	Required	Description	Example
`calendarId`	✅ Yes	Your GHL Calendar ID (auto-filled)	`CVokAlI8fgw4WYWoCtQz`
`locationId`	✅ Yes	Your GHL Location ID (auto-filled)	`eDv3Z93Fnte6jr7ytj`
`contactId`	✅ Yes	Contact ID from Upsert Contact	`0007BWpSzSwfiuSl0tR2`
`startTime`	✅ Yes	Appointment start time (ISO 8601 with timezone)	`2021-06-23T14:00:00-04:00`
`endTime`	No	Appointment end time (ISO 8601 with timezone)	`2021-06-23T14:30:00-04:00`
`title`	No	Appointment title	`Consultation Call`
`appointmentStatus`	No	Status: new, confirmed, cancelled, showed, noshow, invalid	`confirmed`
`description`	No	Appointment description	`Initial consultation`
`address`	No	Meeting location/address	`Zoom`
`meetingLocationType`	No	Type: custom, zoom, gmeet, phone, address, ms_teams, google	`zoom`
`assignedUserId`	No	User ID to assign the appointment to	`0007BWpSzSwfiuSl0tR2`
`ignoreDateRange`	No	Skip minimum scheduling notice	`false`
`toNotify`	No	Run automations (true) or skip (false)	`true`
`ignoreFreeSlotValidation`	No	Skip slot availability check (dangerous!)	`false`

⚠️ Important Notes:

Always get the contactId first from Upsert Contact

Always check slot availability with Get Calendar Free Slots

Times must be in ISO 8601 format with timezone: YYYY-MM-DDTHH:mm:ss±HH:MM

If address is provided, meetingLocationType defaults to custom

Setting ignoreFreeSlotValidation to true can cause double-bookings!

Response:

{
  "event": {
    "id": "ocQHyuzHvysMo5N5VsXc",
    "calendarId": "CVokAlI8fgw4WYWoCtQz",
    "locationId": "eDv3Z93Fnte6jr7ytj",
    "contactId": "0007BWpSzSwfiuSl0tR2",
    "startTime": "2021-06-23T14:00:00-04:00",
    "endTime": "2021-06-23T14:30:00-04:00",
    "title": "Consultation Call",
    "appointmentStatus": "confirmed",
    ...
  }
}

Adding Actions to Campaigns

Once you've created your actions from templates, you can add them to your campaigns.

Steps to Add Actions to a Campaign:

Navigate to Campaigns

Go to your Campaigns section in Atlas

Select the campaign you want to configure

Edit Campaign Settings

Click on the campaign name or Edit button

This opens the campaign configuration

Open Custom Integrations

In the campaign editor, find the Integrations section

Or navigate to Edit > Integrations

Add Your Actions

Click Tools Integration -> Manage Tools -> Custom Tools

Select from your created actions:

✅ GHL Upsert Contact

✅ GHL Calendar Availability (Free Slots)

✅ GHL Book Appointment

Click Add or Add Tool

Common Use Cases

Use Case 1: Appointment Scheduling

Scenario: Customer calls and wants to book an appointment.

Workflow:

AI greets customer and asks for their details (name, email, phone)

AI calls Upsert Contact with customer details

Response includes contactId

AI calls Get Calendar Free Slots for next 7 days

Shows available time slots to customer

Customer chooses a time slot

AI confirms details (date, time, duration, type of meeting)

AI calls Create Appointment with:

contactId from step 2

startTime from confirmed slot

Other details as discussed

AI confirms booking with customer

Example Conversation:

AI: Hi! I can help you schedule an appointment. Can I get your name and email?
Customer: Sure, I'm John Doe, john@example.com
AI: Thanks John! Let me check my calendar... 
    [Calls Upsert Contact - gets contactId]
    [Calls Get Calendar Free Slots]
    I have availability on:
    - June 23rd at 9 AM, 10 AM, or 2 PM
    - June 24th at 9 AM or 11 AM
    Which works best for you?
Customer: I'll take June 23rd at 2 PM
AI: Perfect! I'll book you for June 23rd at 2:00 PM. This will be a 30-minute consultation. 
    [Calls Create Appointment]
    All set! You're confirmed for June 23rd at 2:00 PM. You'll receive a confirmation email shortly.

Use Case 2: Update Customer Information

Scenario: Existing customer calls to update their contact information.

Workflow:

AI identifies customer (by phone number or email)

Customer provides updated information (new address, phone, etc.)

AI calls Upsert Contact with updated details

Existing contact is matched and updated

AI confirms update with customer

Example Conversation:

AI: Hi! How can I help you today?
Customer: I moved and need to update my address
AI: I can help with that. What's your email address?
Customer: john@example.com
AI: Got it. What's your new address?
Customer: 456 Oak Avenue, Los Angeles, CA 90001
AI: [Calls Upsert Contact with new address]
    Perfect! I've updated your address to 456 Oak Avenue, Los Angeles, CA 90001. 
    Is there anything else you'd like to update?

Use Case 3: Check Availability Only

Scenario: Customer wants to know when you're available before committing.

Workflow:

Customer asks about availability

AI calls Get Calendar Free Slots

AI presents options to customer

Customer decides (may book later or end conversation)

Example Conversation:

Customer: When are you available next week?
AI: Let me check my calendar...
    [Calls Get Calendar Free Slots for next 7 days]
    I have several openings next week:
    - Monday at 9 AM, 10 AM, 2 PM
    - Tuesday at 9 AM, 11 AM
    - Wednesday at 1 PM, 3 PM
    Would you like to book one of these times?
Customer: Let me check my schedule and call back
AI: No problem! Feel free to reach out whenever you're ready to book.

Troubleshooting

Common Issues and Solutions

Issue: "API Key Invalid" Error

Symptoms: Actions fail with authentication error

Solutions:

Verify you copied the complete API token from GoHighLevel

Check that you selected the correct scopes when creating the token

Make sure the token hasn't been deleted or regenerated in GoHighLevel

Re-create the action with a new API token

Issue: "Location ID Not Found"

Symptoms: Contact creation fails

Solutions:

Double-check your Location ID from the GoHighLevel URL

Ensure you're using the Sub-Account (Location) ID, not the Agency ID

Verify your API token has access to this location

Make sure the location is active in GoHighLevel

Issue: "Calendar ID Invalid"

Symptoms: Cannot retrieve slots or create appointments

Solutions:

Verify the Calendar ID is correct from your calendar settings

Check that the calendar is active and published

Ensure your API token has calendar permissions

Confirm the calendar belongs to the correct location

Issue: "Contact ID Required" Error

Symptoms: Create Appointment fails

Solutions:

You must call Upsert Contact first to get the Contact ID

Make sure you're using the id field from the Upsert Contact response

Don't try to create appointments without a valid Contact ID

Follow the proper workflow: Upsert Contact → Get Slots → Create Appointment

Issue: "Time Slot Not Available"

Symptoms: Appointment creation fails with slot conflict

Solutions:

Always call Get Calendar Free Slots before creating appointments

Don't assume a slot is available without checking

Make sure you're using an exact slot time from the Free Slots response

Check that the calendar hasn't been booked by someone else

Avoid using ignoreFreeSlotValidation: true unless absolutely necessary

Issue: "Invalid Date Format"

Symptoms: Appointment creation fails with date parsing error

Solutions:

Ensure startTime is in ISO 8601 format: YYYY-MM-DDTHH:mm:ss±HH:MM

Include timezone information: -04:00 or +05:30

Don't use Unix epoch for Create Appointment (only for Get Free Slots)

Example valid format: 2021-06-23T14:00:00-04:00

Issue: Missing Scopes

Symptoms: "Insufficient permissions" or "Scope not granted" errors

Solutions:

Verify you have the required scopes for each action:

Action	Required Scopes
Upsert Contact	`contacts.write`
Get Calendar Free Slots	`calendars.readonly` or `calendars.write`
Create Appointment	`calendars/events.write`

To fix:

Go to GoHighLevel Settings > Private Integrations

Edit your integration

Add the missing scopes

Copy the updated token

Update your action configuration with the new token

Issue: Actions Not Available in Campaign

Symptoms: Can't see or use actions in campaign

Solutions:

Verify actions were created and Add Toold successfully

Check that actions are enabled/active

Make sure you added the actions to the specific campaign

Refresh the campaign editor page

Verify you're in the correct campaign

Getting Help

If you continue to experience issues:

Check GoHighLevel Status: Verify the GoHighLevel API is operational

Review API Logs: Check for detailed error messages in action logs

Contact Support: Reach out with:

Action name

Error message

Steps to reproduce

Screenshots if available

Additional Resources

GoHighLevel API Documentation

GoHighLevel Support Portal

Atlas Actions Documentation

Appendix: Quick Reference

Required Credentials Summary

Credential	Where to Find	Used For
API Token	Settings > Private Integrations	All actions (authentication)
Location ID	URL when viewing location	Upsert Contact, Create Appointment
Calendar ID	Calendars page URL or settings	Get Free Slots, Create Appointment

Scopes Quick Reference

✅ contacts.write           → Upsert Contact
✅ calendars.readonly       → Get Calendar Free Slots
✅ calendars/events.write   → Create Appointment

GoHighLevel - Calendar Integration

📋 Table of Contents#

Overview#

Prerequisites#

Available Atlas Actions#

Setup Process#

Step 1: Obtain GoHighLevel Credentials#

Getting Your Location ID#

Getting Your API Key (V2 API - Recommended)#

Getting Your Calendar ID#

Step 2: Create Actions from Templates#

Creating GHL Upsert Contact Action#

Creating GHL Calendar Free Slots Action#

Creating GHL Create Appointment Action#

Action Details#

1. GHL Upsert Contact#

2. GHL Calendar Free Slots#

3. GHL Create Appointment#

Adding Actions to Campaigns#

Steps to Add Actions to a Campaign:#

Common Use Cases#

Use Case 1: Appointment Scheduling#

Use Case 2: Update Customer Information#

Use Case 3: Check Availability Only#

Troubleshooting#

Common Issues and Solutions#

Issue: "API Key Invalid" Error#

Issue: "Location ID Not Found"#

Issue: "Calendar ID Invalid"#

Issue: "Contact ID Required" Error#

Issue: "Time Slot Not Available"#

Issue: "Invalid Date Format"#

Issue: Missing Scopes#

Issue: Actions Not Available in Campaign#

Getting Help#

Additional Resources#

Appendix: Quick Reference#

Required Credentials Summary#

Scopes Quick Reference#

📋 Table of Contents

Overview

Prerequisites

Available Atlas Actions

Setup Process

Step 1: Obtain GoHighLevel Credentials

Getting Your Location ID

Getting Your API Key (V2 API - Recommended)

Getting Your Calendar ID

Step 2: Create Actions from Templates

Creating GHL Upsert Contact Action

Creating GHL Calendar Free Slots Action

Creating GHL Create Appointment Action

Action Details

1. GHL Upsert Contact

2. GHL Calendar Free Slots

3. GHL Create Appointment

Adding Actions to Campaigns

Steps to Add Actions to a Campaign:

Common Use Cases

Use Case 1: Appointment Scheduling

Use Case 2: Update Customer Information

Use Case 3: Check Availability Only

Troubleshooting

Common Issues and Solutions

Issue: "API Key Invalid" Error

Issue: "Location ID Not Found"

Issue: "Calendar ID Invalid"

Issue: "Contact ID Required" Error

Issue: "Time Slot Not Available"

Issue: "Invalid Date Format"

Issue: Missing Scopes

Issue: Actions Not Available in Campaign

Getting Help

Additional Resources

Appendix: Quick Reference

Required Credentials Summary

Scopes Quick Reference