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#

RequirementDetailsRuntimePython 3.6+ (uses only standard library: urllib, json, os, re, sys, time)External packages****None — zero pip install requiredEnvironment variablesHIGHLEVEL_TOKEN (Primary — your Private Integration bearer token)HIGHLEVEL_LOCATION_ID (your sub-account Location ID)Network accessHTTPS 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 caseRecommended scopesContact management onlycontacts.readonly, contacts.writeContacts + messagingAbove + conversations.readonly, conversations.write, conversations/message.writeFull CRM (contacts, calendar, pipeline)Above + calendars.readonly, calendars.write, opportunities.readonly, opportunities.writeAdding workflows & invoicesAbove + workflows.readonly, invoices.readonly, invoices.writeRead-only reportingcontacts.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

FeatureAgency IntegrationSub-Account IntegrationCreated atAgency Settings → Private IntegrationsSub-Account Settings → Private IntegrationsAccess scopeAgency + all sub-accounts (pass locationId)Single location onlyAvailable scopesAll scopes including locations.write, oauth.*, saas.*, snapshots.*, companies.readonlySub-account scopes onlyBest forMulti-location management, SaaS configuratorSingle 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:

CommandDescriptiontest_connectionVerify token + location ID worksearch_contacts [query]Search by name, email, or phoneget_contact [id]Get full contact detailscreate_contact [json]Create new contactupdate_contact [id] [json]Update contact fieldslist_opportunitiesList pipeline opportunitieslist_conversationsList recent conversationssend_message [contactId] [message]Send SMS/emaillist_calendarsList all calendarsget_free_slots [calendarId] [startDate] [endDate]Available booking slotslist_workflowsList all workflowsadd_to_workflow [contactId] [workflowId]Enroll contact in workflowlist_invoicesList invoiceslist_productsList productslist_formsList formslist_campaignsList campaignsget_location_detailsGet location infolist_location_tagsList location tagslist_coursesList 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.

#GroupBase PathKey OperationsScope Prefix1Contacts/contacts/CRUD, search, upsert, tags, notes, tasks, bulk opscontacts2Conversations/conversations/Search, messages (SMS/email/WhatsApp/FB/IG/chat), recordingsconversations3Calendars/calendars/CRUD, free slots, groups, resources, appointmentscalendars4Opportunities/opportunities/CRUD, search, pipelines, stages, status, followersopportunities5Workflows/workflows/List workflows, enroll/remove contactsworkflows6Campaigns/campaigns/List campaigns (read-only)campaigns7Invoices/invoices/CRUD, send, void, record payment, Text2Pay, schedules, estimatesinvoices8Payments/payments/Orders, transactions, subscriptions, coupons, providerspayments9Products/products/CRUD, prices, collections, reviews, store statsproducts10Locations/locations/Get/update location, custom fields, custom values, tags, templateslocationsCustom Fields CRUD:GET /locations/{id}/customFields — ListPOST /locations/{id}/customFields — CreatePUT /locations/{id}/customFields/{fid} — UpdateDELETE /locations/{id}/customFields/{fid} — DeleteCustom Values CRUD:GET /locations/{id}/customValues — ListPOST /locations/{id}/customValues — CreatePUT /locations/{id}/customValues/{vid} — UpdateDELETE /locations/{id}/customValues/{vid} — DeleteTags CRUD:GET /locations/{id}/tags — ListPOST /locations/{id}/tags — CreatePUT /locations/{id}/tags/{tid} — UpdateDELETE /locations/{id}/tags/{tid} — Delete11Users/users/CRUD, filter by email/roleusers12Forms/forms/List forms, get submissionsforms13Surveys/surveys/List surveys, get submissionssurveys14Funnels/funnels/List funnels, pages, redirectsfunnels15Social Planner/social-media-posting/Posts CRUD, accounts, CSV import, categories, statssocialplanner16Blogs/blogs/Create/update posts, categories, authorsblogs17Email/emails/Templates CRUD, scheduled emailsemails18Media/medias/Upload, list, delete filesmedias19Trigger Links/links/CRUD trigger linkslinks20Businesses/businesses/CRUD businessesbusinesses21Companies/companies/Get company details (Agency)companies22Custom Objects/objects/Schema CRUD, record CRUDobjects23Associations/associations/CRUD associations and relationsassociations24Proposals/Docs/proposals/Documents, contracts, templatesdocuments_contracts25Snapshots/snapshots/List, status, share links (Agency)snapshots26SaaS/saas/Subscription mgmt, plans, bulk ops (Agency $497)saas27Courses/courses/Import courses/membershipscourses28Voice AI/voice-ai/Call logs, agent CRUD, actions, goalsvoice-ai29Phone System/phone-system/Phone numbers, number poolsphonenumbers30Custom Menus/custom-menus/CRUD custom menu links (Agency)custom-menu-link31OAuth/oauth/Token exchange, installed locationsoauth32Marketplace/marketplace/Installations, billing, chargesmarketplace33Conversation AI/conversation-ai/AI chatbot configuration—34Knowledge Base/knowledge-base/Knowledge base for AI features—35AI Agent Studio/agent-studio/Custom AI agent CRUD—36Brand Boards/brand-boards/Brand board management—37Store/store/E-commerce store management—38LC Email/lc-email/Email infrastructure (ISV)—39Custom Fields/locations/:id/customFields/Custom field CRUDlocations/customFields

