GHL API v2 Docs: Tokens, the Version Header, Endpoints and Webhooks

Five things changed between the two API generations; here is the page that explains each one and the order in which to move an existing integration.

GHL API v2 docs: what changed from v1, and the order to read them in

Two generations of the API sit side by side in the documentation, and most of the confusion people report comes from reading v2 pages with v1 assumptions still in their head. The first generation authenticated with a static key copied out of a settings page and called one flat set of paths. The second authenticates through OAuth or a scoped private token, groups its endpoints by service, demands a version header on every request, and moves webhooks into the application that subscribes to them. If you already hold a v1 integration, the useful way to read the v2 docs is not front to back but as a migration list: five things that changed, the page that explains each, and the order in which to move them.

The five changes, and the page for each

Authentication first: OAuth or a private token

The docs open with OAuth because that is what a marketplace app uses: a client registered by you, installed by an account holder who consents to a list of scopes, and issued tokens that expire and are refreshed. If your integration is only ever going to run against your own agency’s accounts, the private integration token is the shorter road: generated inside the account, limited to the scopes you tick, and used as a bearer token without the consent flow. Which one you should hold, and how to store it, is the subject of getting API access and keeping the credential safe; the point for reading the docs is that every endpoint page assumes you have already made that choice, so make it before you open one.

The header that produces the confusing error

Every v2 request carries a Version header whose value is a date string the docs specify. It is not the API version in the usual sense; it pins the response shape you are coding against, so that later changes do not break you without warning. Leave it out and the error you get back reads like an authentication failure or a missing endpoint, which is why the header is worth checking before the token when a first call fails. Copy the value from the docs rather than guessing a plausible date, and send it on every call, including the ones that worked yesterday.

Location tokens, agency tokens and the scope list

A v1 key was simply the account’s key. In v2 a token belongs to either a location or an agency, and the two are not interchangeable: a location token acts inside one sub-account, and an agency token acts at the company level and can be exchanged, through a documented endpoint, for a token to a specific location the agency controls. Which endpoints accept which token is stated on each endpoint page, and so is the scope each one requires. Scopes are declared when the app or private token is created and enforced on every call, so a token that lacks a scope fails cleanly with a permissions error rather than a vague one. The reasoning for keeping that list short is in asking for exactly the OAuth scope you need; for the migration, list every v1 call you make, note the scope its v2 equivalent requires, and request exactly that set.

Reading an endpoint page as a v1 user

The endpoint pages are where field names and shapes changed, and the mistake is to assume a field you used in v1 means the same thing under the same name in v2. Read each page in this order: the token type and scope it needs, the required path and query parameters, the request example, the response example, and only then the field descriptions. Compare the response example to your existing mapping field by field, because a value that was a name in one generation is often an identifier in the other, and dates and custom fields are the usual places the shape differs. That comparison is the same exercise as field mapping between two systems, applied between two versions of one system rather than between two systems.

Create, update and upsert

Where the docs offer an upsert for a resource, read it before the separate create and update pages. An integration that creates on every event is the one that produces duplicate contacts, and an upsert keyed on the right field is the fix the v2 docs hand you directly.

Webhooks moved into the app

In v2 a webhook is something an application subscribes to, event type by event type, rather than something toggled inside an account. The docs list the event names and show a sample payload for each; read the payload before choosing the event, because the name of an event and what it actually carries can differ from what a v1 integration was used to. reading a webhook payload covers how to inspect one and what breaks when the shape changes underneath you. For anything that needs to react to a change rather than poll for it, the webhook page is usually the right answer, and it keeps you well inside the per-app limits the docs publish, which sit alongside workflow rate limits as the two ceilings an integration has to respect.

The migration order

1. Inventory every v1 call your integration makes, with the fields it reads and writes.
2. Register a marketplace app or create a private integration token, with the smallest scope set that covers the inventory. If the app will be installed by other accounts, marketplace app approval is the gate it has to pass.
3. Get one read call working, with the Version header and the right token type, before touching anything else.
4. Map fields from each v2 response example to your existing model, and resolve every name-versus-identifier difference in writing.
5. Move the writes, using an upsert wherever the docs offer one.
6. Subscribe to the webhook events that replace any polling, and verify the sender on every delivery.
7. Run both generations in parallel for a period and log every call and every delivery to an audit trail in a sheet, so the differences show up as rows rather than as support tickets.
8. Revoke the v1 key. A key that still works is a credential nobody is watching.

What to bookmark

Four pages carry most of the value after the first day: the changelog, because the version header protects you only until you decide to move forward; the scopes list, because every new feature request starts there; the webhook events list, because it costs nothing to read and tells you what the platform can notify you about; and the rate limit page, because the numbers on it are the ones your integration will be judged against on its busiest day.

Frequently Asked Questions

What is the difference between the GHL API v1 and v2 docs?

v1 describes a static key, one host with flat paths, no versioning and account-level webhooks. v2 describes OAuth or a private integration token, endpoints grouped by service, a required Version header, location and agency tokens limited by scopes, and webhooks subscribed per application.

Do I need a marketplace app to use the v2 API?

Only if other accounts will install your integration. For your own agency’s accounts, a private integration token generated inside the account, with the scopes you tick, works as a bearer token without the OAuth consent flow. The docs cover both on the authentication pages.

What is the Version header in the v2 docs?

A required header carrying a date string that pins the response shape you are coding against. Leaving it out produces an error that looks like an authentication or routing failure, so check it first when a call fails, and copy the value from the docs rather than guessing.

Can an agency token be used on a location endpoint?

Not directly. Location and agency tokens act at different levels, and each endpoint page states which it accepts. The docs describe an exchange that turns an agency token into a token for a specific location the agency controls, which is the route for agency-wide integrations.

Where do webhooks live in v2?

Inside the application. You subscribe an app to named event types, and the docs list each event with a sample payload. Read the payload before choosing the event, because what an event carries can differ from what a v1 integration expected under a similar name.

In what order should a v1 integration be migrated?

Inventory the v1 calls, create the app or private token with minimal scopes, get one read call working with the Version header, map fields from the v2 response examples, move the writes using upserts, replace polling with webhooks, run both in parallel with logging, then revoke the v1 key.

Which v2 docs pages are worth bookmarking?

The changelog, the scopes list, the webhook events list and the rate limit page. Between them they answer what changed, what a new feature will need, what the platform can notify you about, and what your integration will be held to under load.

We build your GoHighLevel account for you

CRM, pipelines, funnels, SMS and automation — configured for your business, not left for you to figure out.

• Setup (one-time)$850
• Ongoing (per month)$38.80

Get my free setup quote

No obligation quote · reply within 1 business day

This site is independently operated and is not officially affiliated with, endorsed by, or sponsored by HighLevel LLC. We do not receive referral commissions — this is our own flat-fee implementation service.