YYousaf
Guide

GoHighLevel API v2: The Developer's Guide

A developer's guide to the GoHighLevel API v2: which token to use, how OAuth installs really work, scopes, the Version header, rate limits, pagination, signed webhooks, and a worked example that creates a contact and books an appointment.

YBy Yousaf14 min read

The GoHighLevel API v2 is the way into everything the platform stores — contacts, conversations, calendars, opportunities, invoices, custom objects, workflows — and it's what every marketplace app, integration and AI agent I build is written against. The official reference tells you what each endpoint accepts. This guide covers the part it doesn't: which kind of token you actually need, how the OAuth install flow behaves in production, what the Version header and rate limits mean for your code, how webhooks are signed, and the mistakes that cost developers a day the first time.

What the GoHighLevel API v2 is (and what happened to v1)

HighLevel exposes one REST API at https://services.leadconnectorhq.com — the LeadConnector domain is the same product, which confuses people the first time they see it in a URL. The API covers the platform at the level a sub-account sees it: contacts and their custom fields, conversations and messages, calendars and appointments, pipelines and opportunities, invoices and payments, forms, funnels, users, workflows, custom objects, media, and the agency-level resources (locations, snapshots, SaaS rebilling) that only make sense with an agency token.

The API you'll see called "v1" was the original one at rest.gohighlevel.com, authenticated with the per-sub-account API key under the business profile settings. It's legacy: it covers a fraction of the platform, HighLevel has been steering developers off it for years, and nothing new is added to it. If a tutorial tells you to paste an API key from Settings → Business Profile, it's describing v1. Everything in this GoHighLevel API v2 guide uses the v2 base URL and v2 tokens.

Two headers are mandatory on every v2 call except the token endpoint: Authorization: Bearer <token> and Version: 2021-07-28. The version string is a date and it is the current one — HighLevel versions the API by date and hasn't needed a breaking bump since. Forget the header and you'll get an error that reads like an authentication problem but isn't.

Three ways to authenticate — and which one you need

Every "how do I get a GoHighLevel API key" question is really a question about which of three token types fits the job. They have different lifetimes, different scopes and different ceilings, so choose first and code second.

A private integration token is the simplest. In a sub-account go to Settings → Private Integrations (agencies have the same screen under agency settings), create an integration, tick the scopes it needs, and copy the token — it starts with pit-. It's long-lived, it's scoped to that one sub-account (or to the agency), and you use it as a plain Bearer token. This is the right choice for internal tools, a sync between your own agency and your own systems, an n8n or Make scenario, or a website form that creates contacts — it's what the contact form on this site uses.

An OAuth app is what you build when other agencies will install your integration, or when you want per-sub-account installs with explicit consent and the marketplace's distribution. It's a marketplace app with a client id and secret; the agency approves it on HighLevel's consent screen and your server receives tokens for the location or company they chose. More moving parts, but it's the only route to the marketplace, to custom conversation providers, payment providers and workflow actions, and to installing on accounts you don't control. That's the model behind every marketplace app I build.

A location token minted from an agency token is the third, and it's the one people miss. When an app is installed at agency (Company) level, the token you get can only call agency-level endpoints. To act on a particular sub-account you call POST /oauth/locationToken with the companyId and locationId and receive a short-lived token for that location. No refresh token comes with it — when it expires, you mint another.

The simplest possible v2 call, with a private integration token, looks like this:

bash
Search contacts in a sub-account with a private integration token.
curl -X POST "https://services.leadconnectorhq.com/contacts/search" \
  -H "Authorization: Bearer pit-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" \
  -H "Version: 2021-07-28" \
  -H "Content-Type: application/json" \
  -d '{ "locationId": "YOUR_LOCATION_ID", "pageLimit": 20 }'

The OAuth install flow, step by step

An OAuth install has two legs. First you send the agency to HighLevel's consent screen at https://marketplace.gohighlevel.com/oauth/chooselocation with response_type=code, your client_id, your registered redirect_uri and the space-separated scope list. They pick a sub-account (or the agency), approve, and HighLevel redirects back to your callback with a code in the query string. Always send a random state value and check it on the way back — it's the only thing stopping a forged callback.

Second, your server exchanges the code for tokens with POST https://services.leadconnectorhq.com/oauth/token. This is the one endpoint that is form-encoded rather than JSON and takes no Version header: send client_id, client_secret, grant_type=authorization_code, the code, user_type (Location or Company, matching how the app is configured) and redirect_uri. The response carries access_token, refresh_token, expires_in (about 24 hours), the granted scope, userType, and the locationId or companyId the install belongs to — store the whole thing keyed by that id, because that id is how every later API call and webhook identifies the tenant.