Reference Docs (load on demand)#

For detailed endpoint paths, parameters, and examples for each group:

• references/contacts.md — Contact CRUD, search, tags, notes, tasks, bulk operations
• references/conversations.md — Messaging across all channels, recordings, transcriptions
• references/calendars.md — Calendar CRUD, free slots, appointments, groups, resources
• references/opportunities.md — Pipeline management, stages, status updates
• references/invoices-payments.md — Invoices, payments, orders, subscriptions, products
• references/locations-users.md — Location settings, custom fields/values, users, tags
• references/social-media.md — Social planner posts, accounts, OAuth connections
• references/forms-surveys-funnels.md — Forms, surveys, funnels, trigger links
• references/advanced.md — Custom objects, associations, snapshots, SaaS, Voice AI, blogs, courses
• references/troubleshooting.md — Common errors, rate limits, token rotation, debugging

Important Notes#

• Private Integrations are required — the old Settings → API Keys method is deprecated/EOL

• Token rotation: Tokens don't auto-expire but GHL recommends 90-day rotation. Unused tokens auto-expire after 90 days inactivity

  • "Rotate and expire later" — new token generated, old token stays active for 7-day grace period
  • "Rotate and expire now" — old token invalidated immediately (use for compromised credentials)
  • You can edit scopes without regenerating the token

• OAuth tokens (marketplace apps only): Access tokens expire in 24 hours (86,399s); refresh tokens last up to 1 year

• Agency tokens can access sub-account data by passing locationId parameter

• Rate limits are per-resource — each sub-account independently gets 100/10s burst + 200K/day. SaaS endpoints: 10 req/sec global

• All list endpoints default to 20 records, max 100 per page via limit param

• Use cursor pagination with startAfter / startAfterId for large datasets

• Monitor rate limits via response headers: X-RateLimit-Limit-Daily, X-RateLimit-Daily-Remaining, X-RateLimit-Max, X-RateLimit-Remaining, X-RateLimit-Interval-Milliseconds

• $497 Agency Pro plan required for: SaaS Configurator, Snapshots, full agency management APIs

Webhook Events#

50+ webhook event types for real-time notifications. Key events: ContactCreate, ContactDelete, ContactTagUpdate, InboundMessage, OutboundMessage, OpportunityCreate, OpportunityStageUpdate, OpportunityStatusUpdate, appointment events, payment events, form submission events. Webhooks continue firing even if access token expires. Config is per marketplace app. Docs: https://marketplace.gohighlevel.com/docs/webhook/WebhookIntegrationGuide

Official SDKs & Developer Resources#

• Node.js: @gohighlevel/api-client (npm) — supports privateIntegrationToken config, auto 401 retry
• Python: gohighlevel-api-client (PyPI) — session storage, auto token refresh, webhook middleware
• PHP SDK also available
• All SDKs use apiVersion: '2021-07-28'
• OpenAPI Specs: https://github.com/GoHighLevel/highlevel-api-docs
• API Docs: https://marketplace.gohighlevel.com/docs/
• Developer Slack: https://developers.gohighlevel.com/join-dev-community

---

Built by Ty Shane#

🌐 LaunchMyOpenClaw.com • 🌐 MyFBLeads.com ▶️ YouTube @10xcoldleads • 📘 Facebook • 💼 LinkedIn 📧 ty@10xcoldleads.com

No GoHighLevel account yet? → Start the free 5-Day AI Employee Challenge