Let’s walk through “How to use the GoHighLevel API v2 | Complete Tutorial”, a practical guide that highlights Version 2 features missing from platforms like make.com and shows how to speed up API integration for businesses.
Let’s outline what to expect: getting started, setting up a GHL app, Make.com authentication for subaccounts and agency accounts, a step-by-step build of voice AI agents that schedule meetings, and clear reasons to skip the Make.com GHL integration.
Overview of GoHighLevel API v2 and What’s New
We’ll start with a high-level view so we understand why v2 matters and how it changes our integrations. GoHighLevel API v2 is the platform’s modernized, versioned HTTP API designed to let agencies and developers build deeper, more reliable automations and integrations with CRM, scheduling, pipelines, and workflow capabilities. It expands the surface area of what we can control programmatically and aims to support agency-level patterns like multi-tenant (agency + subaccount) auth, richer scheduling endpoints, and more granular webhook and lifecycle events.
Explain the purpose and scope of the API v2
The purpose of API v2 is to provide a single, consistent, versioned interface for manipulating core GHL objects — contacts, appointments, opportunities, pipelines, tags, workflows, and more — while enabling secure agency-level integrations. The scope covers CRUD operations on those resources, scheduling and calendar availability, webhook subscriptions, OAuth app management, and programmatic control over many features that previously required console use. In short, v2 is meant for production-grade integrations for agencies, SaaS, and automation tooling.
Highlight major differences between API v2 and previous versions
Compared to earlier versions, v2 focuses on clearer versioning, more predictable schemas, improved pagination/filtering, and richer auth flows for agency/subaccount models. We see more granular scopes, better-defined webhook event sets, and endpoints tailored to scheduling and provider availability. Error responses and pagination are generally more consistent, and there’s an emphasis on agency impersonation patterns — letting an agency app act on behalf of subaccounts more cleanly.
List features unique to API v2 that other platforms (like Make.com) lack
API v2 exposes a few agency-centric features that many third-party automation platforms don’t support natively. These include agency-scoped OAuth flows that allow impersonation of subaccounts, detailed calendar and provider availability endpoints for scheduling logic, and certain pipeline/opportunity or conversation APIs that are not always surfaced by general-purpose integrators. v2’s webhook control and subscription model is often more flexible than what GUI-based connectors expose, enabling lower-latency, event-driven architectures.
Describe common use cases for agencies and automation projects
We commonly use v2 for automations like automated lead routing, appointment scheduling with real-time availability checks, two-way calendar sync, advanced opportunity management, voice AI scheduling, and custom dashboards that aggregate multiple subaccounts. Agencies build connectors to unify client data, create multi-tenant SaaS offerings, and embed scheduling or messaging experiences into client websites and call flows.
Summarize limitations or known gaps in v2 to watch for
While v2 is powerful, it still has gaps to watch: documentation sometimes lags behind feature rollout; certain UI-only features may not yet be exposed; rate limits and batch operations might be constrained; and some endpoints may require extra parameters (account IDs) to target subaccounts. Also expect evolving schemas and occasional breaking changes if you pin to a non-versioned path. We should monitor release notes and design our integration for graceful error handling and retries.
Prerequisites and Account Requirements
We’ll cover what account types, permissions, tools, and environment considerations we need before building integrations.
Identify account types supported by API v2 (agency vs subaccount)
API v2 supports multi-tenant scenarios: the agency (root) account and its subaccounts (individual client accounts). Agency-level tokens let us manage apps and perform agency-scoped tasks, while subaccount-level tokens (or OAuth authorizations) let us act on behalf of a single client. It’s essential to know which layer we need for each operation because some endpoints are agency-only and others must be executed in the context of a subaccount.
Required permissions and roles in GoHighLevel to create apps and tokens
To create apps and manage OAuth credentials we’ll need agency admin privileges or a role with developer/app-management permissions. For subaccount authorizations, the subaccount owner or an admin must consent to the scopes our app requests. We should verify that the roles in the GHL dashboard allow app creation, OAuth redirect registration, and token management before building.
Needed developer tools: HTTP client, Postman, curl, or SDK
For development and testing we’ll use a standard HTTP client like curl or Postman to exercise endpoints, debug requests, and inspect responses. For iterative work, Postman or Insomnia helps organize calls and manage environments. If an official SDK exists for v2 we’ll evaluate it, but most teams will build against the REST endpoints directly using whichever language/framework they prefer.
Network and security considerations (IP allowlists, CORS, firewalls)
Network-wise, we should run API calls from secure server-side environments — API secrets and client secrets must never be exposed to browsers. If our org uses IP allowlists, we must whitelist our integration IPs in the GoHighLevel dashboard if that feature is enabled. Since most API calls are server-to-server, CORS is not a server-side concern, but web clients using implicit flows or front-end calls must be careful about exposing secrets. Firewalls and egress rules should allow outbound HTTPS to the API endpoints.
Recommended environment setup for development (local vs staging)
We recommend developing locally with environment variables and a staging subaccount to avoid polluting production data. Use a staging agency/subaccount pair to test multi-tenant flows and webhooks. For secrets, use a secret manager or environment variables; for deployment, use a separate staging environment that mirrors production to validate token refresh and webhook handling before going live.
Registering and Setting Up a GoHighLevel App
We’ll walk through creating an app in the agency dashboard and the critical app settings to configure.
How to create a GHL app in the agency dashboard
In the agency dashboard we’ll go to the developer or integrations area and create a new app. We provide the app name, a concise description, and choose whether it’s public or private. Creating the app registers a client_id and client_secret (or equivalent credentials) that we’ll use for OAuth flows and token exchange.
Choosing app settings: name, logo, and public information
Pick a clear, recognizable app name and brand assets (logo, short description) so subaccount admins know who is requesting access. Public-facing information should accurately describe what the app does and which data it will access — this helps speed consent during OAuth flows and builds trust with client admins.
How to set and validate redirect URIs for OAuth flows
When we configure OAuth, we must specify exact redirect URI(s) that the authorization server will accept. These must match the URI(s) our app will actually use. During testing, set local URIs (like a ngrok forwarding URL) only if the dashboard allows them. Redirect URIs should use HTTPS in production and be as specific as possible to avoid open redirect vulnerabilities.
Understanding OAuth client ID and client secret lifecycle
The client_id is public; the client_secret is private and must be treated like a password. If the secret is leaked we must rotate it immediately via the app management UI. We should avoid embedding secrets in client-side code, and rotate secrets periodically as part of security hygiene. Some platforms support generating multiple secrets or rotating with zero-downtime — follow the dashboard procedures.
How to configure scopes and permission requests for your app
When registering the app, select the minimal set of scopes needed — least privilege. Examples include read:contacts, write:appointments, manage:webhooks, etc. Requesting too many scopes will reduce adoption and increase risk; requesting too few will cause permission errors at runtime. Be explicit in consent screens so admins approve access confidently.
Authentication Methods: OAuth and API Keys
We’ll compare the two common authentication patterns and explain steps and best practices for each.
Overview of OAuth 2.0 vs direct API key usage in GHL v2
OAuth 2.0 is the recommended method for agency-managed apps and multi-tenant flows because it provides delegated consent and token lifecycles. API keys (or direct tokens) are simpler for single-account server-to-server integrations and can be generated per subaccount in some setups. OAuth supports refresh token rotation and scope-based access, while API keys are typically long-lived and require careful secret handling.
Step-by-step OAuth flow for agency-managed apps
The OAuth flow goes like this: 1) Our app directs an admin to the authorize URL with client_id, redirect_uri, and requested scopes. 2) The admin authenticates and consents. 3) The authorization server returns an authorization code to our redirect URI. 4) We exchange that code for an access token and refresh token using the client_secret. 5) We use the access token in Authorization: Bearer
Acquiring API keys or tokens for subaccounts when available
For certain subaccount-only automations we can generate API keys or account-specific tokens in the subaccount settings. The exact UI varies, but typically an admin can produce a token that we store and use in the Authorization header. These tokens are useful for server-to-server integrations where OAuth consent UX is unnecessary, but they require secure storage and rotation policies.
Refreshing access tokens: refresh token usage and rotation
Refresh tokens let us request new access tokens without user interaction. We should implement automatic refresh logic before tokens expire and handle refresh failures gracefully by re-initiating the OAuth consent flow if needed. Where possible, follow refresh token rotation best practices: treat refresh tokens as sensitive, store them securely, and rotate them when they’re used (some providers issue a new refresh token per refresh).
Secure storage and handling of secrets in production
In production we store client secrets, access tokens, and refresh tokens in a secrets manager or environment variables with restricted access. Never commit secrets to source control. Use role-based access to limit who can retrieve secrets and audit access. Encrypt tokens at rest and transmit them only over HTTPS.
Authentication for Subaccounts vs Agency Accounts
We’ll outline how auth differs when we act as an agency versus when we act within a subaccount.
Differences in auth flows between subaccounts and agency accounts
Agency auth typically uses OAuth client credentials tied to the agency app and supports impersonation patterns so we can operate across subaccounts. Subaccounts may use their own tokens or OAuth consent where the subaccount admin directly authorizes our app. The agency flow often requires additional headers or parameters to indicate which subaccount we’re targeting.
How to authorize on behalf of a subaccount using OAuth or account linking
To authorize on behalf of a subaccount we either obtain separate OAuth consent from that subaccount or use an agency-scoped consent that enables impersonation. Some flows involve account linking: the subaccount owner logs in and consents, linking their account to the agency app. After linking we receive tokens that include the subaccount context or an account identifier we include in API calls.
Scoped access for agency-level integrations and impersonation patterns
When we impersonate a subaccount, we limit actions to the specified scopes and subaccount context. Best practice is to request the smallest scope set and, where possible, request per-subaccount consent rather than broad agency-level scopes that grant access to all clients.
Making calls to subaccount-specific endpoints and including the right headers
Many endpoints require us to include either an account identifier in the URL or a header (for example, an accountId query param or a dedicated header) to indicate the target subaccount. We must consult endpoint docs to determine how to pass that context. Failing to include the account context commonly results in 403/404 errors or operations applied to the wrong tenant.
Common pitfalls and how to detect permission errors
Common pitfalls include expired tokens, insufficient scopes, missing account context, or using an agency token where a subaccount token is required. Detect permission errors by inspecting 401/403 responses, checking error messages for missing scopes, and logging the request/response for debugging. Implement clear retry and re-auth flows so we can recover from auth failures.
Core API Concepts and Common Endpoints
We’ll cover basics like base URL, headers, core resources, request body patterns, and relationships.
Explanation of base URL, versioning, and headers required for v2
API v2 uses a versioned base path so we can rely on /v2 semantics. We’ll set the base URL in our client and include standard headers: Authorization: Bearer
Common resources: contacts, appointments, opportunities, pipelines, tags, workflows
Core resources we’ll use daily are contacts (lead and customer records), appointments (scheduled meetings), opportunities and pipelines (sales pipeline management), tags for segmentation, and workflows for automation. Each resource typically supports CRUD operations and relationships between them (for example, a contact can have appointments and opportunities).
How to construct request bodies for create, read, update, delete operations
Create and update operations generally accept JSON payloads containing relevant fields: contact fields (name, email, phone), appointment details (start, end, timezone, provider_id), opportunity attributes (stage, value), and so on. For updates, include the resource ID in the path and send only changed fields if supported. Delete operations usually require the resource ID and respond with status confirmations.
Filtering, searching, and sorting resources using query parameters
We’ll use query parameters for filtering, searching, and sorting: common patterns include ?page=, ?limit=, ?sort=, and search or filter params like ?email= or ?createdAfter=. Advanced endpoints often support flexible filter objects or search endpoints that accept complex queries. Use pagination to manage large result sets and avoid pulling everything in one call.
Understanding relationships between objects (contacts -> appointments -> opportunities)
Objects are linked: contacts are the primary entity and can be associated with appointments, opportunities, and workflows. When creating an appointment we should reference the contact ID and, where applicable, provider or calendar IDs. When updating an opportunity stage we may reference related contacts and pipeline IDs. Understanding these relationships helps us design consistent payloads and avoid orphaned records.
Working with Appointments and Scheduling via API
Scheduling is a common and nuanced area; we’ll cover endpoints, availability, timezone handling, and best practices.
Endpoints and payloads related to appointments and calendar availability
Appointments endpoints let us create, update, fetch, and cancel meetings. Payloads commonly include start and end timestamps, timezone, provider (staff) ID, location or meeting link, contact ID, and optional metadata. Availability endpoints allow us to query a provider’s free/busy windows or calendar openings, which is critical to avoid double bookings.
How to check provider availability and timezones before creating meetings
Before creating an appointment we query provider availability for the intended time range and convert times to the provider’s timezone. We must respect daylight saving and ensure timestamps are in ISO 8601 with timezone info. Many APIs offer helper endpoints to get available slots; otherwise, we query existing appointments and external calendar busy times to compute free slots.
Creating, updating, and cancelling appointments programmatically
To create an appointment we POST a payload with contact, provider, start/end, timezone, and reminders. To update, we PATCH the appointment ID with changed fields. Cancelling is usually a delete or a PATCH that sets status to cancelled and triggers notifications. Always return meaningful responses to calling systems and handle conflicts (e.g., 409) if a slot was taken concurrently.
Best practices for handling reschedules and host notifications
For reschedules, we should treat it as an update that preserves history: log the old time, send notifications to hosts and guests, and include a reason if provided. Use idempotency keys where supported to avoid duplicate booking on retries. Send calendar invites or updates to linked external calendars and notify all attendees of changes.
Integrating GHL scheduling with external calendar systems
To sync with external calendars (Google, Outlook), we either leverage built-in calendar integrations or replicate events via APIs. We need to subscribe to external calendar webhooks or polling to detect external changes, reconcile conflicts, and mark GHL appointments as linked. Always store calendar event IDs so we can update/cancel the external event when the GHL appointment changes.
Voice AI Agent Use Case: Automating Meeting Scheduling
We’ll describe a practical architecture for using v2 with a voice AI scheduler that handles calls and books meetings.
High-level architecture for a voice AI scheduler using GHL v2
Our architecture includes the voice AI engine (speech-to-intent), a middleware server that orchestrates state and API calls to GHL v2, and calendar/webhook components. When a call arrives, the voice agent extracts intent and desired times, the middleware queries provider availability via the API, and then creates an appointment. We log the outcome and notify participants.
Flow diagram: call -> intent recognition -> calendar query -> appointment creation
Operationally: 1) Incoming call triggers voice capture. 2) Voice AI converts speech to text and identifies intent/slots (date, time, duration, provider). 3) Middleware queries GHL for availability for requested provider and time window. 4) If a slot is available, middleware POSTs appointment. 5) Confirmation is returned to the voice agent and a confirmation message is delivered to the caller. 6) Webhook or API response triggers follow-up notifications.
Handling availability conflicts and fallback strategies in conversation
When conflicts arise, we fall back to offering alternative times: query the next-best slots, propose them in the conversation, or offer to send a booking link. We should implement quick retries, soft holds (if supported), and clear messaging when no slots are available. Always confirm before finalizing and surface human handoff options if the user prefers.
Mapping voice agent outputs to API payloads and fields
The voice agent will output structured data (start_time, end_time, timezone, contact info, provider_id, notes). We map those directly into the appointment creation payload fields expected by the API. Validate and normalize phone numbers, names, and timezones before sending, and log the mapped payload for troubleshooting.
Logging, auditing, and verifying booking success back to the voice agent
After creating a booking, verify the API response and store the appointment ID and status. Send a confirmation message to the voice agent and store an audit trail that includes the original audio, parsed intent, API request/response, and final booking status. This telemetry helps diagnose disputes and improve the voice model.
Webhooks: Subscribing and Handling Events
Webhooks drive event-based systems; we’ll cover event selection, verification, and resilient handling.
Available webhook events in API v2 and typical use cases
v2 typically offers events for resource create/update/delete (contacts.created, appointments.updated, opportunities.stageChanged, workflows.executed). Typical use cases include syncing contact changes to CRMs, reacting to appointment confirmations/cancellations, and triggering downstream automations when opportunities move stages.
Setting up webhook endpoints and validating payload signatures
We’ll register webhook endpoints in the app dashboard and select the events we want. For security, enable signature verification where the API signs each payload with a secret; validate signatures on receipt to ensure authenticity. Use HTTPS, accept only POST, and respond quickly with 2xx to acknowledge.
Design patterns for idempotent webhook handlers
Design handlers to be idempotent: persist an event ID and ignore repeats, use idempotency keys when making downstream calls, and make processing atomic where possible. Store state and make webhook handlers small — delegate longer-running work to background jobs.
Handling retry logic when receiving webhook replays
Expect retries for transient errors. Ensure handlers return 200 only after successful processing; otherwise return a non-2xx so the platform retries. Build exponential backoff and dead-letter patterns for events that fail repeatedly.
Tools to inspect and debug webhook deliveries during development
During development we can use temporary forwarding tools to inspect payloads and test signature verification, and maintain logs with raw payloads (masked for sensitive data). Use staging webhooks for safe testing and ensure replay handling works before going live.
Conclusion
We’ll wrap up with key takeaways and next steps to get building quickly.
Recap of essential steps to get started with GoHighLevel API v2
To get started: create and configure an app in the agency dashboard, choose the right auth method (OAuth for multi-tenant, API keys for single-account), implement secure token storage and refresh, test core endpoints for contacts and appointments, and register webhooks for event-driven workflows. Use a staging environment and validate scheduling flows thoroughly.
Key best practices to follow for security, reliability, and scaling
Follow least-privilege scopes, store secrets in a secrets manager, implement refresh logic and rotation, design idempotent webhook handlers, and use pagination and batching to respect rate limits. Monitor telemetry and errors, and plan for horizontal scaling of middleware that handles real-time voice or webhook traffic.
When to prefer direct API integration over third-party platforms
Prefer direct API integration when you need agency-level impersonation, advanced scheduling and availability logic, lower latency, or features not exposed by third-party connectors. If you require fine-grained control over retry, idempotency, or custom business logic (like voice AI agents), direct integration gives us the flexibility we need.
Next steps and resources to continue learning and implementing
Next, we should prototype a small workflow: implement OAuth or API key auth, create a sample contact, query provider availability, and book an appointment. Iterate with telemetry and add webhooks to close the loop. Use Postman or a small script to exercise the end-to-end flow before integrating the voice agent.
Encouragement to prototype a small workflow and iterate based on telemetry
We encourage us to build a minimal, focused prototype — even a single flow that answers “can the voice agent book a meeting?” — and to iterate. Telemetry will guide improvements faster than guessing. With v2’s richer capabilities, we can quickly move from proof-of-concept to a resilient, production automation that brings real value to our agency and clients.
If you want to implement Chat and Voice Agents into your business to reduce missed calls, book more appointments, save time, and make more revenue, book a discovery call here: https://brand.eliteaienterprises.com/widget/bookings/elite-ai-30-min-demo-call
