Recipe Format

Every recipe in this book follows a consistent structure:

• What You'll Build — The outcome in one sentence
• Ingredients (Endpoints) — API endpoints and scopes needed
• The Recipe (Steps) — Step-by-step implementation
• How It Works — What's happening under the hood
• Try It in the Playground — Test it live before building

Difficulty Levels

Tool Icons

What It Is

A browser-based tool to test any GoHighLevel API endpoint. No Postman, no curl commands, no setup — just paste your token and go.

How to Connect

1. Visit buildaischool.com/gohighlevel-api
2. Enter your Private Integration Token
3. Select your endpoint from the dropdown
4. Click Send — see the response in real time

Features

• Auto-fills required headers (Authorization, Version, Content-Type)
• Shows formatted response data with syntax highlighting
• Saves request history for quick re-testing
• Supports all 413+ GHL API endpoints
• Copy-paste friendly request/response panels

What You'll Build

Set up your Private Integration Token and make your first authenticated API call.

Ingredients

Settings → Integrations → Private Integrations

The Recipe

1. Navigate to Settings → Integrations
2. Click "Create Integration"
3. Name it (e.g., API Cookbook)
4. Copy your Bearer Token
5. Required headers for every API call:

Authorization: Bearer YOUR_TOKEN
Version: 2021-07-28
Content-Type: application/json

How It Works

The token authenticates every request you make. The Version header is required on EVERY request — GHL uses API versioning to manage breaking changes. Content-Type tells GHL you're sending JSON.

What You'll Build

Search your contact database using the API.

Ingredients

POST /contacts/search · Scope: contacts.readonly

The Recipe

POST https://services.leadconnectorhq.com/contacts/search

// Headers
Authorization: Bearer YOUR_TOKEN
Version: 2021-07-28

// Body
{
  "locationId": "YOUR_LOCATION_ID",
  "page": 1,
  "pageLimit": 20,
  "filters": []
}

Response

Returns a contacts array with id, firstName, lastName, email, phone, and tags for each match.

How It Works

POST /contacts/search is the recommended way to find contacts. The old GET /contacts/ endpoint is deprecated. Always use POST search.

Ingredients

POST /contacts/ · Scope: contacts.write

The Recipe

POST https://services.leadconnectorhq.com/contacts/

{
  "locationId": "YOUR_LOCATION_ID",
  "firstName": "John",
  "lastName": "Doe",
  "email": "john@example.com",
  "phone": "+1234567890",
  "tags": ["api-created", "cookbook-test"],
  "source": "API Cookbook"
}

How It Works

locationId is always required — it tells GHL which sub-account to create the contact in. Tags help you track API-created contacts. The source field shows where the contact came from in the GHL UI.

Ingredients

POST /contacts/upsert · Scope: contacts.write

The Recipe

POST https://services.leadconnectorhq.com/contacts/upsert

{
  "locationId": "YOUR_LOCATION_ID",
  "firstName": "John",
  "email": "john@example.com",
  "tags": ["returning-lead"]
}

How It Works

If a contact with that email exists, it updates the record. If not, it creates a new one. This is THE pattern for avoiding duplicates. It matches on email or phone.

Ingredients

GET /contacts/search/duplicate · Scope: contacts.readonly

The Recipe

GET /contacts/search/duplicate?locationId=XXX&email=john@example.com

How It Works

Returns matching contacts by email or phone. Use this before creating contacts if you need to handle duplicates with custom logic (e.g., merging fields, prompting the user).

What You'll Build

A workflow that searches for duplicate contacts and auto-tags them as "new" or "returning."

Ingredients

• Workflow Trigger: Form Submitted
• Custom Webhook → POST /contacts/search
• If/Else condition
• Add Tag action

The Recipe

1. Create Workflow → Trigger: Form Submitted
2. Add Action → Send Data → Custom Webhook
3. Method: POST
4. URL: https://services.leadconnectorhq.com/contacts/search
5. Headers: Authorization (Bearer token), Version (2021-07-28), Content-Type (application/json)
6. Body:

