Developer API

The Developer API provides programmatic control over contacts, conversations, calendars, opportunities, payments, workflows, and more. Build custom integrations, automate data flows, extend the platform with your own applications. Current version is API V2 (V1 sunset, connections function but no support/updates). Base URL: https://services.leadconnectorhq.com.

What Developer API Does

OAuth 2.0 authentication (required for public marketplace apps, recommended for most integrations): redirect user to authorization URL with Client ID and scopes, user grants permission on consent screen, redirect back with authorization code, exchange code for access token and refresh token, use access token in Authorization: Bearer <token> header, refresh token obtains new access token when expired. Supports OAuth 2.0 with PKCE for browser-based/mobile apps where storing client secret isn’t secure.

Private integration tokens for internal tools/single-location use cases: generate directly from Settings > Integrations > API Key. Simpler but limited to specific account that generated token.

Two access levels: Location Level (Sub-Account) grants access to data within single sub-account (most common for client-facing integrations). Agency Level (Company) grants access across entire agency including managing sub-accounts, viewing cross-location data, performing agency-wide operations (required for SaaS Mode integrations and agency management tools).

Plan tier determines API features: Starter/Unlimited plans (basic API access with private integration tokens), Agency Pro plan (advanced API access including full OAuth capabilities and agency-level tokens).

Key Configuration Options

Getting Started. Navigate to marketplace.gohighlevel.com, create developer account, click My Apps > Create App, fill out app profile (name, description, logo), choose app type (Public App: listed in marketplace for anyone; Private App: restricted access, invitation only), select distribution type (Agency: accessible across all accounts; Sub-Account: limited to specific sub-accounts), generate Client ID and Client Secret (store securely, needed for every OAuth handshake).

Scopes and Permissions. Declare required scopes when creating app (users see on consent screen). Common scopes: contacts.readonly/contacts.write, conversations.readonly/conversations.write, calendars.readonly/calendars.write, opportunities.readonly/opportunities.write, locations.readonly, companies.readonly, workflows.readonly, invoices.readonly/invoices.write. Request minimum scopes needed (users more likely to install apps requesting fewer permissions). Full list documented at developer portal under Authorization > Scopes.

Core API Endpoints. Contacts (GET /contacts/v1/ lists, POST /contacts/v1/ creates, PUT /contacts/v1/{contactId} updates, DELETE /contacts/v1/{contactId} removes, POST /contacts/v1/{contactId}/tags adds tags). Opportunities (GET /opportunities/v1/ lists, POST /opportunities/v1/ creates, PUT /opportunities/v1/{opportunityId} updates). Conversations (GET /conversations/v1/ retrieves threads, GET /conversations/v1/{conversationId}/messages fetches messages, POST /conversations/v1/messages sends new message). Calendars (GET /calendars/v1/ lists calendars, GET /calendars/v1/{calendarId}/free-slots checks availability, POST /calendars/v1/events creates appointment). Workflows (GET /workflows/v1/ lists workflows, POST /workflows/v1/{workflowId}/enroll adds contact). Payments (GET /payments/v1/orders lists orders, GET /payments/v1/transactions lists transactions).

Pagination. List endpoints return paginated results using cursor-based pagination. Query parameters: limit (results per page, default varies by endpoint, typically 20), startAfter or startAfterId (cursor value from previous response to fetch next page). Check for meta.nextPageUrl or meta.startAfterId field in response to determine if more pages available.

Power Features

Webhooks. Deliver real-time notifications when events occur. Register webhook URL (must be HTTPS) in marketplace app settings, select events to subscribe to, save configuration. Endpoint must respond with 200 status within 5 seconds to acknowledge receipt. System retries delivery with exponential backoff on failure. Available events: Contact (created, updated, deleted, tag added/removed, DND updated), Opportunity (created, updated, deleted, stage/status changed), Appointment (created, updated, cancelled, no-show marked), Task (created, completed, deleted), Invoice (created, sent, paid, void, partially paid), Conversation (new inbound message, outbound message sent, updated), Form (submitted, survey submitted), Note (created, updated, deleted). Verify webhook signatures using HMAC-SHA256 hash computed with client secret and request body.

Rate Limits. Burst Limit (100 API requests per 10 seconds per marketplace app per resource, returns 429 Too Many Requests if exceeded). Daily Limit (200,000 API requests per day per marketplace app per resource, resets at midnight UTC). Monitor usage via response headers: X-RateLimit-Limit-Daily (daily quota), X-RateLimit-Daily-Remaining (remaining daily requests), X-RateLimit-Remaining (remaining burst requests), X-RateLimit-Reset (timestamp when burst window resets). Implement exponential backoff on 429 response using Retry-After header duration.

Error Handling. Standard HTTP status codes: 200 OK (succeeded), 201 Created (resource created), 400 Bad Request (invalid parameters/malformed body), 401 Unauthorized (missing/invalid token), 403 Forbidden (valid token but insufficient scopes), 404 Not Found (resource doesn’t exist), 422 Unprocessable Entity (valid JSON but semantic errors), 429 Too Many Requests (rate limit exceeded), 500 Internal Server Error (platform-side issue, retry with backoff). Error responses include JSON body with message field describing issue.

Building Marketplace App. Register at developer portal, create app with clear name/description/icon, configure OAuth (set redirect URI, select scopes, generate credentials), build integration using REST API and webhook endpoints, test thoroughly using sandbox sub-account (verify OAuth flows, token refresh cycles, webhook deliveries), submit for review (team checks security, user experience, API compliance), publish to marketplace once approved, monitor performance using developer dashboard (install counts, API usage, error rates).

Pro Tips

• Use OAuth 2.0 for all production integrations (better security, user consent, token management than private tokens).
• Request minimal scopes (only permissions app actually needs, improves user trust and simplifies security footprint).
• Implement proper token refresh (access tokens expire, handle refresh flow gracefully so integration never breaks silently).
• Handle rate limits proactively (monitor rate limit headers on every response, implement backoff logic before hitting ceiling).
• Validate webhook signatures (never process payload without verifying authenticity using HMAC-SHA256 validation).

Common Questions

What happened to API V1?

API V1 has reached end of support. Existing V1 connections function but no bug fixes, new features, or support provided. All new development should use V2 endpoints.

Do I need a specific plan to use the API?

Basic API access with private integration tokens available on Starter and Unlimited plans. OAuth-based integrations and agency-level access require Agency Pro plan.

How do I handle token expiration?

Access tokens expire after set period. Use refresh token to request new access token before expiration. Store new refresh token from response (previous one invalidated after each use).

What is difference between Location and Agency level access?

Location level access scopes app to single sub-account (suitable for most integrations). Agency level access grants visibility across all sub-accounts in agency (required for multi-location management tools or SaaS mode apps).

Is there a sandbox or staging environment?

No separate sandbox. Create test sub-account in your agency and use as development sandbox. Gives access to all features without risking production data.