gohighlevel

name: gohighlevel description: Comprehensive skill for integrating with the Go High Level (GHL) CRM platform via its REST API v2 and official Python SDK. Covers contacts, conversations, calendars, opportunities, payments, invoices, workflows, funnels, forms, surveys, social planner, courses, memberships, media, companies, custom fields, snapshots, SaaS, reputation management, and more. version: 1.1.0 requires: env: - GHL_API_KEY: "Go High Level API Bearer Token (OAuth 2.0 access token or Private Integration Token)" - GHL_LOCATION_ID: "The Location/Sub-Account ID for location-scoped API calls" - GHL_CLIENT_ID: "(Optional) OAuth Client ID for SDK-based integrations" - GHL_CLIENT_SECRET: "(Optional) OAuth Client Secret for SDK-based integrations" bins: - curl - python3 - pip

Go High Level (GHL) Platform Skill

Self-Updating Policy: If a feature or endpoint referenced in this skill is not working or returns an error, search the internet for the latest GHL API v2 documentation, verify the correct endpoint/payload, and update this skill accordingly. Always check the official docs for the most current information.

Table of Contents

1. Overview & Authentication
2. Official Python SDK (Recommended)
3. Base URL & Headers
4. Rate Limits
5. Contacts
6. Conversations
7. Calendars & Appointments
8. Opportunities (Pipelines & Deals)
9. Payments
10. Invoices
11. Workflows
12. Funnels & Websites
13. Forms
14. Surveys
15. Social Planner
16. Courses & Memberships
17. Media Storage
18. Companies
19. Custom Fields
20. Custom Values
21. Businesses
22. Users
23. Locations (Sub-Accounts)
24. Associations
25. Snapshots
26. SaaS API
27. Webhooks
28. Triggers
29. Blogs
30. Documents & Contracts
31. Reputation Management & Reviews
32. Email / SMS / Calls
33. Links
34. Tags
35. Notes & Tasks
36. Products & Prices
37. Object Records (Custom Objects)
38. OAuth & Marketplace Apps
39. Self-Update Instructions

1. Overview & Authentication

Go High Level (GHL) is an all-in-one CRM platform for agencies and businesses. The API v2 uses OAuth 2.0 exclusively for authentication.

Authentication Methods

OAuth 2.0 Flow

1. Register your app at marketplace.gohighlevel.com
2. Redirect users to the authorization URL
3. Exchange the authorization code for access and refresh tokens
4. Use the access token as a Bearer token in API calls
5. Refresh tokens before they expire (tokens last ~24 hours)

Authorization URL:

https://marketplace.gohighlevel.com/oauth/chooselocation
  ?response_type=code
  &redirect_uri=YOUR_REDIRECT_URI
  &client_id=YOUR_CLIENT_ID
  &scope=SCOPES

Token Exchange:

curl -X POST https://services.leadconnectorhq.com/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "grant_type=authorization_code" \
  -d "code=AUTH_CODE" \
  -d "redirect_uri=YOUR_REDIRECT_URI"

Token Refresh:

curl -X POST https://services.leadconnectorhq.com/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "grant_type=refresh_token" \
  -d "refresh_token=YOUR_REFRESH_TOKEN"

Available OAuth Scopes

2. Official Python SDK (Recommended)

Prefer the Python SDK over raw curl/HTTP calls. GHL publishes an official async Python client that handles OAuth token rotation, webhook signature validation, and provides typed service methods for every endpoint.

Installation

# pip
pip install gohighlevel-api-client

# poetry
poetry add gohighlevel-api-client

# pipenv
pipenv install gohighlevel-api-client

Requires: Python 3.8+

Quick Start — Initialize Client

from highlevel import HighLevel

client = HighLevel(
    client_id="your_client_id",
    client_secret="your_client_secret",
)

Make an API Call (Async)

The SDK is async-first. Wrap your logic in asyncio.run() when not already inside an async framework:

import asyncio
from highlevel import HighLevel