{
  "locationId": "{{location.id}}",
  "filters": [{
    "field": "email",
    "operator": "eq",
    "value": "{{contact.email}}"
  }]
}

7. Add If/Else: Check response for matches
8. Found → Tag "returning-lead" / Not Found → Tag "new-lead"

What You'll Build

Form submission automatically creates an opportunity in your sales pipeline.

Ingredients

• Custom Webhook → GET /opportunities/pipelines (fetch pipeline & stage IDs)
• Custom Webhook → POST /opportunities/ (create opportunity)

The Recipe

1. Trigger: Form Submitted
2. Webhook #1: GET /opportunities/pipelines?locationId={{location.id}}
   → Capture pipelineId and stageId from response
3. Webhook #2: POST /opportunities/

{
  "pipelineId": "...",
  "locationId": "...",
  "name": "{{contact.name}} - New Deal",
  "status": "open",
  "contactId": "{{contact.id}}",
  "pipelineStageId": "...",
  "monetaryValue": 500
}

What You'll Build

Check calendar availability and book an appointment — all inside GHL workflows.

Ingredients

• Custom Webhook → GET /calendars/{id}/free-slots
• Custom Webhook → POST /calendars/events/appointments
• Custom Webhook → POST /conversations/messages (Version: 2021-04-15!)

The Recipe

1. Trigger: Contact Tag Added = "book-now"
2. Webhook #1: GET free-slots with startDate, endDate, timezone
3. Extract first available slot from response
4. Webhook #2: POST appointment with calendarId, contactId, startTime
5. Webhook #3: POST SMS confirmation

What You'll Build

When an appointment completes, automatically advance the contact's pipeline stage.

Ingredients

• Trigger: Appointment Status Changed
• Custom Webhook → GET /opportunities/search
• Custom Webhook → PUT /opportunities/{id}
• Custom Webhook → POST /contacts/{id}/notes

The Recipe

1. Trigger: Appointment Status = "showed"
2. Webhook #1: Search opportunities by contactId, status=open
3. If/Else: opportunity found?
4. Webhook #2: PUT opportunity with new pipelineStageId
5. Webhook #3: POST note logging the stage change with timestamp

What You'll Build

A multi-workflow system: form → dedup → opportunity → booking → pipeline advance.

Workflow A: Lead Intake

Workflow B: Appointment Follow-Up

Workflow C: Deal Won

Endpoints Used (9 Total via Custom Webhooks)

POST /contacts/search · POST /contacts/upsert · POST /contacts/{id}/tags · POST /opportunities/ · PUT /opportunities/{id} · GET /opportunities/search · GET /calendars/{id}/free-slots · POST /calendars/events/appointments · POST /conversations/messages

Setup

Location: Workflow → Add Action → Send Data → Custom Webhook
Cost: $0.01/execution (100 free included)

Required Headers

The 10 Most Useful Endpoints

What You'll Build

Send SMS through any carrier (not Twilio), receive replies back in GHL conversations.

Architecture

The Recipe (Outbound)

1. GHL Workflow: Outbound Message trigger
2. Custom Webhook → POST to n8n webhook URL
3. n8n receives → calls SMS gateway API (rbsoft/Semaphore/any provider)

The Recipe (Inbound)

1. SMS gateway webhooks reply to n8n
2. n8n: POST /contacts/search (find contact by phone)
3. n8n: POST /conversations/ (create conversation if needed)
4. n8n: POST /conversations/messages/inbound (log message, Version: 2021-04-15)

What You'll Build

Auto-enrich and score leads, then route to the appropriate pipeline stage based on score.

Ingredients

• POST /locations/{locationId}/customFields — create score fields
• PUT /contacts/{contactId} — write score back
• POST /contacts/{id}/tags — tier tag: hot/warm/cold
• POST /opportunities/ — create in appropriate stage

The Recipe

