Whether you're building a custom CRM integration, syncing leads between platforms, connecting GoHighLevel with your own application, or automating workflows using tools like n8n or Make, GoHighLevel's API gives developers access to nearly every major feature inside the platform.
From creating contacts and updating opportunities to triggering automations and listening for real-time events, the API is powerful enough to build complete integrations around your agency workflow.
In this guide, we'll explain how the GoHighLevel API works, how OAuth authentication is implemented, which endpoints you'll use most often, how webhooks fit into the picture, and a few best practices we've learned while working with the platform.
Start GoHighLevel 14-Day Free Trial
Test the complete GoHighLevel CRM API, configure OAuth integrations, and trigger automations. Cancel anytime.
In This Guide
🚀 How the GoHighLevel API Works
GoHighLevel provides a REST-based API (currently API v2) that allows developers to interact with resources inside an agency or location account.
Instead of manually creating contacts, updating opportunities, or syncing appointment data through the dashboard, you can perform those actions programmatically from your own application.
Common API Use Cases:
If you're already comfortable working with REST APIs, you'll find GoHighLevel fairly straightforward to integrate.
🔐 Authentication with OAuth 2.0
GoHighLevel API v2 uses OAuth 2.0 Authorization Code Flow, which is the recommended authentication method for public applications and third-party integrations.
Unlike older API systems that relied on permanent API keys, OAuth issues temporary access tokens that can be refreshed automatically when they expire. This approach provides better security while allowing users to control exactly which applications can access their account.
Interactive OAuth 2.0 Authentication Flow
Click each step to visualize the authentication sequence details.
Step 1: User Redirect & Consent
Your application redirects the browser to GoHighLevel's authorization portal, attaching parameters for `client_id`, `scope` permissions, and your `redirect_uri`. The user logs in and selects which Location account they consent to authorize.
Typical OAuth Token Response
Once authentication succeeds, you'll receive a JSON response payload:
{
"access_token": "ghl_oauth_token_abc123xyz...",
"refresh_token": "ghl_refresh_token_789qwe...",
"expires_in": 86400,
"token_type": "Bearer",
"scope": "contacts.readonly contacts.write opportunities.write",
"locationId": "loc_abc123..."
}| Field | Purpose |
|---|---|
| access_token | Used to authenticate every API request header |
| refresh_token | Generates a new access token automatically after expiration |
| expires_in | Token lifetime in seconds (usually 86400 / 24 hours) |
| token_type | Identifies bearer authentication protocol (Bearer) |
| scope | Whitespace-separated permissions scope granted by user |
| locationId | The specific authorized Location CRM ID |
Tip: Never expose your access tokens or refresh tokens in frontend JavaScript code. Store and process them securely on your server backend.
Configure GHL Webhook Syncs Natively
Sign up for a GoHighLevel developer-capable subscription and gain access to custom redirect URLs and OAuth testing.
📚 Most Common API Endpoints
While GoHighLevel offers many endpoints, these are the ones developers use most frequently.
| Method | Endpoint Path | Purpose Description |
|---|---|---|
| GET | /v2/contacts/ | Retrieve contacts with filtering and pagination parameters. |
| POST | /v2/contacts/ | Create a new contact record with tags and custom fields. |
| PUT | /v2/contacts/{contactId} | Update email, phone, tags, or custom values for a contact. |
| DELETE | /v2/contacts/{contactId} | Delete a contact record permanently from a Location. |
| POST | /v2/opportunities/ | Create pipeline opportunities to track sales pipelines. |
| GET | /v2/opportunities/ | Retrieve opportunity cards registered under a pipeline. |
| GET | /v2/users/ | Fetch all registered agency users and client agents. |
| GET | /v2/calendars/ | Retrieve all booking calendars available in the account. |
| POST | /v2/webhooks/ | Register a webhook listener endpoint for real-time notifications. |
For most CRM integrations, you'll spend the majority of your time working with Contacts, Opportunities, Calendars, Conversations, and Webhooks.
👨💻 Making Your First API Request
Every request follows the same basic structure. You'll need:
- Authorization Header containing your Bearer Access Token
- Version Header specifying the GHL API version (e.g. `2021-07-28`)
- JSON Request Body (for POST/PUT requests)
Raw Headers Example Structure:
Authorization: Bearer YOUR_ACCESS_TOKEN
Version: 2021-07-28
Content-Type: application/jsonThe Version header is particularly important because it ensures your integration continues working even as the API evolves over time.
Example: Creating a Contact
One of the most common API operations is creating a new contact. A typical request sends details such as First Name, Last Name, Email, Phone Number, Tags, and Custom Fields.
Your application sends these values as JSON, and GoHighLevel creates the contact inside the selected Location.
This contact creation flow is commonly used for:
Node.js Integration Script:
// Example Node.js script to create a GoHighLevel contact
const createContact = async (accessToken, contactInfo) => {
const endpoint = "https://services.leadconnectorhq.com/hooks/v2/contacts/";
const response = await fetch(endpoint, {
method: "POST",
headers: {
"Authorization": `Bearer ${accessToken}`,
"Version": "2021-07-28",
"Content-Type": "application/json"
},
body: JSON.stringify({
firstName: contactInfo.firstName,
lastName: contactInfo.lastName,
email: contactInfo.email,
phone: contactInfo.phone,
tags: contactInfo.tags || [],
customFields: contactInfo.customFields || {}
})
});
if (!response.ok) {
const errorDetails = await response.text();
throw new Error(`API returned error: ${response.status} - ${errorDetails}`);
}
return await response.json();
};⚡ Working with Webhooks
While APIs allow your application to request information, webhooks allow GoHighLevel to send information to you automatically whenever something happens.
Think of webhooks as real-time notifications. Instead of checking every few minutes to see if a new lead has arrived, GoHighLevel simply sends the event directly to your server as soon as it happens. This is significantly faster and more efficient.
Common Webhook Events:
Popular Webhook Automation Workflows
Many agencies use webhook triggers to power automated multi-app integrations via n8n, Make, or Zapier:
🔄 API vs Webhooks
A common question from beginners is: "When should I use the API, and when should I use webhooks?"
Use the API when:
- You want to create data (e.g. create a contact from an external checkout).
- You want to update existing information in the CRM.
- You need to retrieve specific CRM records or filters.
- Your external application initiates the action.
⚡ Understanding Rate Limits
Like most modern APIs, GoHighLevel limits how many requests can be made within a short period.
Current GHL Rate Limits:
API allows approximately 100 requests every 10 seconds per Location account. If your application exceeds that, the API responds with an HTTP 429 Too Many Requests error.
Best Practices for Handling Rate Limits:
🔒 Security Best Practices
Whenever you're building an integration with GoHighLevel, security should be part of your design from day one. Here are our recommendations:
Secure Storage
Store access/refresh tokens securely on the server backend database.
No Frontend Exposure
Never expose API keys or credentials in client-side script code.
HTTPS Webhooks
Mandate SSL (HTTPS) for every single webhook receiver endpoint.
Minimal Scopes
Limit OAuth scopes strictly to permissions required for app functionality.
Frequently Asked Questions
Final Thoughts
GoHighLevel's API has grown into a powerful foundation for building custom integrations, automating agency workflows, and extending the platform far beyond its built-in features. Whether you're creating simple lead capture automations or developing a full white-label SaaS experience, the combination of REST APIs, OAuth 2.0 authentication, and real-time webhooks provides the flexibility most developers need.
If you're new to the platform, start with the Contacts API and OAuth authentication before exploring more advanced endpoints like Opportunities, Calendars, Conversations, and Workflows. Once you become comfortable with those basics, you'll find that integrating GoHighLevel into your own applications is both straightforward and highly scalable.
Ready to build your custom GHL integration?
Get access to the GoHighLevel developer sandbox environment. Start testing endpoints, configuring OAuth redirects, and syncing client data natively.