async def main():
    client = HighLevel(
        client_id="your_client_id",
        client_secret="your_client_secret",
    )

    # Search contacts
    response = await client.contacts.search_contacts_advanced({
        "locationId": "YOUR_LOCATION_ID",
        "pageLimit": 5,
    })
    print(response)

    # Get calendars
    calendars = await client.calendars.get_calendars({
        "locationId": "YOUR_LOCATION_ID",
    })
    print(calendars)

    # Create an opportunity
    opp = await client.opportunities.create_opportunity({
        "pipelineId": "PIPELINE_ID",
        "locationId": "YOUR_LOCATION_ID",
        "name": "New Deal",
        "status": "open",
        "contactId": "CONTACT_ID",
    })
    print(opp)

asyncio.run(main())

Session Storage (Token Persistence)

Use in-memory storage for local testing or swap in MongoDB/Redis for production:

from highlevel import HighLevel
from highlevel.storage import MongoDBSessionStorage

storage = MongoDBSessionStorage(
    connection_string="mongodb://localhost:27017",
    database_name="ghl_sessions",
    collection_name="jwt_tokens",
)

client = HighLevel(
    client_id="your_client_id",
    client_secret="your_client_secret",
    session_storage=storage,
)

Webhook Integration (Middleware)

The SDK provides webhook middleware that validates signatures, handles INSTALL/UNINSTALL events automatically, and keeps session storage synchronized:

from highlevel import HighLevel

client = HighLevel(
    client_id="your_client_id",
    client_secret="your_client_secret",
)

webhook_middleware = client.webhooks.subscribe()

@app.post("/api/webhooks/ghl")
async def handle_ghl_webhook(request):
    await webhook_middleware(request)
    # Your custom webhook logic goes here
    return {"status": "success"}

SDK Service Methods

The SDK exposes typed service namespaces matching the API modules:

SDK Features

• ✅ Auto token rotation — refresh happens transparently once storage is configured
• ✅ Webhook utilities — signature validation + automatic INSTALL/UNINSTALL handling
• ✅ Token for bulk installation — generates tokens for each location where app is installed
• ✅ Typed service methods — IDE autocompletion for all API operations
• ✅ Session storage adapters — In-memory, MongoDB, Redis, or custom
• ✅ Async-first — Built on asyncio for high-performance

SDK Resources

Also available: Node.js SDK (@gohighlevel/api-client via npm) and PHP SDK (gohighlevel/api-client via Composer).

3. Base URL & Headers

Base URL:

https://services.leadconnectorhq.com

Required Headers:

Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json
Version: 2021-07-28

Note: The Version header is required for all API calls. Use 2021-07-28 as the API version.

3. Rate Limits

Exceeding rate limits will return a 429 Too Many Requests error. Implement exponential backoff.

4. Contacts

The CRM's core entity. Full CRUD operations for managing leads and customers.

Endpoints

Create Contact Example

curl -X POST https://services.leadconnectorhq.com/contacts/ \
  -H "Authorization: Bearer $GHL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Version: 2021-07-28" \
  -d '{
    "firstName": "John",
    "lastName": "Doe",
    "email": "john@example.com",
    "phone": "+1234567890",
    "locationId": "'$GHL_LOCATION_ID'",
    "tags": ["new-lead", "website"],
    "source": "API",
    "customFields": [
      {
        "id": "CUSTOM_FIELD_ID",
        "value": "Custom Value"
      }
    ]
  }'

Search Contacts Example

curl -X GET "https://services.leadconnectorhq.com/contacts/?locationId=$GHL_LOCATION_ID&query=john&limit=20" \
  -H "Authorization: Bearer $GHL_API_KEY" \
  -H "Version: 2021-07-28"

Contact Object Fields

5. Conversations

Manage SMS, email, WhatsApp, and other communication channels.

Endpoints

Send SMS Example

curl -X POST https://services.leadconnectorhq.com/conversations/messages \
  -H "Authorization: Bearer $GHL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Version: 2021-07-28" \
  -d '{
    "type": "SMS",
    "contactId": "CONTACT_ID",
    "message": "Hello! This is a test message from the API."
  }'

Send Email Example

curl -X POST https://services.leadconnectorhq.com/conversations/messages \
  -H "Authorization: Bearer $GHL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Version: 2021-07-28" \
  -d '{
    "type": "Email",
    "contactId": "CONTACT_ID",
    "subject": "Test Email",
    "message": "<html><body><h1>Hello!</h1><p>This is a test email.</p></body></html>",
    "emailFrom": "Sender Name <sender@yourdomain.com>",
    "html": "<html><body><h1>Hello!</h1><p>This is a test email.</p></body></html>"
  }'

