--- name: highlevel version: 1.2.0 description: "Connect your AI assistant to GoHighLevel CRM via the official API v2. Manage contacts, conversations, calendars, pipelines, invoices, payments, workflows, and 30+ endpoint groups through natural language. Includes interactive setup wizard and 100+ pre-built, safe API commands. Python 3.6+ stdlib only — zero external dependencies." tags: [gohighlevel, crm, api, contacts, conversations, calendars, opportunities, invoices, workflows, automation] author: Ty Shane homepage: https://launchmyopenclaw.com metadata: author: Ty Shane version: "1.2.0" clawdbot: emoji: 🦞 homepage: "https://launchmyopenclaw.com" requires: env: - HIGHLEVEL_TOKEN - HIGHLEVEL_LOCATION_ID compatibility: "Requires Python 3.6+ (stdlib only, no pip installs). Requires two environment variables: HIGHLEVEL_TOKEN and HIGHLEVEL_LOCATION_ID." ---

GoHighLevel API Skill

> Turn your AI assistant into a GoHighLevel command center. Search contacts, send messages, book appointments, manage pipelines, create invoices, schedule social posts — across all 39 GHL API v2 endpoint groups, using plain English.

Don't have GoHighLevel yet? Start with the free 5-Day AI Employee Challenge and build a fully automated system: 👉 Start the 5-Day AI Employee Challenge

Requirements

| Requirement | Details | |-------------|---------| | Runtime | Python 3.6+ (uses only standard library: urllib, json, os, re, sys, time) | | External packages | None — zero pip install required | | Environment variables | HIGHLEVEL_TOKEN (Primary — your Private Integration bearer token) | | | HIGHLEVEL_LOCATION_ID (your sub-account Location ID) | | Network access | HTTPS to services.leadconnectorhq.com only |

Base URL: https://services.leadconnectorhq.com Required Headers: Authorization: Bearer $HIGHLEVEL_TOKEN + Version: 2021-07-28 Rate Limits: 100 requests/10 seconds burst, 200K/day per location

Security Design

All API functions use pre-defined endpoint paths — there is no arbitrary HTTP request capability. Every user-supplied ID is validated against a strict alphanumeric regex (^[a-zA-Z0-9_-]{1,128}$) before being included in any URL path, preventing path traversal and injection. The scripts use only Python's built-in urllib.request for all network calls. No shell commands, no external binaries, no file writes outside of stdout.

Setup — /highlevel-setup

If the user says "set up highlevel", "connect my GHL", or /highlevel-setup, run the setup wizard:

python3 scripts/setup-wizard.py

The wizard automatically: checks environment variables → guides Private Integration creation → tests the connection → pulls first 5 contacts as a quick win.

Manual Setup (if wizard can't run)

Step 1: Create a Private Integration (NOT the old API Keys method)

1. Log into app.gohighlevel.com
2. Switch to your Sub-Account (recommended for single-location use)
3. Click Settings (bottom-left gear icon)
4. Select Private Integrations in the left sidebar

- If not visible, enable it first: Settings → Labs → toggle Private Integrations ON

1. Click "Create new Integration"
2. Enter a name (e.g., "Claude AI Assistant") and description
3. Grant only the scopes you need (least-privilege recommended):

| Use case | Recommended scopes | |----------|--------------------| | Contact management only | contacts.readonly, contacts.write | | Contacts + messaging | Above + conversations.readonly, conversations.write, conversations/message.write | | Full CRM (contacts, calendar, pipeline) | Above + calendars.readonly, calendars.write, opportunities.readonly, opportunities.write | | Adding workflows & invoices | Above + workflows.readonly, invoices.readonly, invoices.write | | Read-only reporting | contacts.readonly, opportunities.readonly, calendars.readonly, invoices.readonly, locations.readonly |

You can always add more scopes later in Settings → Private Integrations → Edit without regenerating the token.

1. Click Create → Copy the token IMMEDIATELY — it is shown only once and cannot be retrieved later

Agency vs Sub-Account Integrations

| Feature | Agency Integration | Sub-Account Integration | |---------|-------------------|------------------------| | Created at | Agency Settings → Private Integrations | Sub-Account Settings → Private Integrations | | Access scope | Agency + all sub-accounts (pass locationId) | Single location only | | Available scopes | All scopes including locations.write, oauth., saas., snapshots.*, companies.readonly | Sub-account scopes only | | Best for | Multi-location management, SaaS configurator | Single client integrations (recommended default) |

> Recommendation: Start with a Sub-Account integration and the minimum scopes you need. You can upgrade to Agency-level later if you need multi-location access.

Step 2: Get Your Location ID

1. While in the sub-account, go to Settings → Business Info (or Business Profile)
2. The Location ID is displayed in the General Information section
3. Alternative: check the URL bar — it's the ID after /location/ in app.gohighlevel.com/v2/location/{LOCATION_ID}/...

Step 3: Set Environment Variables

export HIGHLEVEL_TOKEN="your-private-integration-token"
export HIGHLEVEL_LOCATION_ID="your-location-id"

Step 4: Test Connection

Run python3 scripts/ghl-api.py test_connection — should return location name and status.

After successful setup, pull 5 contacts as a quick win to confirm everything works.

Helper Script

scripts/ghl-api.py — Executable Python script (stdlib only) with built-in retry logic, pagination, input validation, and error handling.

Core Commands: | Command | Description | |---------|-------------| | test_connection | Verify token + location ID work | | search_contacts [query] | Search by name, email, or phone | | get_contact [id] | Get full contact details | | create_contact [json] | Create new contact | | update_contact [id] [json] | Update contact fields | | list_opportunities | List pipeline opportunities | | list_conversations | List recent conversations | | send_message [contactId] [message] | Send SMS/email | | list_calendars | List all calendars | | get_free_slots [calendarId] [startDate] [endDate] | Available booking slots | | list_workflows | List all workflows | | add_to_workflow [contactId] [workflowId] | Enroll contact in workflow | | list_invoices | List invoices | | list_products | List products | | list_forms | List forms | | list_campaigns | List campaigns | | get_location_details | Get location info | | list_location_tags | List location tags | | list_courses | List courses/memberships |

All functions are safe, pre-defined endpoints. No arbitrary request capability.

Complete API v2 Coverage (39 Endpoint Groups)

The skill provides safe, specific functions for all major GHL operations. Each function maps to a specific, allowed API endpoint with validated parameters.

...