GoHighLevel API & Private Integrations Guide (2026)

By Dr Priya Jaganathan, GoHighLevel Certified Admin · HL Growth Partner, Australia · Updated 3 August 2026 · 9 min read

On this page: What the API is · API 1.0 vs 2.0 · Private Integration tokens · PIT vs OAuth vs Zapier/Make · Common endpoints · Webhooks vs polling · When native tools are enough · Security practices · Agency use cases · Common mistakes · FAQ

The GoHighLevel API is the layer that turns HighLevel from a closed CRM into a genuine platform. Every contact record, pipeline stage, calendar slot and conversation thread you see in the app is reachable programmatically — which means anything the interface won't do for you, code can. I build on it weekly for Australian agency clients, and the difference between a clean integration and a fragile one almost always comes down to decisions made in the first hour: which authentication method, which scopes, and whether you actually needed the API at all.

This guide covers the practical path: how API 2.0 differs from the deprecated 1.0, when a Private Integration token beats a full OAuth marketplace app, the endpoints you'll touch most, and the security habits that stop a convenient token becoming a liability. No hype — just what I'd tell a client scoping their first custom build.

What the GoHighLevel API actually is

API 2.0 is a REST API served under the LeadConnector brand (the white-label identity HighLevel uses for its infrastructure — you'll see services.leadconnectorhq.com as the base URL). You authenticate with a bearer token, send JSON, and get JSON back. It covers contacts, opportunities, calendars, conversations, custom fields, users, locations, payments, blogs, social posting and more, with new endpoint groups added most quarters.

The official reference lives at the GoHighLevel API documentation, which includes schemas, scope requirements per endpoint and a try-it console. Bookmark it; the docs are versioned and the platform moves quickly.

API 1.0 vs API 2.0: use 2.0, full stop

API 1.0 used simple location-level API keys under rest.gohighlevel.com. It's deprecated. HighLevel stopped adding endpoints to it years ago, and 1.0 keys grant broad, unscoped access to a sub-account — a security model nobody should be shipping in 2026. If you've inherited a client integration still running on a 1.0 key, treat migration as maintenance debt with a deadline, not an optional upgrade.

API 2.0 differs in three ways that matter:

• Scoped access. Tokens only reach the endpoint groups you explicitly grant, so a reporting script can't accidentally delete contacts.
• Two auth models. Private Integration tokens for your own builds; OAuth 2.0 for Marketplace developer apps installed across many accounts.
• Active development. New objects (custom objects, associations, voice AI) land in 2.0 only.

Private Integration tokens: the practical default

A Private Integration token (PIT) is a long-lived bearer token you create inside GoHighLevel itself — no developer application, no OAuth redirect flow, no app review. It's the right tool when the integration serves you or one client, rather than being distributed as a product.

Creating a PIT step by step

In the sub-account (or at agency level, where supported endpoint groups differ), go to Settings → Private Integrations → Create new integration. Name it after the system it serves — "Looker Studio reporting", not "Priya's token" — select only the scopes it needs, and copy the token once on creation. Store it in a secrets manager or your platform's environment variables immediately; GoHighLevel won't show it again, though you can rotate it from the same screen at any time.

Choosing scopes deliberately

Scopes map to endpoint groups: contacts.readonly, contacts.write, opportunities.write, calendars/events.readonly, conversations/message.write and so on. The habit worth forming is least privilege: a dashboard that only reads pipelines needs read-only scopes and nothing else. If requirements grow later, edit the integration and add the scope — that's a thirty-second job, whereas cleaning up after an over-permissioned leaked token is not.

PIT vs OAuth marketplace app vs Zapier/Make

Here's how I frame the decision when scoping client work:

Rule of thumb: if the code will only ever run for accounts you control, use a PIT. Build an OAuth Marketplace developer app only when strangers will install your integration — the refresh-token plumbing and app review are worth it then, and only then.

The endpoints you'll actually use

Contacts upsert

The contacts upsert endpoint is the workhorse of every migration and form integration I've built. Send an email or phone number and GoHighLevel matches an existing contact or creates one, updating standard and custom fields in a single call — no "check if exists, then create or update" dance, and no duplicates when your source data is messy. Fetch custom field IDs first via the custom fields endpoint, because you write to them by ID, not by name.

Opportunities

Opportunities endpoints let you create deals, move them between pipeline stages and update monetary values programmatically. This is how you sync GoHighLevel pipelines with an external proposal tool or finance system — and how you build reporting that the native dashboards can't produce, like cohort-based win rates across twenty sub-accounts.

Calendars

Calendar endpoints expose free slots and let you create, move and cancel appointments. Common use: booking widgets on platforms GoHighLevel doesn't embed into cleanly, or syncing appointments into an operations system that drives rostering.

Conversations

Conversations endpoints read message history and send SMS, email or WhatsApp messages into the unified inbox. They're the backbone of custom AI agent builds — your agent reads context from the thread, reasons externally, then replies through the same channel the client's team already monitors.

Webhooks vs polling: let GHL push, don't pull

Polling — hitting the API on a timer to ask "anything new?" — burns rate limit (API 2.0 allows a burst of 100 requests per 10 seconds and 200,000 per day per location) and still misses events between polls. Outbound webhooks invert this: GoHighLevel pushes JSON to your URL the moment something happens. You can subscribe via Marketplace app webhook events, or far more simply, drop a Webhook action inside a Workflow so any trigger — form submitted, stage changed, tag added — posts the payload to your endpoint. Inbound webhooks work the other way: a Workflow's inbound webhook trigger gives you a URL that external systems can call to start automation inside GHL. I've broken down the patterns in my guide to GoHighLevel webhooks and Zapier integrations.

My default architecture: webhooks for event-driven updates, API calls for on-demand reads and writes, polling only as a nightly reconciliation sweep to catch anything a webhook dropped.

When Workflows, Zapier or Make are enough

Custom code is a liability you maintain forever, so exhaust the native options first. Workflows with their triggers and actions handle the overwhelming majority of automation inside the platform — and the built-in Custom Webhook action can even call external APIs without you hosting anything. Zapier and Make cover most app-to-app plumbing on top of that.

Reach for the HighLevel API directly when you hit one of these walls: bulk operations across thousands of records, logic too complex for a Workflow branch, sub-second response requirements, cross-sub-account aggregation, or a user interface of your own. If none of those apply, you're probably buying maintenance overhead for no benefit. It's also worth noting API 2.0 access is included on standard plans — check current inclusions on the GoHighLevel pricing page — so the cost of an API build is your development time, not a platform surcharge.

Security practices that survive an audit

A PIT is a password with superpowers. Treat it accordingly:

• Least-privilege scopes. Grant only the endpoint groups the integration touches today.
• Never hard-code tokens. No tokens in source code, client-side JavaScript, Git history or shared documents. Use environment variables or a secrets manager, and call the API from a server, never the browser.
• Rotate on a schedule and on departure. Rotate tokens periodically and immediately when a developer or VA with access leaves. The Private Integrations screen makes rotation painless; your deployment process should make swapping the new value equally painless.
• One token per integration. Separate tokens per system mean you can revoke one integration without breaking three others, and audit logs actually tell you who did what.
• Log and alert. Watch for 401s (revoked or rotated token) and 429s (rate limiting) so failures surface before the client notices.

Practical agency use cases

Custom dashboards and reporting exports

Pull opportunities, appointments and conversation counts across every client sub-account into BigQuery or a Google Sheet, then visualise in Looker Studio. Clients get one branded report; you stop screenshotting dashboards on the last Friday of the month.

Migration scripts

Moving a client in from Keap, HubSpot or a spreadsheet graveyard? A contacts upsert script with field mapping beats CSV imports for anything beyond trivial data — you control matching, custom field population and tagging in one pass. Pair the data migration with snapshots for the configuration side: snapshots carry funnels, Workflows and custom field definitions between sub-accounts, while the API carries the records themselves.

AI agents and MCP

The fastest-growing use case in my client work. HighLevel now ships an MCP (Model Context Protocol) server, which lets AI assistants like Claude call contacts, opportunities, calendars and conversations endpoints as native tools — authenticated with a Private Integration token. That means an AI agent that looks up a caller's history, books an appointment and logs the outcome, without you writing REST plumbing by hand. Scope the token tightly; an AI agent should hold write access to exactly what it manages and nothing more.

Common mistakes to avoid

• Building on API 1.0 in 2026. It's deprecated and unscoped; any new work on 1.0 keys is technical debt on day one.
• Granting every scope "to be safe". Over-permissioned tokens turn a minor leak into a full sub-account compromise. Add scopes when needed, not in advance.
• Hard-coding tokens in code or funnels. Tokens pasted into client-side scripts or committed to Git get scraped. Server-side only, from a secrets store.
• Polling for changes webhooks would push. You'll chew through the 200,000 daily request limit and still lag behind real-time; subscribe to webhooks and reconcile occasionally instead.
• Ignoring rate limits and error handling. Bulk scripts without backoff on 429 responses fail halfway through a migration and leave data in a half-synced state.
• Writing code where a Workflow would do. Every custom integration is something you maintain forever; if a native trigger and action chain covers it, use that.

If you want a custom integration or API build scoped properly — before anyone writes a line of code that becomes your problem later — book a strategy call with the HL Growth Partner team.

Book Your Strategy Call →

Frequently asked questions

Is the GoHighLevel API free to use?

API 2.0 access is included with standard GoHighLevel plans at no extra platform charge — you pay for the plan itself and whatever you spend hosting your integration. Usage-based costs like SMS and email sends still apply when your API calls trigger them.

What is the difference between a Private Integration token and an old API key?

API 1.0 keys were unscoped and granted broad access to a whole sub-account. A Private Integration token is an API 2.0 credential created under Settings → Private Integrations with only the scopes you select, and it can be rotated or revoked at any time without touching other integrations.

What are the GoHighLevel API rate limits?

API 2.0 allows a burst of 100 requests per 10 seconds and 200,000 requests per day per location for Private Integrations. Well-built integrations handle 429 responses with exponential backoff and lean on webhooks rather than polling to stay well under those limits.

Can I use the API at agency level or only per sub-account?

Both. Private Integrations can be created at the agency (company) level or within an individual sub-account, though some endpoint groups are only available at one level or the other. Agency-level tokens suit cross-account reporting; sub-account tokens suit client-specific integrations.

Does GoHighLevel support MCP for AI agents?

Yes. HighLevel provides an MCP server that exposes contacts, opportunities, calendars, conversations and payments endpoints as tools for AI assistants, authenticated with a Private Integration token. It's the quickest route to letting an AI agent read and act on live CRM data without custom REST integration code.