GoHighLevel Integration

Overview

GoHighLevel (GHL) is the primary CRM platform. Gridlink syncs data from GHL at the Agency level, with each client represented as a GHL sub-account (Location).

Authentication

GHL uses OAuth2 via a Private Integration app.

Setup Steps

In GHL, go to Settings > Integrations > Private Integrations

Click Create App, name it "Gridlink Dashboard"

Select all *.readonly scopes (contacts, opportunities, calendars, conversations, campaigns, workflows, forms, surveys, locations, users, companies, invoices, payments, products, funnels, tags, custom fields, notes, tasks)

Save — GHL provides a Client ID and Client Secret

Click the install link to authorize against your agency

Copy the access_token and refresh_token

Enter all 4 values in Settings > Components > GoHighLevel in the Gridlink dashboard

Token Lifecycle

Access tokens expire every 24 hours

The sync engine refreshes tokens automatically using the refresh token

If the refresh token expires (~30 days of inactivity), the settings page shows "Reconnect Required"

Token refresh failures are logged and surfaced in the component status

Sync Behavior

Direction

Read-only. Gridlink pulls data from GHL but never writes back. To update data, use the GHL platform directly.

Frequency

Configurable per-component: 5 min, 15 min, 30 min, 1 hour, or daily. Default: 15 minutes.

Incremental Sync

First sync: full pull of all records

Subsequent syncs: only records modified since sync_cursor (last modified timestamp)

Periodic full sync (daily) as a safety net to catch any missed changes

Rate Limits

GHL API rate limit: 100 requests/minute per location. The sync engine:

Processes one location at a time

Includes automatic throttling (respects X-RateLimit-Remaining headers)

Backs off exponentially on 429 responses

Objects Synced

GHL Object	Mirror Table	Key Fields
Locations	`ghl_locations`	name, email, phone, address, timezone
Contacts	`ghl_contacts`	name, email, phone, tags, source, custom fields
Opportunities	`ghl_opportunities`	name, pipeline, stage, value, status
Pipelines	`ghl_pipelines`	name, stages
Pipeline Stages	`ghl_pipeline_stages`	name, order, pipeline_id
Appointments	`ghl_appointments`	title, calendar, contact, start/end time
Calendars	`ghl_calendars`	name, type
Conversations	`ghl_conversations`	contact, type, last message
Campaigns	`ghl_campaigns`	name, status
Forms	`ghl_forms`	name, fields
Form Submissions	`ghl_form_submissions`	form, contact, data
Users	`ghl_users`	name, email, role
Tags	`ghl_tags`	name, location
Custom Fields	`ghl_custom_fields`	name, type, location
Invoices	`ghl_invoices`	contact, amount, status
Payments	`ghl_payments`	contact, amount, date
Tasks	`ghl_tasks`	title, contact, due date, status
Notes	`ghl_notes`	contact, body

Error Handling

Sync failures are logged to sync_log table with error details

3 consecutive failures: component status changes to "Error" with red badge

Token expiry: status changes to "Reconnect Required"

Individual object failures don't block other objects from syncing

Troubleshooting

Problem	Check
No data syncing	Verify credentials in Settings > Components > GoHighLevel
Stale data	Check sync frequency and last sync timestamp
Missing contacts	Verify the location/sub-account has contacts in GHL
Auth errors	Token may have expired — click "Reconnect" in settings
Rate limit errors	Reduce sync frequency or check if another integration is consuming API quota

Viewing Sync Logs

Sync history is available at Settings > Components > GoHighLevel > View Sync Log. Each entry shows:

Start/end time

Records fetched / created / updated

Error details (if any)

Last updated: 5/26/2026