1. n8n Webhook receives GHL ContactCreate event
2. n8n: Call Apollo/Clearbit for enrichment data
3. n8n Function: Calculate score (0–100) based on company size, title, revenue
4. n8n: PUT /contacts/{id} → write lead_score custom field
5. n8n Switch node:
   • Score ≥ 80 → Hot path
   • Score ≥ 50 → Warm path
   • Below 50 → Cold path
6. Hot: POST /opportunities/ (Qualified stage) + enroll in hot-lead workflow
7. Cold: Tag "long-term-drip" only

What You'll Build

Nightly batch job that enriches and scores your entire contact database.

The Recipe

1. n8n Schedule Trigger: daily at 2 AM
2. POST /contacts/search: filter enrichment_status != "complete"
3. SplitInBatches: 10 contacts at a time
4. For each: enrich → score → write back via PUT /contacts/{id}
5. 700ms delay between batches (rate limit safe: ~85 req/min)
6. On error: tag "enrichment-failed" and continue to next

What You'll Build

An AI phone agent that checks your GHL calendar and books appointments mid-call.

Architecture

Ingredients

• GET /contacts/{contactId} — fetch contact for call
• GET /calendars/{id}/free-slots — mid-call availability check
• POST /calendars/events/appointments — book the slot
• POST /conversations/messages — SMS confirmation
• PUT /contacts/{id} — write call outcome

The Recipe

1. GHL: Tag "call-now" → Custom Webhook to n8n
2. n8n: GET contact details → POST to Vapi create-call API
3. Vapi mid-call: tool "check_availability" → n8n → GET free-slots → return formatted slots
4. Vapi: tool "book_appointment" → n8n → POST appointment
5. Post-call: PUT contacts with call_outcome, POST tags, update pipeline

What You'll Build

Same appointment-setting pattern as Recipe 3.4, but using Retell's Custom LLM WebSocket interface.

Key Differences: Vapi vs. Retell

Architecture

Both use n8n as middleware to GHL. The core pattern is identical:

1. GHL triggers the call via n8n
2. Voice AI handles conversation
3. Mid-call tools call n8n → n8n calls GHL API
4. Post-call: update contact, tags, pipeline

Endpoints: Same as Recipe 3.4

HTTP Request Node Settings

Method: POST / GET / PUT / DELETE
URL: https://services.leadconnectorhq.com/{endpoint}
Authentication: Header Auth
  Name: Authorization
  Value: Bearer {{$credentials.ghlToken}}
Headers:
  Version: 2021-07-28
  Content-Type: application/json
Body: JSON (specify parameters)

Secure Token Storage

Never hardcode tokens. Use n8n's Credentials Store:

1. Settings → Credentials → Add Credential
2. Type: Header Auth
3. Name: Authorization / Value: Bearer YOUR_TOKEN
4. Reference in nodes via {{$credentials.ghlToken}}

Common n8n Patterns

Error Handling

Use the IF node to check HTTP status codes after every API call:

// Check for success
IF {{ $json.statusCode }} == 200 → Continue
ELSE → Error Handler (log to Supabase, retry, or alert)

What You'll Build

Form submission → Sub-account creation → Custom field setup → User login → Welcome SMS. Full automated onboarding.

Ingredients

• POST /locations/ — create sub-account (Agency Pro $497 plan required)
• POST /oauth/locationToken — generate token for new account
• POST /locations/{id}/customFields — setup fields
• POST /contacts/ — create client contact
• POST /users/ — create user login
• POST /conversations/messages — welcome SMS

The Recipe

1. Make: Webhook receives form data from GHL
2. Make HTTP: POST /locations/ with companyId, name, timezone
3. Make HTTP: POST /oauth/locationToken → get new location token
4. Make HTTP: POST /locations/{id}/customFields → create standard fields
5. Make HTTP: POST /users/ → create user login
6. Make HTTP: POST /conversations/messages → welcome SMS

What You'll Build

Link Custom Objects to Opportunities via the Associations API.

Ingredients

