GoHighLevel

What this is

GoHighLevel (GHL) is a marketing + sales platform widely used by agencies. Each customer is a "Location" (sub-account). LeadRails creates a contact in the target Location for each lead. With optional pipeline configuration, the contact also gets added to a specific sales pipeline at a named stage — perfect for triggering GHL automations from inbound leads.

Where to find your credentials

Location ID

1. Sign in to your GHL agency dashboard.
2. Pick the sub-account (Location) you want LeadRails to send to.
3. After clicking into the Location, the URL becomes https://app.gohighlevel.com/v2/location/<LOCATION_ID>/dashboard.
4. Copy the <LOCATION_ID> from the URL — it looks like loc_abc123xyz or a long alphanumeric.

Private Integration Token (newer flow — recommended)

1. Inside the target Location: Settings → Business Profile.
2. Scroll to "Private Integration Token" → click "Create New".
3. Pick scopes — for LeadRails you need at minimum: contacts.write. For pipeline assignment, also: opportunities.write and pipelines.read.
4. Copy the token immediately — starts with pit- followed by a UUID.
5. GHL only shows the token once.

Legacy API Key (older Locations)

If you don't see "Private Integration Token", use Settings → API Keys instead. Legacy keys are long opaque strings without a prefix.

We recommend migrating to Private Integration Token when possible — it's scoped + revocable.

Adding contacts to a pipeline (optional)

If you want LeadRails leads to drop directly into a pipeline (not just create a contact), grab the Pipeline ID + Stage ID:

1. In your Location: Settings → Pipelines → click your pipeline.
2. The URL becomes https://app.gohighlevel.com/v2/location/<LOC>/settings/pipelines/<PIPELINE_ID>.
3. Copy the <PIPELINE_ID>.
4. Click the stage you want leads to land at — its ID appears in the page's URL or in the stage detail panel.
5. Copy the <STAGE_ID>.

Both must be set together for pipeline assignment. Setting only one is treated as "no pipeline" (contact still gets created, just not added to a pipeline).

Set up your destination in LeadRails

1. Sign in → Destinations → New.
2. Adapter type: GoHighLevel (Beta).
3. Location ID: paste.
4. API Key: paste your Private Integration Token (or legacy key).
5. Pipeline ID (optional): paste if you want pipeline routing.
6. Stage ID (optional): paste if you want pipeline routing (both required together).
7. Click Create.

Test it

1. Sources → your source → Settings → ensure a route exists from this source to the GHL destination.
2. Click "Send test event".
3. Within seconds: a contact "Test Lead" with email test+leadrails@example.com appears in your GHL Location's contact list.
4. If pipeline + stage are configured: the contact also shows up as an opportunity at the named stage.
5. Clean up the test contact in GHL after verifying.

Contact record shape

• LeadRails creates a contact with: first_name (from lead.name, split), last_name, email, phone, source ="LeadRails" tag, customField entries for source_url and any UTM params.
• With pipeline + stage: also creates an opportunity at the configured stage with the contact attached.
• Customize via per-route mapping (Routes → Mapping editor).

Common issues

401 "Invalid token"

Token expired or revoked. Generate a new Private Integration Token.

403 "Insufficient scopes"

Token doesn't have contacts.write (or opportunities.write if using pipeline). Re-generate with broader scopes.

404 "Location not found"

Location ID is wrong, or the token doesn't have access to that Location. Verify Location ID matches the URL exactly.

422 "Invalid pipeline/stage"

Pipeline ID or Stage ID is wrong, or the stage doesn't belong to the pipeline. Both IDs must match the Location.

Duplicate contact

GHL has fuzzy email matching. Contact may have been created elsewhere; LeadRails treats this as a soft conflict (still surfaces in Jobs as a permanent_failure for review).

Beta status

GoHighLevel was added to LeadRails in our v2 adapter wave. It's stable enough to use in production, but we're still tuning the contact-deduplication strategy and gathering feedback on which custom fields to expose. The Beta label reflects "recently shipped" rather than "unreliable."