Message Types

6. Calendars & Appointments

Full scheduling system: calendars, calendar groups, events, free slots, and service bookings.

Calendar Endpoints

Calendar Groups

Calendar Events (Appointments)

Calendar Resources

Get Free Slots Example

curl -X GET "https://services.leadconnectorhq.com/calendars/{calendarId}/free-slots?startDate=2025-01-01&endDate=2025-01-31&timezone=America/New_York" \
  -H "Authorization: Bearer $GHL_API_KEY" \
  -H "Version: 2021-07-28"

Create Appointment Example

curl -X POST https://services.leadconnectorhq.com/calendars/events \
  -H "Authorization: Bearer $GHL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Version: 2021-07-28" \
  -d '{
    "calendarId": "CALENDAR_ID",
    "locationId": "'$GHL_LOCATION_ID'",
    "contactId": "CONTACT_ID",
    "startTime": "2025-02-01T10:00:00Z",
    "endTime": "2025-02-01T11:00:00Z",
    "title": "Consultation Call",
    "appointmentStatus": "confirmed",
    "assignedUserId": "USER_ID",
    "notes": "Initial consultation"
  }'

7. Opportunities (Pipelines & Deals)

Track sales pipelines, manage deals and their stages.

Endpoints

Pipelines

Create Opportunity Example

curl -X POST https://services.leadconnectorhq.com/opportunities/ \
  -H "Authorization: Bearer $GHL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Version: 2021-07-28" \
  -d '{
    "pipelineId": "PIPELINE_ID",
    "locationId": "'$GHL_LOCATION_ID'",
    "name": "New Deal - John Doe",
    "pipelineStageId": "STAGE_ID",
    "status": "open",
    "contactId": "CONTACT_ID",
    "monetaryValue": 5000,
    "assignedTo": "USER_ID",
    "source": "API"
  }'

Opportunity Status Values

8. Payments

Process payments, manage orders, subscriptions, transactions, and coupons.

Payment Integration Endpoints

Orders

Order Fulfillments

Transactions

Subscriptions

Coupons

Custom Payment Providers

9. Invoices

Full invoice lifecycle management: create, send, void, collect payments.

Invoice Endpoints

Invoice Templates

Invoice Schedules

Text2Pay

Estimates

Create Invoice Example

curl -X POST https://services.leadconnectorhq.com/invoices/ \
  -H "Authorization: Bearer $GHL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Version: 2021-07-28" \
  -d '{
    "altId": "'$GHL_LOCATION_ID'",
    "altType": "location",
    "name": "Invoice #001",
    "contactDetails": {
      "id": "CONTACT_ID",
      "name": "John Doe",
      "email": "john@example.com"
    },
    "items": [
      {
        "name": "Consulting Service",
        "description": "1 hour consulting session",
        "quantity": 1,
        "price": 15000
      }
    ],
    "currency": "USD",
    "dueDate": "2025-03-01"
  }'

10. Workflows

Manage automations and workflow executions.

Endpoints

Note: Workflow creation/editing is primarily done through the GHL UI. The API allows you to list workflows and add/remove contacts from them programmatically (see Contacts section).

11. Funnels & Websites

Manage sales funnels, landing pages, and website pages.

Funnel Endpoints

Funnel Redirect Endpoints

List Funnels Example

curl -X GET "https://services.leadconnectorhq.com/funnels/?locationId=$GHL_LOCATION_ID" \
  -H "Authorization: Bearer $GHL_API_KEY" \
  -H "Version: 2021-07-28"

12. Forms

Manage forms, form submissions, and form data.

Endpoints

Get Form Submissions Example

curl -X GET "https://services.leadconnectorhq.com/forms/submissions?locationId=$GHL_LOCATION_ID&page=1&limit=20" \
  -H "Authorization: Bearer $GHL_API_KEY" \
  -H "Version: 2021-07-28"

13. Surveys

Manage surveys and survey responses.

Endpoints

Get Survey Submissions Example

curl -X GET "https://services.leadconnectorhq.com/surveys/submissions?locationId=$GHL_LOCATION_ID" \
  -H "Authorization: Bearer $GHL_API_KEY" \
  -H "Version: 2021-07-28"