• POST /associations/relations — create the link
• GET /associations/relations/{recordId} — verify

The Recipe (2-Workflow Pattern)

Workflow 1: Form → Find/Create Opportunity → Create Associated Record (Account object)

Workflow 2: Object Created trigger → Stamp self-ID → Custom Webhook:

POST /associations/relations

{
  "firstRecordId": "account_id",
  "secondRecordId": "opportunity_id",
  "associationId": "static_association_id",
  "locationId": "..."
}

HTTP Module Configuration

URL: https://services.leadconnectorhq.com/{endpoint}
Method: POST / GET / PUT / DELETE
Headers:
  Authorization: Bearer {{connection.token}}
  Version: 2021-07-28
  Content-Type: application/json
Body type: Raw → JSON
Request content: (your JSON body)

Tips for Make.com Users

• Use the HTTP module (not a GHL-specific module) for full control
• Store your token in Make's Data Store or as a custom Connection
• Use Router modules to branch based on API responses
• Set Error Handler on every HTTP module → Resume / Retry / Ignore
• Make's Iterator is equivalent to n8n's SplitInBatches
• Use Sleep module (700ms) between batch API calls for rate limiting

What You'll Build

Sync GHL data to Supabase, calculate KPIs, display on a live dashboard.

Ingredients

• POST /contacts/search — sync contacts
• GET /opportunities/search — sync pipeline
• GET /calendars/events — sync appointments
• Supabase Edge Function for KPI calculations

The Recipe

1. Create Supabase tables: contacts, opportunities, kpi_snapshots
2. n8n hourly sync: POST /contacts/search → upsert to Supabase
3. n8n: GET opportunities → upsert to Supabase
4. Edge Function: calculate win_rate, revenue, avg_response_time
5. Frontend: Lovable React app with KPI cards + charts

What You'll Build

AI classifies every inbound message as booking request, inquiry, complaint, or spam — and auto-responds when confident.

Ingredients

• GHL Webhook: InboundMessage event
• GET /conversations/{id}/messages — get context
• POST /conversations/messages — auto-reply
• POST /contacts/{id}/tags — classification tag

The Recipe

1. Edge Function: ghl-inbound-handler receives webhook
2. Parse message → store in Supabase
3. Call Claude/GPT: classify as booking_request / inquiry / complaint / spam
4. If confidence > 0.8: POST auto-reply via Conversations API
5. If low confidence: Tag "needs-human-review"
6. If booking_request: Tag "book-now" → triggers the auto-booking workflow from Recipe 2.3!

What You'll Build

Manage OAuth tokens for 100+ sub-accounts with automatic refresh and failure alerting.

Ingredients

• POST /oauth/token — refresh tokens
• POST /oauth/locationToken — generate location tokens

The Recipe

1. Supabase table: ghl_tokens with columns:
   location_id, access_token, refresh_token, expires_at, status
2. n8n Cron every 4 hours: query tokens expiring in 6 hours
3. For each: POST /oauth/token with refresh_token
4. Update Supabase with new tokens and expiry
5. If refresh fails 3x → set status = "failed" → Slack alert

GHL API Helper

const GHL_BASE = 'https://services.leadconnectorhq.com';

async function ghlRequest(
  endpoint: string,
  token: string,
  options: RequestInit = {}
) {
  const response = await fetch(
    `${GHL_BASE}${endpoint}`,
    {
      ...options,
      headers: {
        'Authorization': `Bearer ${token}`,
        'Version': '2021-07-28',
        'Content-Type': 'application/json',
        ...options.headers,
      },
    }
  );

  if (!response.ok) {
    throw new Error(
      `GHL API Error: ${response.status}`
    );
  }

  return response.json();
}

Webhook Handler Pattern

import { createClient } from '@supabase/supabase-js';