Refreshing is the same endpoint with grant_type=refresh_token. The detail that breaks production apps: the response includes a new refresh token and the old one stops working. If two requests notice an expired access token at the same moment and both refresh, the second refresh fails, and if your code saves whichever response arrived last, the install is stranded until the agency reinstalls. Serialise refreshes per install — one in-flight refresh, everyone else waits for it. The function below is the shape of that exchange; the single-flight refresh, location-token minting and storage are all in my open-source gohighlevel-oauth-starter, which is what I start every app from.

ts
Code → tokens. Form-encoded, no Version header, and keep the locationId/companyId as the install key.
async function exchangeCode(code: string) {
  const res = await fetch("https://services.leadconnectorhq.com/oauth/token", {
    method: "POST",
    headers: { "Content-Type": "application/x-www-form-urlencoded", Accept: "application/json" },
    body: new URLSearchParams({
      client_id: process.env.GHL_CLIENT_ID!,
      client_secret: process.env.GHL_CLIENT_SECRET!,
      grant_type: "authorization_code",
      code,
      user_type: "Location", // or "Company" for agency-level apps
      redirect_uri: process.env.GHL_REDIRECT_URI!,
    }),
  });
  if (!res.ok) throw new Error("token exchange failed: " + res.status);
  const t = await res.json(); // access_token, refresh_token, expires_in, scope, userType, locationId | companyId
  const key = t.userType === "Company" ? t.companyId : t.locationId;
  await db.installs.upsert(key, { ...t, expiresAt: Date.now() + t.expires_in * 1000 });
  return key;
}

Scopes: what they are and why you get 403s

Every token carries a list of scopes, and every endpoint requires specific ones. Scopes are named by resource and access level — contacts.readonly, contacts.write, conversations/message.write, calendars/events.write, opportunities.readonly, locations/customFields.readonly, workflows.readonly, and so on — and sub-resources use the slash form. A private integration gets the scopes you tick when you create it; an OAuth app requests the scopes enabled on the app, and the agency grants them on the consent screen.

Two consequences follow. First, request only what the features use: marketplace reviewers check that every scope is justified, and agencies are rightly wary of an app that wants users.write to show a dashboard. Second, when a call returns 403, the cause is almost always a scope the token doesn't have or a location the token wasn't issued for — not a bug in your request. Read the error body; HighLevel's messages name the missing scope or say the token has no access to that location.

Adding a scope to an existing OAuth app doesn't update tokens that were issued before the change. Agencies have to re-authorise (reinstall) to grant the new scope, which is worth knowing before you promise a feature that needs one.

Making requests: headers, locationId, pagination and search

With a token in hand, requests are plain JSON over HTTPS. Three habits keep them boring. Send both headers on every call. Pass the locationId wherever the endpoint wants it — as a query parameter on most GETs, in the body on most POSTs — because the API is multi-tenant and a token for an agency can see many locations. And wrap fetch once so you never hand-write headers again.

Listing endpoints paginate, but not all the same way. Newer endpoints use page and pageLimit (maximum 100) or cursor fields such as startAfter/startAfterId returned in a meta object; older ones use limit and skip. For contacts specifically, the legacy GET /contacts/ list is deprecated in favour of POST /contacts/search, which takes locationId, pageLimit, optional filters (field, operator, value) and sorting, and returns contacts plus a total. Custom fields come back as an array of { id, value } pairs, so cache GET /locations/{locationId}/customFields to map ids to names.

This is the wrapper I use. It's deliberately small: headers, JSON, a typed error, and a retry on the two statuses that are safe to retry.

ts
A minimal v2 client: Version header, JSON, typed errors, backoff on 429/5xx.
const BASE = "https://services.leadconnectorhq.com";

export async function ghl<T>(opts: {
  token: string; endpoint: string; method?: string; query?: Record<string, string>; body?: unknown; retries?: number;
}): Promise<T> {
  const url = new URL(BASE + opts.endpoint);
  for (const [k, v] of Object.entries(opts.query ?? {})) url.searchParams.set(k, v);
  const retries = opts.retries ?? 3;

  for (let attempt = 0; ; attempt++) {
    const res = await fetch(url, {
      method: opts.method ?? "GET",
      headers: {
        Authorization: "Bearer " + opts.token,
        Version: "2021-07-28",
        Accept: "application/json",
        ...(opts.body ? { "Content-Type": "application/json" } : {}),
      },
      body: opts.body ? JSON.stringify(opts.body) : undefined,
    });
    if (res.ok) return (res.status === 204 ? undefined : await res.json()) as T;

    const retryable = res.status === 429 || res.status >= 500;
    if (retryable && attempt < retries) {
      const retryAfter = Number(res.headers.get("retry-after")) || 0;
      await new Promise((r) => setTimeout(r, retryAfter ? retryAfter * 1000 : 1000 * 2 ** attempt));
      continue;
    }
    throw new Error("GHL " + res.status + " on " + opts.endpoint + ": " + (await res.text()));
  }
}

