GoHighLevel API Guide

Source: ai-research/ghl-2026-05-01/support-solutions-articles-48001060529-highlevel-api-documentation.md, ai-research/ghl-2026-05-01/docs.md

Practical reference for the GoHighLevel API V2. GHL exposes a comprehensive REST API for CRM operations, messaging, calendars, pipelines, social posting, blogs, media, and more. Authentication is either a Private Integration Token (single-location or single-agency) or OAuth 2.0 (multi-location marketplace apps). All endpoints share a single base URL.

Authentication

• Private Integration Token (PIT) — simpler option, scoped to a single location or agency. Generated in Settings > Integrations > Private Integrations. See Private Integration Tokens for details
• OAuth 2.0 — required for marketplace apps that need multi-location access. Authorization-code flow with redirect URL. See OAuth 2.0
• All requests use Authorization: Bearer {token} header
• PIT tokens do not expire but can be revoked. OAuth tokens expire and require refresh

Base configuration

• Base URL: https://services.leadconnectorhq.com
• API Version: 2021-07-28 (V2 only — V1 is end-of-support, no new features)
• Required headers: Authorization: Bearer {token}, Version: 2021-07-28, Content-Type: application/json
• Developer portal: marketplace.gohighlevel.com/docs/
• GitHub docs: github.com/GoHighLevel/highlevel-api-docs

Rate limits

• 200,000 requests per day per app per resource (location or company)
• That is roughly 2.3 requests/second sustained over 24 hours
• Per-endpoint burst limits may apply
• Rate limit headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset
• See API Rate Limits for full handling guidance

Key endpoints

Contacts

• GET /contacts/ — list contacts with pagination
• GET /contacts/{id} — single contact with all fields
• POST /contacts/ — create contact (email, phone, name, tags, custom fields)
• PUT /contacts/{id} — update contact
• DELETE /contacts/{id} — delete contact
• GET /contacts/search — search by email, phone, name, tags
• POST /contacts/{id}/tags — add tags
• DELETE /contacts/{id}/tags — remove tags
• Use cases: Lead import, tagging automation, CRM sync, contact enrichment

Conversations

• GET /conversations/ — list conversation threads
• GET /conversations/{id} — single conversation with messages
• POST /conversations/messages — send SMS or email
• GET /conversations/messages/{id} — single message
• See Conversations API: Add Inbound Message for the inbound-message endpoint
• Use cases: Automated follow-up, message history analysis, response time tracking

Calendars

• GET /calendars/ — list calendars
• GET /calendars/{id}/free-slots — check availability
• POST /calendars/events/appointments — book an appointment
• PUT /calendars/events/appointments/{id} — reschedule
• DELETE /calendars/events/appointments/{id} — cancel
• Use cases: Appointment booking, availability checks, scheduling automation

Opportunities / Pipelines

• GET /opportunities/ — list deals in a pipeline
• POST /opportunities/ — create a deal
• PUT /opportunities/{id} — update deal stage, value, contact
• GET /opportunities/pipelines — list all pipelines and stages
• Use cases: Deal tracking, pipeline reporting, conversion analysis

Workflows

• Cannot create or edit workflows via API — workflows are built in the GHL visual editor only
• POST /hooks/ — create a webhook that triggers a workflow
• Inbound webhooks fire workflow triggers
• Outbound webhooks send GHL events to external systems
• See Webhooks for setup and event reference
• Use cases: Trigger automations from external events, sync GHL data outward

Payments

• GET /payments/orders — list transactions
• GET /payments/subscriptions — list active subscriptions
• GET /payments/transactions/{id} — transaction details
• Use cases: Revenue reporting, subscription management

Social Planner

• POST /social-media-posting/ — schedule a social post
• GET /social-media-posting/ — list scheduled posts
• DELETE /social-media-posting/{id} — cancel scheduled post
• Use cases: Cross-platform publishing, content calendar management

Blogs

• POST /blogs/ — create blog post
• PUT /blogs/{id} — update blog post
• GET /blogs/ — list posts
• Use cases: SEO content publishing, content pipeline automation

Media

• POST /medias/upload-file — upload images, videos, documents
• GET /medias/ — list media library
• Use cases: Asset management, image upload for blog/social posts

Webhooks (Outbound)

• POST /webhooks/ — register an outbound webhook
• Events: contact.create, contact.update, appointment.create, opportunity.stageUpdate, invoice.paid, etc.
• Use cases: Real-time event sync to external systems, alerting

For a fuller endpoint catalog, see API Endpoints Overview.

Example: List sub-accounts

curl -s "https://services.leadconnectorhq.com/locations/search" \
  -H "Authorization: Bearer $GHL_API_KEY" \
  -H "Version: 2021-07-28" \
  -H "Content-Type: application/json" \
  -d '{"companyId": "your-company-id"}'

Example: Create a contact

curl -s "https://services.leadconnectorhq.com/contacts/" \
  -H "Authorization: Bearer $GHL_API_KEY" \
  -H "Version: 2021-07-28" \
  -H "Content-Type: application/json" \
  -d '{
    "locationId": "your-location-id",
    "firstName": "Jane",
    "lastName": "Doe",
    "email": "jane@example.com",
    "phone": "+15551234567",
    "tags": ["new-lead", "website-form"]
  }'

Example: Send an SMS

curl -s "https://services.leadconnectorhq.com/conversations/messages" \
  -H "Authorization: Bearer $GHL_API_KEY" \
  -H "Version: 2021-07-28" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "SMS",
    "contactId": "your-contact-id",
    "message": "Thanks for reaching out — we will be in touch shortly."
  }'

Key Takeaways

• GHL API V2 is a comprehensive REST API covering CRM, messaging, scheduling, pipelines, social, and content — all from one base URL
• PIT auth is simpler than OAuth for single-agency use; OAuth 2.0 is required for marketplace apps spanning multiple locations
• Rate limits are generous (200K/day per app per resource) — unlikely to be a bottleneck for reporting or automation use cases
• Workflows cannot be created via API, only triggered via webhooks. The visual editor remains the only way to build them
• The API is the foundation for MCP integration — every endpoint exposed via the API can be wrapped in an MCP tool
• Treat scopes as the gating concern: a token’s effective surface is the intersection of the API endpoints and the scopes granted at token creation. See API Security

Related

• GoHighLevel Overview — Platform context and what GHL replaces
• Private Integration Tokens — PIT setup and scope reference
• OAuth 2.0 — Marketplace-app auth flow
• API Rate Limits — Limits, headers, and backoff strategy
• API Security — Token handling, scope minimization, audit logging
• Webhooks — Inbound and outbound event flows
• API Endpoints Overview — Full endpoint catalog
• API Troubleshooting — Common errors and fixes
• MCP Integration — Wrapping these endpoints in MCP tools for Claude Code

Try It

1. Generate a Private Integration Token in Settings > Integrations > Private Integrations with the scopes you need
2. Test the working endpoints with curl using the examples above — start with GET /locations/search to confirm auth
3. Walk through each endpoint category (contacts, conversations, calendars, opportunities) with simple GET requests before building integrations
4. Bookmark the developer portal at marketplace.gohighlevel.com/docs/ for full endpoint reference
5. When ready to build, follow MCP Integration to expose these endpoints to Claude Code