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. LeadRails needs contacts.write to create the contact, plus contacts.readonly so the "Verify connection" check can confirm the token can reach contacts in this Location. For pipeline assignment, also add 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

By default (no custom mapping) LeadRails sends:

• firstName / lastName — from the lead's name. A single full name is split on the first space.
• email and phone — when the lead has them.
• source — the submitting form's site URL, falling back to the lead's UTM source.
• tags — a single lead-router tag, so you can filter LeadRails contacts in GHL.
• With pipeline + stage set: also creates an opportunity at the configured stage with the contact attached.

Want different fields (company name, custom fields, your own tags)? Set up a per-route mapping in Routes → Mapping editor. The mapper controls exactly what goes on the wire.

Verify connection

When you save a GoHighLevel destination, LeadRails runs a read-only check against your Location's contacts. It confirms three things at once: the token is valid, it can reach the Location you entered, and it has the contacts permission that delivery needs. No test contact is created.

If the check fails, the message tells you which part broke:

• Rejected (401). The token is wrong, expired, or revoked. Generate a new one.
• Missing Contacts permission (403). The token is valid but wasn't given the contacts scope. Re-create it with View + Edit Contacts.
• Location not found (404). The Location ID is wrong, or this token can't see that Location.

Token type and limitations

LeadRails uses the token you paste, as-is, on every request. GoHighLevel also supports OAuth apps with access tokens that refresh on a schedule. LeadRails does not manage OAuth or refresh tokens today — you supply a Private Integration Token (or a legacy API key) and we send it.

Private Integration Tokens don't expire on a timer, so this is stable for day-to-day use. If you rotate or revoke the token in GoHighLevel, update it here too. Until you do, deliveries fail with a 401 and you get an alert.

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."