Submission filter parameters: surveyId, contactId, q (search by name/email/phone), startAt, endAt, page, limit

14. Social Planner

Manage social media posts, accounts, and OAuth connections.

Social Media Posts

Social Media Accounts

Social Media OAuth

Supported Social Platforms

Create Social Post Example

curl -X POST https://services.leadconnectorhq.com/social-media-posting/posts \
  -H "Authorization: Bearer $GHL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Version: 2021-07-28" \
  -d '{
    "locationId": "'$GHL_LOCATION_ID'",
    "accountIds": ["ACCOUNT_ID"],
    "type": "post",
    "summary": "Check out our latest offers!",
    "media": [
      {
        "type": "image",
        "url": "https://example.com/image.jpg"
      }
    ],
    "scheduledAt": "2025-03-01T10:00:00Z",
    "status": "scheduled"
  }'

15. Courses & Memberships

Manage online courses, enrollments, lessons, and certificates.

Course Endpoints

Course Enrollment

Course Lessons

Course Certificates

Course Webhooks

16. Media Storage

Upload, manage, and organize files and folders.

Endpoints

Upload File Example

curl -X POST https://services.leadconnectorhq.com/medias/upload-file \
  -H "Authorization: Bearer $GHL_API_KEY" \
  -H "Version: 2021-07-28" \
  -F "file=@/path/to/file.png" \
  -F "locationId=$GHL_LOCATION_ID" \
  -F "name=my-image.png"

File Size Limits

17. Companies

Manage company records and their associations.

Endpoints

Create Company Example

curl -X POST https://services.leadconnectorhq.com/companies/ \
  -H "Authorization: Bearer $GHL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Version: 2021-07-28" \
  -d '{
    "name": "Acme Corp",
    "locationId": "'$GHL_LOCATION_ID'",
    "phone": "+1234567890",
    "email": "info@acme.com",
    "website": "https://acme.com",
    "address": "123 Main St",
    "city": "New York",
    "state": "NY",
    "postalCode": "10001",
    "country": "US"
  }'

18. Custom Fields

Create and manage custom data fields across contacts, opportunities, companies, and more.

Endpoints

Custom Field Data Types

Create Custom Field Example

curl -X POST https://services.leadconnectorhq.com/custom-fields/ \
  -H "Authorization: Bearer $GHL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Version: 2021-07-28" \
  -d '{
    "name": "Preferred Contact Method",
    "dataType": "SINGLE_OPTIONS",
    "locationId": "'$GHL_LOCATION_ID'",
    "model": "contact",
    "options": [
      {"value": "email", "name": "Email"},
      {"value": "phone", "name": "Phone"},
      {"value": "sms", "name": "SMS"}
    ]
  }'

19. Custom Values

Dynamic placeholders that can be used across the platform (emails, SMS, funnels, etc.).

Endpoints

Create Custom Value Example

curl -X POST https://services.leadconnectorhq.com/custom-values/ \
  -H "Authorization: Bearer $GHL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Version: 2021-07-28" \
  -d '{
    "name": "Business Hours",
    "value": "Mon-Fri 9AM-5PM EST",
    "locationId": "'$GHL_LOCATION_ID'"
  }'

20. Businesses

Manage business entities within a location.

Endpoints

21. Users

Manage users and team members within the platform.

Endpoints

22. Locations (Sub-Accounts)

Manage sub-accounts within an agency account.

Endpoints

23. Associations

Manage relationships between entities (contacts, companies, opportunities, custom objects).

Endpoints

24. Snapshots

Manage account configuration templates (snapshots).

Endpoints

List Snapshots Example

curl -X GET "https://services.leadconnectorhq.com/snapshots/?companyId=YOUR_COMPANY_ID" \
  -H "Authorization: Bearer $GHL_API_KEY" \
  -H "Version: 2021-07-28"

25. SaaS API

For agencies reselling GHL as white-label SaaS.

Endpoints

26. Webhooks

Configure real-time event notifications.

Endpoints

Available Webhook Events

Create Webhook Example

curl -X POST https://services.leadconnectorhq.com/webhooks/ \
  -H "Authorization: Bearer $GHL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Version: 2021-07-28" \
  -d '{
    "locationId": "'$GHL_LOCATION_ID'",
    "url": "https://your-server.com/webhook",
    "events": ["ContactCreate", "ContactUpdate", "AppointmentCreate"],
    "secret": "your-webhook-secret"
  }'