Deno.serve(async (req) => {
  const body = await req.json();
  const supabase = createClient(
    Deno.env.get('SUPABASE_URL')!,
    Deno.env.get('SUPABASE_SERVICE_KEY')!
  );

  // 1. Store the event
  await supabase
    .from('ghl_events')
    .insert({ payload: body });

  // 2. Enqueue for processing
  await supabase.rpc('pgmq_send', {
    queue: 'ghl_events',
    message: body
  });

  // 3. Return 200 immediately!
  return new Response(
    JSON.stringify({ status: 'queued' }),
    { status: 200 }
  );
});

What You'll Build

Claude Desktop connected to your live GHL account via MCP (Model Context Protocol).

The Recipe

1. Open Claude Desktop → Settings → Developer → MCP Servers
2. Add the GHL MCP server URL
3. Configure with your Private Integration Token + locationId
4. Test: "Search for contacts created in the last 7 days"
5. Claude calls the MCP tool → returns real contacts from your CRM

Available MCP Tools (21+)

Contacts: search, create, update, delete, add tags, add notes
Calendars: list, get free slots, book appointments
Opportunities: search, create, update, change status
Conversations: search, get messages, send messages
Workflows: list, add contact to workflow

What You'll Build

Claude audits your entire pipeline, flags stale deals, and cross-references with calendar data.

The Prompt

"Search all open opportunities. Flag any that have
been stuck in the same stage for more than 14 days.
For each stale deal, cross-reference with the
calendar — does the contact have an upcoming
appointment? Give me a prioritized action list."

What Claude Does

1. Calls opportunities/search → gets all open deals
2. Analyzes stage timestamps → identifies stale deals (>14 days)
3. For each stale contact: checks calendar for upcoming appointments
4. Generates prioritized recommendations:
   • Urgent: Stale deal, no appointment booked
   • Action needed: Stale deal, appointment next week
   • On track: Appointment tomorrow

What You'll Build

Claude reads and summarizes all recent conversations, giving you a quick status overview.

The Prompt

"Get the last 20 conversations. For each one,
summarize the key points and classify the status
as: active, waiting-for-reply, or closed.
Group them by status and highlight any that
need immediate attention."

What Claude Returns

A structured report grouped by status:

• Needs Attention (3): Unread messages waiting >24 hours
• Waiting for Reply (8): You sent last message, awaiting response
• Active (5): Back-and-forth conversations in progress
• Closed (4): Resolved or no response in 7+ days

What You'll Build

One Edge Function that routes ALL GHL webhook events to the right handler.

The Pattern

// ghl-event-router
const handlers: Record<string, Function> = {
  'InboundMessage':       handleMessage,
  'ContactCreate':        handleNewLead,
  'AppointmentStatus':    handleAppointment,
  'OpportunityStageUpdate': handlePipeline,
};

Deno.serve(async (req) => {
  const body = await req.json();
  const eventType = body.type;

  // Enqueue to pgmq, return 200 immediately
  await supabase.rpc('pgmq_send', {
    queue: eventType,
    message: body
  });

  return new Response('OK', { status: 200 });
});

Calendars

Locations (Sub-Accounts)

OAuth

Rate Limits

• ~100 requests/min per location (not officially documented, observed)
• Implement exponential backoff on 429 responses
• Batch operations: use 700ms delays between requests (~85/min, safe margin)
• If you hit 429: wait 2^attempt seconds before retry (1s, 2s, 4s, 8s...)

Token Best Practices

• Access tokens expire in ~24 hours
• Always store and use refresh_token — it doesn't expire
• Refresh proactively (before expiry), not reactively (after 401)
• For multi-account: build token management (Recipe 5.3)

Webhook Best Practices

• Always return 200 OK from webhook handlers immediately
• Enqueue the event for async processing (pgmq, Redis, SQS)
• Implement idempotency — webhooks can fire multiple times
• Log everything to Supabase for debugging

General Best Practices

• Use upsert over create → avoids duplicates
• Always include error handling in workflows
• Test every API call in the Playground first
• Tag API-created records for tracking
• Never store tokens in code — use env variables or credentials store

Essential Links