The GoHighLevel API is a REST API at services.leadconnectorhq.com. You call it with a Private Integration Token for your own account or OAuth 2.0 for an app other accounts install, and you send a Version header on each request. There is no API key in the current setup. GoHighLevel's own docs say the old API-key route belongs to API v1, which has reached end-of-life.
This guide covers which authentication to pick, a first request, rate limits, webhooks and the mistakes we avoid when a build depends on the API. It is the technical side of the work we do on our GoHighLevel development service, and we wrote it because many tutorials still start from a location API key that no longer applies.
GoHighLevel API authentication: Private Integration Token or OAuth
GoHighLevel's docs say it supports two kinds of authorization. They fit different jobs.
| Situation | Use | What you manage |
|---|---|---|
| Syncing your own account or a client account to another system | Private Integration Token | One token, chosen scopes, rotation |
| Building an app other GoHighLevel users install | OAuth 2.0 | Install flow, access and refresh tokens per install |
| A tutorial that says "paste your API key" | Neither | It targets API v1, so find a newer source |
We default to the Private Integration Token. You create it from the Private Integrations area (the docs say to enable the feature under Labs if you cannot see it), name it, tick only the scopes the integration needs, and copy the token. The page warns that you cannot view it again later. Scopes can be edited afterwards without generating a new token.
OAuth is the right call only when you are shipping an app. The docs describe an access token that lasts about 24 hours and a refresh token valid for up to a year or until it is used. Each refresh invalidates the old refresh token and returns a new one, so you must save both every time. If two workers refresh at once, one of them loses its token. We put a lock around the refresh for that reason.
Your first GoHighLevel API request
The example in GoHighLevel's Private Integrations page fetches a location. It is a good first test because it proves the token, the scope and the header in one call:
curl https://services.leadconnectorhq.com/locations/YOUR_LOCATION_ID \
-H "Accept: application/json" \
-H "Authorization: Bearer YOUR_PRIVATE_INTEGRATION_TOKEN" \
-H "Version: 2021-07-28"A 401 usually means a bad token. A 403 usually means the token lacks the scope for that endpoint, so edit the integration and add it. A 400 on a newer endpoint can mean the Version header is too old, which brings us to the next problem.
The Version header trips people up
Version is set per request. The docs' versioning page lists several values, including 2021-07-28 and a newer v3, and the current examples are not consistent about which to send. At least one contacts endpoint documents that it needs a Version of v3 or later and returns 400 for older values.
We do not hard-code one value across a whole integration. Each call reads its version from a small table next to the endpoint it belongs to, and we confirm against the endpoint page when we add the call. When a request that worked last month starts returning 400, the header is the first thing we check.
GoHighLevel API rate limits and how we handle them
The rate limits page documents a burst limit and a daily limit (the numbers are in the as-of section below). Two details matter more than the numbers.
- The daily budget is counted per location, and every Private Integration Token on that location shares it. Two integrations on one sub-account draw from one pool.
- A 429 does not come with a Retry-After header. The response headers report what is left and how long until reset, so the client has to read them.
Our rule is to read X-RateLimit-Remaining on every response, pause when it hits zero, and wait for the interval the daily-reset header reports if the daily budget is gone. A bulk import that loops over contacts with no pause is the usual way an integration trips the burst limit on day one.
GoHighLevel webhooks: events going the other way
Calling the API pulls data out. Webhooks push events to you when something changes: a contact is created, an opportunity moves, an appointment is booked. The docs home page advertises notifications for more than 50 events. For app-level webhooks you set the URL and pick events in the app's advanced settings. Separately, a GoHighLevel workflow can post to an outside URL, which is how we trigger most small syncs without writing an app.
Three things we handle on every webhook receiver:
- Answer with a 2xx fast and do the real work after. The docs say any non-2xx or missing response counts as a failure and triggers retries with exponential backoff, so a slow handler causes duplicate deliveries.
- Deduplicate. Retries mean you can see the same event twice, so store an event or record ID and skip repeats.
- Verify the signature. The docs describe an
X-GHL-Signatureheader (Ed25519) as current and an olderX-WH-Signatureheader (RSA-SHA256) marked legacy, with a stated deprecation date of September 1, 2026. We verify the current header and check it against the raw request body, because re-serializing parsed JSON can change whitespace or key order and break a valid signature.
We built this pattern into our Stripe deposit to project kickoff automation, where a signed webhook verifies the payment, drops duplicates and matches it to exactly one proposal before the deal moves to Closed Won in GoHighLevel. The same shape works for any inbound event.
GoHighLevel API details to re-check (as of November 21, 2026)
This is the section that goes stale first. Everything below comes from GoHighLevel's developer documentation as we read it on this date, and the docs are not always consistent with themselves, so confirm on the linked pages before you build.
- Base URL in the doc examples:
https://services.leadconnectorhq.com. The docs do not state it as a standalone fact, only through example requests. - Authorization: Private Integration Token and OAuth 2.0 are the two documented methods. API keys are described as API v1, end-of-life, with no end date given on the pages we read. See the Private Integrations page.
- Token handling: the docs recommend rotating Private Integration Tokens every 90 days, with a 7-day overlap where old and new both work. OAuth access tokens last about 24 hours.
- Limits: 100 requests per 10 seconds and 200,000 per day, per app per location or agency, per the rate limits page.
- Versions: the versioning page lists v3 with a June 11, 2026 release date, next to 2023-02-21 and 2021-07-28.
- Webhooks: signature headers and the September 1, 2026 legacy date are on the webhook guide. The page still words that date in the future tense, so we cannot say from it whether the legacy header is already gone. Test against the header you actually receive.
- Plan prices and which plans include API access are on GoHighLevel's pricing page. We are not restating them here.
Mistakes we avoid
- Following an API-key tutorial. If the first step is "copy your location API key," the guide targets the old API and the rest will not match the current docs.
- Granting every scope. Tick what the integration needs. A token that can touch billing and users is a bad thing to paste into a third-party tool.
- Forgetting rotation. A token that is never rotated eventually belongs to someone who left the team. We put the 90-day rotation on a calendar.
- Treating a phone number pulled through the API as marketing consent. Reading a contact through the API tells you nothing about whether you may text them, so keep consent as its own field and check it before any send.
- Writing to GoHighLevel from two systems with no source-of-truth rule. Decide which side owns each field, or the two will overwrite each other.
What we would do
Start without code. If the job is "when X happens in GoHighLevel, tell another system," a workflow with an outbound webhook step is enough, and you can add an n8n or custom receiver later. Reach for the API when you need to read or write at volume, or when data starts somewhere else and must land in a pipeline.
For that second case, create one Private Integration Token with the narrowest scopes, build the receiver to return 2xx fast, dedupe and verify signatures, and test with a throwaway contact before any real lead goes through. If you want it scoped for your account, our GoHighLevel service page shows how we build and hand over this kind of integration.
Frequently asked questions
- Does GoHighLevel have an API?
- Yes. GoHighLevel publishes a REST API (version 2.0) with documentation at marketplace.gohighlevel.com/docs. You authenticate with either a Private Integration Token for your own account or OAuth 2.0 for an app other accounts install. Webhooks cover the other direction, pushing events out of GoHighLevel to your own endpoint.
- Where do I find the GHL API key?
- For the current API you do not use an API key. You create a Private Integration Token under the Private Integrations settings and copy it when it is shown, because it cannot be displayed again. GoHighLevel documents API keys as belonging to API v1, which it says has reached end-of-life, so a tutorial that starts with a location API key is out of date.
- What are the GoHighLevel API rate limits?
- The documentation lists 100 requests per 10 seconds and 200,000 requests per day, counted per app per location or agency. Every response carries headers showing what is left, and a 429 response does not include a Retry-After header, so your code has to read the headers and wait. Check the rate limits page for the current numbers before you design around them.
- Should I use a Private Integration Token or OAuth?
- Use a Private Integration Token when the integration only touches your own account or a client account you manage. Use OAuth 2.0 when you are building an app that other GoHighLevel users install. OAuth adds refresh-token handling you have to store and rotate correctly, which is wasted effort for a single-account integration.
- Do I need a developer to use the GoHighLevel API?
- Not for simple jobs. GoHighLevel workflows can send a webhook or call an outside URL without code, and that covers many syncs. You need a developer when you must read and write contacts at volume, handle failures and duplicates, or verify incoming webhook signatures.