27. Triggers

Workflow triggers for automating actions based on events.

Built-in Trigger Categories

Marketplace Workflow Triggers

Developers can create custom triggers that push data from external apps into GHL workflows:

curl -X POST https://services.leadconnectorhq.com/workflows/triggers \
  -H "Authorization: Bearer $GHL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Version: 2021-07-28" \
  -d '{
    "locationId": "'$GHL_LOCATION_ID'",
    "triggerId": "CUSTOM_TRIGGER_ID",
    "contactId": "CONTACT_ID",
    "data": {
      "key1": "value1",
      "key2": "value2"
    }
  }'

28. Blogs

Manage blog posts, authors, and categories.

Endpoints

29. Documents & Contracts

Manage documents, contracts, and e-signatures.

Endpoints

Document Webhook Events

30. Reputation Management & Reviews

Manage review requests, monitor reviews, and respond to feedback.

Capabilities

• Automated review requests via SMS and email after customer interactions
• Review monitoring across Google and Facebook
• Centralized response management from one dashboard
• Sentiment analysis for incoming reviews
• Workflow triggers based on review events

Note: Reputation management is primarily managed within GHL workflows. Use Contact and Conversation APIs to automate review request sending. Use webhooks to listen for review-related events.

Automated Review Request Workflow

1. Use the Contacts API to identify customers who completed a service
2. Send an SMS/email using the Conversations API with a review link
3. Set up webhooks to monitor review responses
4. Use workflows to handle positive vs. negative review routing

31. Email / SMS / Calls

Sending Communications

All communication is handled through the Conversations API (Section 5):

Voicemail & Call Recordings

• Access call recordings via /conversations/{conversationId}/messages/{messageId}/recordings
• Inbound call webhook payloads include recordingUrl when available
• Configure voicemail drops in workflow actions

32. Links

Manage tracking links and URLs.

Link (Trigger Link) Endpoints

33. Tags

Manage tags for contacts and other entities.

Endpoints (via Locations API)

Apply/Remove Tags on Contacts

34. Notes & Tasks

Manage notes and tasks attached to contacts.

Notes Endpoints

Tasks Endpoints

35. Products & Prices

Manage products and their pricing.

Products Endpoints

Prices Endpoints

Create Product Example

curl -X POST https://services.leadconnectorhq.com/products/ \
  -H "Authorization: Bearer $GHL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Version: 2021-07-28" \
  -d '{
    "locationId": "'$GHL_LOCATION_ID'",
    "name": "Premium Consulting Package",
    "description": "Monthly consulting package",
    "productType": "DIGITAL",
    "availableInStore": true
  }'

36. Object Records (Custom Objects)

Manage custom object records for extending the CRM data model.

Endpoints

37. OAuth & Marketplace Apps

Building a Marketplace App

1. Register at marketplace.gohighlevel.com
2. Create an app with required scopes
3. Set redirect URI for OAuth callbacks
4. Implement OAuth flow (see Section 1)
5. Submit for review (for public apps)
6. Distribute via GHL Marketplace

App Distribution Types

Private Integration Token

For single-account use without full OAuth flow:

1. Go to Settings → Integrations → Private Integrations in GHL
2. Create a new integration
3. Select required scopes
4. Copy the generated token
5. Use as Bearer token in API calls

38. Self-Update Instructions

IMPORTANT: This skill should be kept up-to-date with the latest GHL API changes.

When to Update This Skill

1. API call fails with a 404 or unexpected error → search for the correct endpoint
2. New feature needed not listed here → research the GHL documentation
3. Endpoint changed or deprecated → update the affected section
4. New webhook event available → add to the webhooks section
5. Rate limits changed → update Section 3

How to Update

1. Search the official docs: Visit marketplace.gohighlevel.com/docs/
2. Search GitHub docs: Check github.com/GoHighLevel/highlevel-api-docs
3. Search the web: Look for "Go High Level API v2 [feature name] endpoint"
4. Verify the endpoint by making a test API call
5. Update this SKILL.md with the correct information
6. Add examples for any new endpoints

Official Resources

Changelog

Quick Reference: All API Base Paths