Rate limits, and how to never see a 429 in production

The GoHighLevel API rate limits are per app per resource, where a resource is a sub-account (or an agency for agency-level calls): a burst limit of 100 requests per 10 seconds and a daily limit of 200,000 requests. For a private integration, "app" is that integration. The response headers tell you what's left in both windows, and exceeding either returns 429.

In practice the burst limit only bites during backfills and fan-out — importing 5,000 contacts, syncing every opportunity after a webhook storm, or an AI agent making six calls per turn across many simultaneous calls. The fix is structural, not clever: put outbound API work behind a queue with a per-location concurrency of a few workers, back off on 429 (the wrapper above does), and batch where the API offers it. Treat the daily cap as a design constraint for polling: if you're polling every location every minute you'll hit it; use webhooks for change detection and poll only to reconcile.

One more number worth planning around: tokens. Access tokens last about a day, so a service that calls the API every few minutes will refresh roughly daily per install. That's fine — as long as the refresh is single-flight.

Webhooks: app webhooks, workflow webhooks and signatures

There are two things called "webhook" in GoHighLevel and they're unrelated. App webhooks are configured on a marketplace app: you subscribe to event types (contact created or updated, opportunity stage changed, inbound message, appointment booked, app installed or uninstalled, and many more) and HighLevel posts them to your app's webhook URL for every location that has the app installed. Workflow webhooks are a step an agency drags into a workflow to POST the contact's data to a URL of their choosing — useful for one agency's automation, useless as a platform integration because every agency would have to build the workflow.

App webhooks are signed. HighLevel signs the request body with its private key and sends the base64 signature in the x-ghl-signature header; you verify it with HighLevel's published Ed25519 public key over the raw bytes you received. Re-serialising parsed JSON changes the bytes and makes valid signatures fail, which is the most common reason verification "doesn't work". The older RSA x-wh-signature header was retired in September 2026, so code that only checks that header — or skips verification when the header is missing — now accepts unauthenticated requests. Verify every request, and reject unsigned ones.

ts
Ed25519 verification of x-ghl-signature over the raw body (mount the route with express.raw()).
import crypto from "node:crypto";

const GHL_PUBLIC_KEY = process.env.GHL_WEBHOOK_PUBLIC_KEY!; // PEM from the Marketplace webhook docs

export function verifyGhlWebhook(rawBody: Buffer, signatureHeader?: string): boolean {
  if (!signatureHeader) return false; // unsigned = unauthenticated
  try {
    const key = crypto.createPublicKey({ key: GHL_PUBLIC_KEY, format: "pem" });
    return crypto.verify(null, rawBody, key, Buffer.from(signatureHeader, "base64"));
  } catch {
    return false;
  }
}

Respond with a 2xx quickly; anything else is retried. If a handler does real work, acknowledge first and process from a queue. And remember that INSTALL and UNINSTALL events only ever arrive at the app's default webhook URL — for an agency-level app, INSTALL fires per sub-account and is the right moment to mint that location's token.

Worked example: create a contact, find a slot, book the appointment

