GoHighLevel API Integration Guide for Developers

GoHighLevel is easy to demo and awkward to integrate. The CRM is agency-shaped, which means almost every object you touch belongs to a sub-account, tokens are scoped in ways that surprise people on day one, and the v1 API most tutorials still reference is end-of-support.

I have built against this API for lead intake, AI calling and SMS pipelines, and two-way CRM sync. This guide is the version of the docs I wish existed: what to authenticate with, what the v2 API actually expects, how webhooks behave, and the specific failures that cost me time so they do not cost you any.

What does a GoHighLevel API integration actually connect to?

A GoHighLevel API integration connects to a single sub-account, called a location, or to an agency account that holds many locations. Almost every useful endpoint (contacts, opportunities, conversations, calendars, custom fields) is location-scoped, so the first design decision is which level your token lives at.

That matters more than it sounds. An agency-level token cannot read contacts directly. It exchanges itself for a location access token, and you cache that per location. If you skip this, you get 401s that look like scope problems and are actually hierarchy problems.

If you are still deciding whether the platform belongs in your stack at all, start with what GoHighLevel is used for before you write a line of integration code. Half the integrations I get asked to fix exist because someone automated around a feature the CRM already ships.

OAuth or API key: which GoHighLevel authentication should you use?

Use OAuth 2.0 if your integration will be installed on accounts you do not own. Use a private integration token if you are building one internal tool against your own sub-accounts. The old v1 location API keys are legacy and should not be the foundation of anything new.

Private integration tokens are effectively static OAuth access tokens issued from inside a sub-account. They are the pragmatic choice for a Zapier-style glue script, an n8n workflow, or an internal FastAPI service. They never expire or refresh on their own, which is convenient right up to the moment one leaks, so treat them like database credentials and rotate them on a schedule you set yourself.

If you go the OAuth route, store the refresh token, not just the access token, and refresh on a schedule rather than reactively on the first 401. Reactive refresh under concurrency produces a thundering herd where ten workers refresh simultaneously and nine of them end up holding an invalidated token.

"Pick your auth model based on who owns the account, not on which tutorial you found first."

What do you need to know about the v2 API before you write code?

Three things: the base URL is services.leadconnectorhq.com, every request needs a Version header such as 2021-07-28, and most write payloads need an explicit locationId. Miss any one of them and you get an error that does not name the missing piece.

The Version header is the part people forget. It is not optional and it is not a nicety. HighLevel uses it to pin endpoint behaviour, so omitting it produces failures that look like malformed requests. Set it once at the session level and never think about it again.

import os
import requests

BASE = "https://services.leadconnectorhq.com"

session = requests.Session()
session.headers.update({
    "Authorization": "Bearer " + os.environ["GHL_ACCESS_TOKEN"],
    "Version": "2021-07-28",
    "Accept": "application/json",
    "Content-Type": "application/json",
})


class RateLimited(Exception):
    pass


def upsert_contact(location_id: str, lead: dict) -> dict:
    payload = {
        "locationId": location_id,
        "email": lead["email"].strip().lower(),
        "phone": lead.get("phone"),
        "firstName": lead.get("first_name"),
        "source": "website-form",
        "tags": ["inbound", "api-sync"],
    }

    res = session.post(BASE + "/contacts/upsert", json=payload, timeout=20)

    if res.status_code == 429:
        # Burst budget gone. Back off with jitter, do not retry immediately.
        raise RateLimited(res.headers.get("X-RateLimit-Remaining"))

    res.raise_for_status()
    return res.json()["contact"]

That upsert call is the single most important endpoint in a contact sync. It matches on email or phone within the location and returns the existing record instead of creating a duplicate, which is the difference between a sync you can re-run safely and one you can run exactly once.

How do you sync contacts and opportunities without creating duplicates?

Make the write idempotent at the CRM level with upsert, and idempotent at your level with a stored external id mapping. GoHighLevel does not accept an arbitrary idempotency key on writes, so you build that guarantee yourself.

Pipelines are the sharp edge. Pipeline and stage ids differ per location, so a multi-tenant integration has to resolve them at install time and cache them. I lost an afternoon early on to a hardcoded stage id that worked in the demo sub-account and silently 422'd everywhere else. If your pipeline structure is still in flux, fix that first with a proper GoHighLevel CRM setup before wiring code to it.

How do GoHighLevel webhooks work, and how do you verify them?

Webhooks push events such as ContactCreate, ContactUpdate, OpportunityStatusUpdate and InboundMessage to your endpoint as signed JSON. HighLevel's webhook documentation describes an Ed25519 signature in the X-GHL-Signature header, with a legacy RSA-SHA256 X-WH-Signature header being retired. The guidance is to verify with the Ed25519 key when X-GHL-Signature is present and fall back to the legacy RSA key only during the transition. Verify against the published public key before you trust a single field.

Delivery is at-least-once. The docs describe retries with exponential backoff and jitter on any non-2xx response, timeout or connection failure, which means your handler will eventually see the same event twice. Payloads carry a webhookId, so store it and drop repeats.

One non-obvious behaviour: your own API writes fire webhooks too. If your webhook handler writes back to GoHighLevel, you have built a loop. Tag API-originated writes and short-circuit on them, or you will find out at 3am when a contact update ping-pongs a few thousand times.

What are the GoHighLevel API rate limits?

HighLevel documents two limits on the v2 API: a burst limit of 100 requests per 10 seconds and a daily limit of 200,000 requests, both counted per marketplace app per resource (location or company). Every response carries headers telling you where you stand.

The daily limit is the one that bites during migrations. A 40,000-contact backfill that reads, upserts and then writes custom fields is three calls per contact, which is over half your daily budget before any live traffic. Batch the reads, hash-compare to skip no-op writes, and run backfills overnight in the account's timezone.

Because limits are per app per location, a multi-tenant integration does not share one global budget. That is genuinely helpful, but it means your throttling has to be keyed per location rather than global, or a single busy account will starve the rest.

What are the most common GoHighLevel API integration gotchas?

Most GoHighLevel API integration failures are not exotic. They are the same handful of assumptions carried over from friendlier APIs. Here is the list I now check before shipping anything.

On the GoHighLevel AI calling and SMS platform I built, the two that mattered most were loop protection and per-location throttling. Voice and SMS events arrive in bursts, and a conversation that triggers a contact update that triggers another webhook will find every weakness in your handler within minutes.

Should you build the integration in code or in n8n?

Build it in a workflow tool if the logic is linear and low volume. Write real code once you need per-location token management, backfills, retry semantics or anything stateful. The crossover comes faster than people expect.

In practice I run both. A thin n8n layer handles notification fan-out and simple triggers, while a Python service owns tokens, syncs and anything that must be replayable. That split keeps the workflow canvas readable and puts the hard guarantees where they can be tested.

If you want the integration designed and handed over rather than debugged in production, that is what my GoHighLevel integration work and broader AI automation services cover, mostly for agencies running many sub-accounts at once.