highlevel

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.

# 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**](https://gohighlevel.com/5-day-challenge?fp_ref=369ai)

## 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:

```bash
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
5. Click **"Create new Integration"**
6. Enter a name (e.g., "Claude AI Assistant") and description
7. **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.

8. 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
```bash
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.

| # | Group | Base Path | Key Operations | Scope Prefix |
|---|-------|-----------|----------------|-------------|
| 1 | **Contacts** | `/contacts/` | CRUD, search, upsert, tags, notes, tasks, bulk ops | `contacts` |
| 2 | **Conversations** | `/conversations/` | Search, messages (SMS/email/WhatsApp/FB/IG/chat), recordings | `conversations` |
| 3 | **Calendars** | `/calendars/` | CRUD, free slots, groups, resources, appointments | `calendars` |
| 4 | **Opportunities** | `/opportunities/` | CRUD, search, pipelines, stages, status, followers | `opportunities` |
| 5 | **Workflows** | `/workflows/` | List workflows, enroll/remove contacts | `workflows` |
| 6 | **Campaigns** | `/campaigns/` | List campaigns (read-only) | `campaigns` |
| 7 | **Invoices** | `/invoices/` | CRUD, send, void, record payment, Text2Pay, schedules, estimates | `invoices` |
| 8 | **Payments** | `/payments/` | Orders, transactions, subscriptions, coupons, providers | `payments` |
| 9 | **Products** | `/products/` | CRUD, prices, collections, reviews, store stats | `products` |
| 10 | **Locations** | `/locations/` | Get/update location, custom fields, custom values, tags, templates | `locations` |
|    | | | **Custom Fields CRUD:** | |
|    | | | `GET /locations/{id}/customFields` — List | |
|    | | | `POST /locations/{id}/customFields` — Create | |
|    | | | `PUT /locations/{id}/customFields/{fid}` — Update | |
|    | | | `DELETE /locations/{id}/customFields/{fid}` — Delete | |
|    | | | **Custom Values CRUD:** | |
|    | | | `GET /locations/{id}/customValues` — List | |
|    | | | `POST /locations/{id}/customValues` — Create | |
|    | | | `PUT /locations/{id}/custo