GoHighLevel API · Plain-English Reference

Every GHL API scope.
In simple words.

What each scope does. Who it's for. Read-only or write. How to use the API in Claude, Antigravity, or your own app. And the limits.

How to read a scope name

A name has two parts. Like contacts.write — contacts = what you touch, write = what you can do. readonly = look only.

Try GoHighLevel Free for 30 Days Need Help? GHL Megaminds

GHL Megaminds helps you integrate GoHighLevel and build custom wrappers around it.

How to use the API

Four guides. Start at the top. Each one is short.

1. Get a token (start here)

First you need a key. We call it a token. Then the API will listen to you.

Way A: Private token. (Easy. For your own account.)

  1. Log in to GoHighLevel.
  2. Open Settings, then Private Integrations.
  3. Click Create. Give it a name.
  4. Pick the scopes you need. (See the list above.)
  5. Copy the token. It shows only once.

Use it in a request header:

curl https://services.leadconnectorhq.com/contacts/v1/contacts \
  -H "Authorization: Bearer YOUR_TOKEN"

Way B: OAuth 2.0. (For apps other people install.)

  1. Make an app on the GHL developer site.
  2. Pick scopes. Set a callback URL.
  3. Send the user to the allow page.
  4. The user says yes. GHL sends back a short code.
  5. Swap the code for a token.
  6. Tokens live 24 hours. Use the refresh token to get a new one.
curl -X POST https://services.leadconnectorhq.com/oauth/token \
  -d grant_type=authorization_code \
  -d code=THE_CODE_YOU_GOT \
  -d client_id=YOUR_CLIENT_ID \
  -d client_secret=YOUR_CLIENT_SECRET
Which one do I pick?
Just your own account? Way A. Fast and simple.
An app for many people? Or webhooks? Way B. (Private tokens can't get webhooks.)

2. Use it in Claude

GHL has its own MCP server. That is the clean way to hook Claude up.

MCP is a standard way for AI to use tools. The AI asks, the server does the work. Claude only does what the scopes you approved allow.

On Claude.ai:

  1. Open Settings, then Connectors.
  2. Click Add custom connector.
  3. Paste this URL: https://services.leadconnectorhq.com/mcp/anthropic/v2
  4. Click Connect. Sign in. Pick your sub-accounts. Say yes.
  5. Start a new chat. Ask: "Show me contacts tagged hot."

In Claude Code (terminal):

claude mcp add --transport http leadconnector \
  https://services.leadconnectorhq.com/mcp/anthropic/v2

Then type /mcp to see it. For ChatGPT and other OpenAI tools, GHL has a matching endpoint: https://services.leadconnectorhq.com/mcp/openai/v2/

Stay safe:
• Do not paste your token into a public chat site.
• Pick only the scopes you need. Less is safer.
• Prefer the official GHL server over random community servers.

3. Use it in Antigravity

Antigravity is Google's AI coding app. Two ways to work.

Way A: Add GHL's MCP server.

  1. Open Settings, then Customizations.
  2. Find MCP servers.
  3. Add GHL's MCP URL: https://services.leadconnectorhq.com/mcp/anthropic/v2
  4. Sign in. Pick your sub-accounts.

Way B: Let the agent write the code.

  1. Save your token in a file named .env in your project:
# .env
GHL_TOKEN=your_private_token
GHL_LOCATION_ID=your_location_id
  1. Ask the agent in plain words:
Use the GoHighLevel API.
Base URL: https://services.leadconnectorhq.com
My token is in .env (GHL_TOKEN, GHL_LOCATION_ID).
List my last 10 contacts. Show me the code before you run it.
  1. The agent writes the code. Check it. Then run it.
Tip: ask for read-only scopes first while you test. Add write scopes only when you are sure.

4. Build your own app or script

You need one thing: a token. Then you call the API.

Step 1 — Make a token (Guide 1, Way A for your own account).

Step 2 — Call the API. Put the token in the header.

const token = process.env.GHL_TOKEN;

const res = await fetch("https://services.leadconnectorhq.com/contacts/v1/contacts", {
  headers: { Authorization: "Bearer " + token }
});
const data = await res.json();
console.log(data.contacts);

Building an app for others (OAuth): create the app, get the code (Guide 1, Way B), swap the code for a token, store the refresh token, and call the API like above.

Common errors:

  • 401 = bad or dead token. Make a new one.
  • 403 = missing scope. Add it, then approve again.
  • 429 = too fast. Slow down. (See Limits.)

Webhooks (GHL sends you events, like "a contact was made"): they need an OAuth app. Private tokens do not get webhooks.

Limits and rules

How much you can send. And what you can't do.

What Limit
Speed 100 requests per 10 seconds
Per day 200,000 requests per day
How it counts Per app, per sub-account

Example: one app on two sub-accounts = 400,000 requests a day. Each sub-account gets its own full allowance.

Best habit: pick the fewest scopes you need. Every scope is something a customer must say yes to. And each extra scope is more risk if a token leaks.