This is the sequence behind an AI voice agent that books calls, a lead form that schedules a consultation, or an integration that mirrors bookings from another system. Three calls: upsert the contact (so a repeat caller doesn't become a duplicate), read free slots for a calendar in the contact's timezone, and create the appointment against the first slot that works.

Notes on the details. POST /contacts/upsert matches on email or phone within the location and returns the contact either way. Free slots come from GET /calendars/{calendarId}/free-slots with startDate and endDate as millisecond timestamps and a timezone; the response is keyed by date. Appointments are created with POST /calendars/events/appointments using the calendarId, locationId, contactId and an ISO startTime with an offset — if the calendar assigns users, pass assignedUserId or let round-robin handle it. Every one of these needs the corresponding scope (contacts.write, calendars.readonly, calendars/events.write).

ts
Upsert → free slots → book, using the ghl() wrapper from above.
async function bookFirstSlot(token: string, locationId: string, calendarId: string, lead: { name: string; email: string; phone?: string }) {
  // 1) Upsert the contact (dedupes on email/phone inside the location)
  const { contact } = await ghl<{ contact: { id: string } }>({
    token, method: "POST", endpoint: "/contacts/upsert",
    body: { locationId, name: lead.name, email: lead.email, phone: lead.phone, source: "API booking" },
  });

  // 2) Free slots for the next 7 days, in the lead's timezone
  const start = Date.now();
  const end = start + 7 * 24 * 60 * 60 * 1000;
  const slots = await ghl<Record<string, { slots: string[] }>>({
    token, endpoint: "/calendars/" + calendarId + "/free-slots",
    query: { startDate: String(start), endDate: String(end), timezone: "America/New_York" },
  });
  const firstDay = Object.keys(slots).find((d) => slots[d]?.slots?.length);
  if (!firstDay) throw new Error("no availability in the next 7 days");
  const startTime = slots[firstDay].slots[0]; // ISO string with offset

  // 3) Book it
  return ghl({
    token, method: "POST", endpoint: "/calendars/events/appointments",
    body: { calendarId, locationId, contactId: contact.id, startTime, title: "Consultation with " + lead.name, appointmentStatus: "confirmed" },
  });
}

Common errors and what they actually mean

Most GoHighLevel API v2 problems fall into a handful of buckets. Check these before you open a support ticket:

  • 401 Unauthorized — the access token is expired, revoked, or you're sending a v1 API key to a v2 endpoint. Refresh (OAuth) or regenerate (private integration) and make sure the header is Authorization: Bearer ….
  • 403 Forbidden — the token lacks the scope the endpoint needs, or it was issued for a different location than the locationId you passed. Agency tokens can't call sub-account endpoints directly: mint a location token.
  • 400 mentioning the Version header — you forgot Version: 2021-07-28. The token endpoint is the only call that doesn't take it.
  • 422 Unprocessable Entity — validation. The body lists the fields; the usual culprits are a missing locationId, a custom field value in the wrong shape, or a phone number that isn't E.164.
  • 429 Too Many Requests — you've hit the burst or daily limit for that app and location. Back off and queue; don't retry in a tight loop.
  • Refresh token invalid — a previous refresh already rotated it and your code saved the old one, or two refreshes raced. Fix the single-flight bug first, then ask the agency to reinstall to get a fresh pair.
  • Webhook signature fails — you verified a re-serialised body, used the retired RSA key, or the key in your env is stale. Verify the raw bytes with the current Ed25519 key.

Where to go from here

The official reference at marketplace.gohighlevel.com/docs is the source of truth for request and response shapes, and HighLevel publishes an official SDK if you'd rather not own the HTTP layer. For the parts this guide covers in code — the install flow, rotation-safe refresh, location tokens, the client and webhook verification — my gohighlevel-oauth-starter is MIT-licensed and small enough to read in one sitting.

And if the job is a production integration rather than a weekend project — a two-way sync, a marketplace app, a provider, an agent that has to book reliably — that's the work I do. See GoHighLevel API integration and marketplace app development, or send me the brief and I'll tell you honestly whether it's a private integration, an OAuth app, or something n8n can already do.

Frequently asked questions

How do I get a GoHighLevel API key?

For your own sub-account or agency, create a private integration under Settings → Private Integrations, choose the scopes, and copy the token (it starts with pit-); use it as a Bearer token with the Version: 2021-07-28 header. The older API key under the business profile is for the legacy v1 API and shouldn't be used for new work. To access other agencies' accounts you need an OAuth marketplace app instead.

What's the difference between the GoHighLevel API v1 and v2?

v1 (rest.gohighlevel.com, per-sub-account API key) is the original, limited, legacy API. v2 (services.leadconnectorhq.com) covers the whole platform, authenticates with private integration tokens or OAuth, requires the Version header, and is where all new endpoints land. Build on v2.

What are the GoHighLevel API rate limits?

100 requests per 10 seconds (burst) and 200,000 requests per day, per app per resource — a resource being a sub-account or, for agency calls, the agency. The response headers report what's remaining, and exceeding a limit returns 429. Queue outbound work and back off on 429 to stay under them.

Do I need a marketplace app to use the API?

No. A private integration token gives you full v2 access to your own sub-account or agency without a marketplace app. You need an OAuth marketplace app when other agencies will install your integration, when you want per-location consent, or when you're building providers, workflow actions or anything distributed through the marketplace.

Why does my refresh token stop working?

Refresh tokens rotate: each refresh returns a new one and invalidates the old one. If your code refreshes twice concurrently, or saves an older response after a newer one, you end up holding a dead token. Serialise refreshes per install and always store the refresh token from the latest successful response.

Can I use the GoHighLevel API from n8n, Make or Zapier?

Yes — all three can call v2 with a private integration token using their HTTP modules (n8n and Make also have GoHighLevel nodes/apps). They're a good fit for single-agency automations; when the logic is complex, the volume is high or the integration must be installable by other agencies, a small custom service or a marketplace app is the better tool.

Is there an official GoHighLevel API SDK?

HighLevel publishes an official TypeScript/JavaScript SDK (and a PHP client) on GitHub with built-in token refresh and webhook signature verification. It's a reasonable choice if you want generated endpoint methods; if you prefer a thin layer you fully own, the client in this guide and the open-source starter are enough.

Want this built for you?

Hire an engineer who specializes in GoHighLevel — apps, automation and white-label.