# GoHighLevel API V2 Documentation

GoHighLevel (GHL) is a comprehensive all-in-one sales and marketing platform designed for agencies and businesses. The API V2 provides programmatic access to manage contacts, conversations, calendars, opportunities, payments, workflows, and more. The platform uses OAuth 2.0 for authentication with both Agency and Sub-Account (formerly Location) level access, enabling developers to build integrations and marketplace applications that extend the platform's functionality.

The API follows RESTful conventions with a base URL of `https://services.leadconnectorhq.com`. All requests require Bearer token authentication and a Version header specifying the API version (e.g., `2021-07-28`). The platform supports comprehensive webhook events for real-time notifications on contact changes, appointments, opportunities, messages, and invoices, allowing applications to respond to events as they occur within the GHL ecosystem.

---

## OAuth 2.0 Authorization

The OAuth 2.0 flow enables secure access to the GoHighLevel API. After obtaining authorization, use the access token for all API requests. Tokens must be refreshed before expiration.

```bash
# Step 1: Redirect user to authorization URL
# User visits: https://marketplace.gohighlevel.com/oauth/chooselocation
#   ?response_type=code
#   &redirect_uri=https://myapp.com/oauth/callback
#   &client_id=YOUR_CLIENT_ID
#   &scope=contacts.readonly contacts.write conversations.readonly

# Step 2: Exchange authorization code for access token
curl -X POST "https://services.leadconnectorhq.com/oauth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "grant_type=authorization_code" \
  -d "code=AUTHORIZATION_CODE" \
  -d "redirect_uri=https://myapp.com/oauth/callback"

# Response:
# {
#   "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
#   "token_type": "Bearer",
#   "expires_in": 86400,
#   "refresh_token": "refresh_token_value",
#   "scope": "contacts.readonly contacts.write",
#   "locationId": "ve9EPM428h8vShlRW1KT"
# }

# Step 3: Refresh token before expiration
curl -X POST "https://services.leadconnectorhq.com/oauth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "grant_type=refresh_token" \
  -d "refresh_token=YOUR_REFRESH_TOKEN"
```

---

## Contacts API

Manage contacts within a sub-account including creating, updating, searching, and deleting contacts. Contacts are the central entity for CRM functionality, storing customer information, tags, custom fields, and communication history.

```bash
# Create a new contact
curl -X POST "https://services.leadconnectorhq.com/contacts/" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Version: 2021-07-28" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "John",
    "lastName": "Doe",
    "email": "john.doe@example.com",
    "phone": "+14155551234",
    "locationId": "ve9EPM428h8vShlRW1KT",
    "address1": "123 Main Street",
    "city": "San Francisco",
    "state": "CA",
    "postalCode": "94102",
    "country": "US",
    "source": "API",
    "tags": ["lead", "website"],
    "customFields": [
      {
        "id": "BcdmQEsNgz6AVpgLVUJ0",
        "value": "Enterprise"
      }
    ]
  }'

# Response:
# {
#   "contact": {
#     "id": "nmFmQEsNgz6AVpgLVUJ0",
#     "locationId": "ve9EPM428h8vShlRW1KT",
#     "firstName": "John",
#     "lastName": "Doe",
#     "email": "john.doe@example.com",
#     "phone": "+14155551234",
#     "dateAdded": "2024-01-15T10:30:00.000Z"
#   }
# }

# Get contact by ID
curl -X GET "https://services.leadconnectorhq.com/contacts/nmFmQEsNgz6AVpgLVUJ0" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Version: 2021-07-28"

# Search contacts with filters
curl -X GET "https://services.leadconnectorhq.com/contacts/?locationId=ve9EPM428h8vShlRW1KT&query=john&limit=20" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Version: 2021-07-28"

# Update contact
curl -X PUT "https://services.leadconnectorhq.com/contacts/nmFmQEsNgz6AVpgLVUJ0" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Version: 2021-07-28" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "John",
    "lastName": "Smith",
    "tags": ["customer", "premium"]
  }'

# Add tags to contact
curl -X POST "https://services.leadconnectorhq.com/contacts/nmFmQEsNgz6AVpgLVUJ0/tags" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Version: 2021-07-28" \
  -H "Content-Type: application/json" \
  -d '{"tags": ["vip", "referral"]}'

# Delete contact
curl -X DELETE "https://services.leadconnectorhq.com/contacts/nmFmQEsNgz6AVpgLVUJ0" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Version: 2021-07-28"
```

---

## Contact Tasks API

Create and manage tasks associated with contacts. Tasks help track follow-ups, reminders, and action items for each contact.

```bash
# Create a task for a contact
curl -X POST "https://services.leadconnectorhq.com/contacts/nmFmQEsNgz6AVpgLVUJ0/tasks" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Version: 2021-07-28" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Follow up on proposal",
    "body": "Call to discuss the proposal sent last week",
    "dueDate": "2024-01-20T14:00:00.000Z",
    "completed": false,
    "assignedTo": "user_id_here"
  }'

# Get all tasks for a contact
curl -X GET "https://services.leadconnectorhq.com/contacts/nmFmQEsNgz6AVpgLVUJ0/tasks" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Version: 2021-07-28"

# Mark task as completed
curl -X PUT "https://services.leadconnectorhq.com/contacts/nmFmQEsNgz6AVpgLVUJ0/tasks/task123/completed" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Version: 2021-07-28" \
  -H "Content-Type: application/json" \
  -d '{"completed": true}'
```

---

## Contact Notes API

Add and manage notes on contacts to track important information and interaction history.

```bash
# Create a note for a contact
curl -X POST "https://services.leadconnectorhq.com/contacts/nmFmQEsNgz6AVpgLVUJ0/notes" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Version: 2021-07-28" \
  -H "Content-Type: application/json" \
  -d '{
    "body": "Customer interested in premium package. Schedule demo for next week."
  }'

# Get all notes for a contact
curl -X GET "https://services.leadconnectorhq.com/contacts/nmFmQEsNgz6AVpgLVUJ0/notes" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Version: 2021-07-28"

# Update a note
curl -X PUT "https://services.leadconnectorhq.com/contacts/nmFmQEsNgz6AVpgLVUJ0/notes/note456" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Version: 2021-07-28" \
  -H "Content-Type: application/json" \
  -d '{"body": "Updated note content with additional details"}'

# Delete a note
curl -X DELETE "https://services.leadconnectorhq.com/contacts/nmFmQEsNgz6AVpgLVUJ0/notes/note456" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Version: 2021-07-28"
```

---

## Conversations API

Manage conversations and messaging across multiple channels including SMS, Email, WhatsApp, Facebook, Instagram, and more. Conversations provide a unified inbox for all customer communications.

```bash
# Search conversations
curl -X GET "https://services.leadconnectorhq.com/conversations/search?locationId=ve9EPM428h8vShlRW1KT&status=unread&limit=20&sort=desc" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Version: 2021-04-15"

# Response:
# {
#   "conversations": [
#     {
#       "id": "tDtDnQdgm2LXpyiqYvZ6",
#       "contactId": "nmFmQEsNgz6AVpgLVUJ0",
#       "locationId": "ve9EPM428h8vShlRW1KT",
#       "lastMessageBody": "Thanks for your help!",
#       "lastMessageType": "TYPE_SMS",
#       "lastMessageDirection": "inbound",
#       "lastMessageDate": "2024-01-15T10:30:00.000Z",
#       "unreadCount": 2
#     }
#   ]
# }

# Get conversation by ID
curl -X GET "https://services.leadconnectorhq.com/conversations/tDtDnQdgm2LXpyiqYvZ6" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Version: 2021-04-15"

# Update conversation (mark as read, star, assign)
curl -X PUT "https://services.leadconnectorhq.com/conversations/tDtDnQdgm2LXpyiqYvZ6" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Version: 2021-04-15" \
  -H "Content-Type: application/json" \
  -d '{
    "unreadCount": 0,
    "starred": true,
    "assignedTo": "user123"
  }'

# Send SMS message
curl -X POST "https://services.leadconnectorhq.com/conversations/messages" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Version: 2021-04-15" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "SMS",
    "contactId": "nmFmQEsNgz6AVpgLVUJ0",
    "message": "Hi John, just following up on our conversation. Let me know if you have any questions!"
  }'

# Send Email message
curl -X POST "https://services.leadconnectorhq.com/conversations/messages" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Version: 2021-04-15" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "Email",
    "contactId": "nmFmQEsNgz6AVpgLVUJ0",
    "subject": "Follow-up on Your Inquiry",
    "message": "<html><body><p>Dear John,</p><p>Thank you for your interest...</p></body></html>",
    "emailFrom": "sales@company.com"
  }'

# Add inbound message (for custom providers)
curl -X POST "https://services.leadconnectorhq.com/conversations/messages/inbound" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Version: 2021-04-15" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "SMS",
    "locationId": "ve9EPM428h8vShlRW1KT",
    "contactId": "nmFmQEsNgz6AVpgLVUJ0",
    "message": "Customer reply message content"
  }'
```

---

## Calendars API

Manage calendars, appointments, and availability for scheduling. Supports creating calendar resources, booking appointments, and managing blocked time slots.

```bash
# Get all calendars for a location
curl -X GET "https://services.leadconnectorhq.com/calendars/?locationId=ve9EPM428h8vShlRW1KT" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Version: 2021-04-15"

# Response:
# {
#   "calendars": [
#     {
#       "id": "calendar123",
#       "name": "Sales Consultations",
#       "locationId": "ve9EPM428h8vShlRW1KT",
#       "teamMembers": [{"userId": "user1", "priority": 1}],
#       "eventType": "RoundRobin_OptimizeForAvailability"
#     }
#   ]
# }

# Create a new calendar
curl -X POST "https://services.leadconnectorhq.com/calendars/" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Version: 2021-04-15" \
  -H "Content-Type: application/json" \
  -d '{
    "locationId": "ve9EPM428h8vShlRW1KT",
    "name": "Product Demo",
    "description": "30-minute product demonstration",
    "slug": "product-demo",
    "widgetSlug": "product-demo",
    "calendarType": "round_robin",
    "widgetType": "default",
    "eventTitle": "Product Demo with {{contact.name}}",
    "eventColor": "#2196F3",
    "slotDuration": 30,
    "slotInterval": 30,
    "slotBuffer": 0,
    "preBuffer": 0,
    "appoinmentPerSlot": 1,
    "appoinmentPerDay": 10,
    "openHours": [
      {
        "daysOfTheWeek": [1, 2, 3, 4, 5],
        "hours": [{"openHour": 9, "openMinute": 0, "closeHour": 17, "closeMinute": 0}]
      }
    ],
    "teamMembers": [{"userId": "user123", "priority": 1}]
  }'

# Get free slots for a calendar
curl -X GET "https://services.leadconnectorhq.com/calendars/calendar123/free-slots?startDate=2024-01-20&endDate=2024-01-27&timezone=America/New_York" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Version: 2021-04-15"

# Create an appointment
curl -X POST "https://services.leadconnectorhq.com/calendars/events/appointments" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Version: 2021-04-15" \
  -H "Content-Type: application/json" \
  -d '{
    "calendarId": "calendar123",
    "locationId": "ve9EPM428h8vShlRW1KT",
    "contactId": "nmFmQEsNgz6AVpgLVUJ0",
    "startTime": "2024-01-22T10:00:00-05:00",
    "endTime": "2024-01-22T10:30:00-05:00",
    "title": "Product Demo with John Doe",
    "appointmentStatus": "confirmed",
    "assignedUserId": "user123",
    "notes": "Customer interested in enterprise plan"
  }'

# Update appointment
curl -X PUT "https://services.leadconnectorhq.com/calendars/events/appointments/event456" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Version: 2021-04-15" \
  -H "Content-Type: application/json" \
  -d '{
    "startTime": "2024-01-22T14:00:00-05:00",
    "endTime": "2024-01-22T14:30:00-05:00",
    "appointmentStatus": "confirmed"
  }'

# Create a blocked slot
curl -X POST "https://services.leadconnectorhq.com/calendars/events/block-slots" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Version: 2021-04-15" \
  -H "Content-Type: application/json" \
  -d '{
    "calendarId": "calendar123",
    "locationId": "ve9EPM428h8vShlRW1KT",
    "startTime": "2024-01-25T12:00:00-05:00",
    "endTime": "2024-01-25T13:00:00-05:00",
    "title": "Lunch Break",
    "assignedUserId": "user123"
  }'
```

---

## Opportunities API

Manage sales opportunities within pipelines. Track deals through stages, monitor monetary values, and manage the sales process.

```bash
# Search opportunities
curl -X GET "https://services.leadconnectorhq.com/opportunities/search?location_id=ve9EPM428h8vShlRW1KT&status=open&limit=20" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Version: 2021-07-28"

# Response:
# {
#   "opportunities": [
#     {
#       "id": "opp123",
#       "name": "Enterprise Deal - Acme Corp",
#       "monetaryValue": 50000,
#       "pipelineId": "pipeline1",
#       "pipelineStageId": "stage2",
#       "status": "open",
#       "contactId": "nmFmQEsNgz6AVpgLVUJ0",
#       "assignedTo": "user123"
#     }
#   ],
#   "meta": {"total": 45, "currentPage": 1}
# }

# Get pipelines
curl -X GET "https://services.leadconnectorhq.com/opportunities/pipelines?locationId=ve9EPM428h8vShlRW1KT" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Version: 2021-07-28"

# Create opportunity
curl -X POST "https://services.leadconnectorhq.com/opportunities/" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Version: 2021-07-28" \
  -H "Content-Type: application/json" \
  -d '{
    "pipelineId": "bCkKGpDsyPP4peuKowkG",
    "locationId": "ve9EPM428h8vShlRW1KT",
    "name": "New Enterprise Deal",
    "pipelineStageId": "7915dedc-8f18-44d5-8bc3-77c04e994a10",
    "status": "open",
    "contactId": "nmFmQEsNgz6AVpgLVUJ0",
    "monetaryValue": 25000,
    "assignedTo": "user123",
    "source": "Website Form"
  }'

# Update opportunity
curl -X PUT "https://services.leadconnectorhq.com/opportunities/opp123" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Version: 2021-07-28" \
  -H "Content-Type: application/json" \
  -d '{
    "monetaryValue": 35000,
    "pipelineStageId": "stage3",
    "name": "Updated Deal Name"
  }'

# Update opportunity status
curl -X PUT "https://services.leadconnectorhq.com/opportunities/opp123/status" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Version: 2021-07-28" \
  -H "Content-Type: application/json" \
  -d '{"status": "won"}'

# Delete opportunity
curl -X DELETE "https://services.leadconnectorhq.com/opportunities/opp123" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Version: 2021-07-28"
```

---

## Locations (Sub-Accounts) API

Manage sub-accounts (locations) within an agency. Locations represent individual businesses or clients within the GHL platform.

```bash
# Get location by ID
curl -X GET "https://services.leadconnectorhq.com/locations/ve9EPM428h8vShlRW1KT" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Version: 2021-07-28"

# Response:
# {
#   "location": {
#     "id": "ve9EPM428h8vShlRW1KT",
#     "companyId": "5DP4iH6HLkQsiKESj6rh",
#     "name": "Acme Marketing Agency",
#     "address": "123 Business Ave",
#     "city": "New York",
#     "state": "NY",
#     "country": "US",
#     "postalCode": "10001",
#     "website": "https://acme.com",
#     "timezone": "America/New_York",
#     "email": "contact@acme.com",
#     "phone": "+12125551234"
#   }
# }

# Search locations (Agency level)
curl -X GET "https://services.leadconnectorhq.com/locations/search?companyId=5DP4iH6HLkQsiKESj6rh&limit=50" \
  -H "Authorization: Bearer YOUR_AGENCY_ACCESS_TOKEN" \
  -H "Version: 2021-07-28"

# Create a new location (Agency level)
curl -X POST "https://services.leadconnectorhq.com/locations/" \
  -H "Authorization: Bearer YOUR_AGENCY_ACCESS_TOKEN" \
  -H "Version: 2021-07-28" \
  -H "Content-Type: application/json" \
  -d '{
    "companyId": "5DP4iH6HLkQsiKESj6rh",
    "name": "New Client Business",
    "address": "456 Client Street",
    "city": "Los Angeles",
    "state": "CA",
    "country": "US",
    "postalCode": "90001",
    "timezone": "America/Los_Angeles",
    "email": "info@newclient.com",
    "phone": "+13105551234"
  }'

# Update location
curl -X PUT "https://services.leadconnectorhq.com/locations/ve9EPM428h8vShlRW1KT" \
  -H "Authorization: Bearer YOUR_AGENCY_ACCESS_TOKEN" \
  -H "Version: 2021-07-28" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Business Name",
    "website": "https://updated-website.com"
  }'

# Get available timezones
curl -X GET "https://services.leadconnectorhq.com/locations/timezones" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Version: 2021-07-28"
```

---

## Custom Fields API

Manage custom fields for contacts to store additional business-specific data.

```bash
# Get custom fields for a location
curl -X GET "https://services.leadconnectorhq.com/locations/ve9EPM428h8vShlRW1KT/customFields" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Version: 2021-07-28"

# Create a custom field
curl -X POST "https://services.leadconnectorhq.com/locations/ve9EPM428h8vShlRW1KT/customFields" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Version: 2021-07-28" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Company Size",
    "dataType": "TEXT",
    "placeholder": "Enter company size",
    "position": 0
  }'

# Update custom field
curl -X PUT "https://services.leadconnectorhq.com/locations/ve9EPM428h8vShlRW1KT/customFields/field123" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Version: 2021-07-28" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Organization Size",
    "placeholder": "e.g., 1-50 employees"
  }'

# Delete custom field
curl -X DELETE "https://services.leadconnectorhq.com/locations/ve9EPM428h8vShlRW1KT/customFields/field123" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Version: 2021-07-28"
```

---

## Custom Values API

Manage custom values (location-level variables) that can be used in templates and automations.

```bash
# Get custom values for a location
curl -X GET "https://services.leadconnectorhq.com/locations/ve9EPM428h8vShlRW1KT/customValues" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Version: 2021-07-28"

# Create a custom value
curl -X POST "https://services.leadconnectorhq.com/locations/ve9EPM428h8vShlRW1KT/customValues" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Version: 2021-07-28" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "business_hours",
    "value": "Monday-Friday 9AM-5PM EST"
  }'

# Update custom value
curl -X PUT "https://services.leadconnectorhq.com/locations/ve9EPM428h8vShlRW1KT/customValues/value123" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Version: 2021-07-28" \
  -H "Content-Type: application/json" \
  -d '{"value": "Monday-Friday 8AM-6PM EST"}'
```

---

## Users API

Manage users within agencies and sub-accounts. Users can have different roles and permissions.

```bash
# Search users
curl -X GET "https://services.leadconnectorhq.com/users/search?companyId=5DP4iH6HLkQsiKESj6rh&limit=25" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Version: 2021-07-28"

# Get user by ID
curl -X GET "https://services.leadconnectorhq.com/users/user123" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Version: 2021-07-28"

# Response:
# {
#   "user": {
#     "id": "user123",
#     "name": "Jane Smith",
#     "firstName": "Jane",
#     "lastName": "Smith",
#     "email": "jane@agency.com",
#     "phone": "+15551234567",
#     "type": "account",
#     "role": "admin",
#     "locationIds": ["ve9EPM428h8vShlRW1KT"]
#   }
# }

# Create a new user
curl -X POST "https://services.leadconnectorhq.com/users/" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Version: 2021-07-28" \
  -H "Content-Type: application/json" \
  -d '{
    "companyId": "5DP4iH6HLkQsiKESj6rh",
    "firstName": "New",
    "lastName": "User",
    "email": "newuser@agency.com",
    "phone": "+15559876543",
    "type": "account",
    "role": "user",
    "locationIds": ["ve9EPM428h8vShlRW1KT"],
    "permissions": {
      "campaignsEnabled": true,
      "contactsEnabled": true,
      "workflowsEnabled": true
    }
  }'

# Update user
curl -X PUT "https://services.leadconnectorhq.com/users/user123" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Version: 2021-07-28" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Jane",
    "lastName": "Doe",
    "role": "admin"
  }'

# Delete user
curl -X DELETE "https://services.leadconnectorhq.com/users/user123" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Version: 2021-07-28"
```

---

## Workflows API

Access and manage workflows (automations) within a sub-account. Workflows automate actions based on triggers.

```bash
# Get all workflows for a location
curl -X GET "https://services.leadconnectorhq.com/workflows/?locationId=ve9EPM428h8vShlRW1KT" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Version: 2021-07-28"

# Response:
# {
#   "workflows": [
#     {
#       "id": "78559bb3-b920-461e-b010-7b2a2816d2a9",
#       "name": "New Lead Follow-up",
#       "status": "published",
#       "version": 2,
#       "createdAt": "2024-01-01T00:00:00.000Z",
#       "updatedAt": "2024-01-10T00:00:00.000Z",
#       "locationId": "ve9EPM428h8vShlRW1KT"
#     }
#   ]
# }

# Add contact to workflow
curl -X POST "https://services.leadconnectorhq.com/contacts/nmFmQEsNgz6AVpgLVUJ0/workflow/78559bb3-b920-461e-b010-7b2a2816d2a9" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Version: 2021-07-28"

# Remove contact from workflow
curl -X DELETE "https://services.leadconnectorhq.com/contacts/nmFmQEsNgz6AVpgLVUJ0/workflow/78559bb3-b920-461e-b010-7b2a2816d2a9" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Version: 2021-07-28"
```

---

## Campaigns API

Access marketing campaigns within a sub-account. Add or remove contacts from campaigns.

```bash
# Get all campaigns
curl -X GET "https://services.leadconnectorhq.com/campaigns/?locationId=ve9EPM428h8vShlRW1KT" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Version: 2021-07-28"

# Add contact to campaign
curl -X POST "https://services.leadconnectorhq.com/contacts/nmFmQEsNgz6AVpgLVUJ0/campaigns/campaign123" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Version: 2021-07-28"

# Remove contact from specific campaign
curl -X DELETE "https://services.leadconnectorhq.com/contacts/nmFmQEsNgz6AVpgLVUJ0/campaigns/campaign123" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Version: 2021-07-28"

# Remove contact from all campaigns
curl -X DELETE "https://services.leadconnectorhq.com/contacts/nmFmQEsNgz6AVpgLVUJ0/campaigns/removeAll" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Version: 2021-07-28"
```

---

## Forms API

Access forms and form submissions. Retrieve form data and upload files to custom fields.

```bash
# Get all forms for a location
curl -X GET "https://services.leadconnectorhq.com/forms/?locationId=ve9EPM428h8vShlRW1KT&limit=20" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Version: 2021-07-28"

# Get form submissions
curl -X GET "https://services.leadconnectorhq.com/forms/submissions?locationId=ve9EPM428h8vShlRW1KT&formId=form123&startAt=2024-01-01&endAt=2024-01-31&limit=50" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Version: 2021-07-28"

# Response:
# {
#   "submissions": [
#     {
#       "id": "sub123",
#       "contactId": "nmFmQEsNgz6AVpgLVUJ0",
#       "createdAt": "2024-01-15T10:30:00.000Z",
#       "formId": "form123",
#       "name": "John Doe",
#       "email": "john@example.com"
#     }
#   ],
#   "meta": {"total": 150, "currentPage": 1}
# }

# Upload files to custom fields (multipart form)
curl -X POST "https://services.leadconnectorhq.com/forms/upload-custom-files?contactId=nmFmQEsNgz6AVpgLVUJ0&locationId=ve9EPM428h8vShlRW1KT" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Version: 2021-07-28" \
  -F "field123_file1=@/path/to/document.pdf"
```

---

## Surveys API

Access surveys and survey submissions for collecting customer feedback.

```bash
# Get all surveys
curl -X GET "https://services.leadconnectorhq.com/surveys/?locationId=ve9EPM428h8vShlRW1KT" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Version: 2021-07-28"

# Get survey submissions
curl -X GET "https://services.leadconnectorhq.com/surveys/submissions?locationId=ve9EPM428h8vShlRW1KT&surveyId=survey123&page=1&limit=50" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Version: 2021-07-28"
```

---

## Invoices API

Create and manage invoices for billing customers. Supports invoice templates, scheduling, and payment tracking.

```bash
# List invoices
curl -X GET "https://services.leadconnectorhq.com/invoices/?altId=ve9EPM428h8vShlRW1KT&altType=location&limit=20&offset=0" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Version: 2021-07-28"

# Create an invoice
curl -X POST "https://services.leadconnectorhq.com/invoices/" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Version: 2021-07-28" \
  -H "Content-Type: application/json" \
  -d '{
    "altId": "ve9EPM428h8vShlRW1KT",
    "altType": "location",
    "name": "Monthly Services",
    "contactId": "nmFmQEsNgz6AVpgLVUJ0",
    "issueDate": "2024-01-15",
    "dueDate": "2024-02-15",
    "items": [
      {
        "name": "Marketing Services",
        "description": "January 2024",
        "quantity": 1,
        "unitPrice": 1500,
        "currency": "USD"
      }
    ],
    "discount": {"value": 10, "type": "percentage"},
    "currency": "USD"
  }'

# Get invoice by ID
curl -X GET "https://services.leadconnectorhq.com/invoices/inv123?altId=ve9EPM428h8vShlRW1KT&altType=location" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Version: 2021-07-28"

# Send invoice to customer
curl -X POST "https://services.leadconnectorhq.com/invoices/inv123/send" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Version: 2021-07-28" \
  -H "Content-Type: application/json" \
  -d '{"altId": "ve9EPM428h8vShlRW1KT", "altType": "location"}'

# Record a payment
curl -X POST "https://services.leadconnectorhq.com/invoices/inv123/record-payment" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Version: 2021-07-28" \
  -H "Content-Type: application/json" \
  -d '{
    "altId": "ve9EPM428h8vShlRW1KT",
    "altType": "location",
    "amount": 1350,
    "mode": "cash",
    "notes": "Payment received via check"
  }'

# Void an invoice
curl -X POST "https://services.leadconnectorhq.com/invoices/inv123/void" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Version: 2021-07-28" \
  -H "Content-Type: application/json" \
  -d '{"altId": "ve9EPM428h8vShlRW1KT", "altType": "location"}'
```

---

## Payments API

Access payment orders, transactions, and subscriptions. Manage payment integrations and fulfillments.

```bash
# List orders
curl -X GET "https://services.leadconnectorhq.com/payments/orders?altId=ve9EPM428h8vShlRW1KT&altType=location&status=completed&limit=20" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Version: 2021-07-28"

# Get order by ID
curl -X GET "https://services.leadconnectorhq.com/payments/orders/order123?altId=ve9EPM428h8vShlRW1KT&altType=location" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Version: 2021-07-28"

# List transactions
curl -X GET "https://services.leadconnectorhq.com/payments/transactions?altId=ve9EPM428h8vShlRW1KT&altType=location&limit=20" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Version: 2021-07-28"

# Get transaction details
curl -X GET "https://services.leadconnectorhq.com/payments/transactions/txn123?altId=ve9EPM428h8vShlRW1KT&altType=location" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Version: 2021-07-28"

# List subscriptions
curl -X GET "https://services.leadconnectorhq.com/payments/subscriptions?altId=ve9EPM428h8vShlRW1KT&altType=location" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Version: 2021-07-28"

# Create order fulfillment
curl -X POST "https://services.leadconnectorhq.com/payments/orders/order123/fulfillments" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Version: 2021-07-28" \
  -H "Content-Type: application/json" \
  -d '{
    "altId": "ve9EPM428h8vShlRW1KT",
    "altType": "location",
    "trackingNumber": "1Z999AA10123456784",
    "trackingUrl": "https://tracking.example.com/1Z999AA10123456784",
    "carrier": "UPS"
  }'
```

---

## Products API

Manage products and pricing for e-commerce functionality.

```bash
# List products
curl -X GET "https://services.leadconnectorhq.com/products/?locationId=ve9EPM428h8vShlRW1KT" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Version: 2021-07-28"

# Create a product
curl -X POST "https://services.leadconnectorhq.com/products/" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Version: 2021-07-28" \
  -H "Content-Type: application/json" \
  -d '{
    "locationId": "ve9EPM428h8vShlRW1KT",
    "name": "Premium Consulting Package",
    "description": "10 hours of consulting services",
    "productType": "SERVICE"
  }'

# Get product by ID
curl -X GET "https://services.leadconnectorhq.com/products/prod123" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Version: 2021-07-28"

# Create a price for product
curl -X POST "https://services.leadconnectorhq.com/products/prod123/price/" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Version: 2021-07-28" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Standard Rate",
    "amount": 150000,
    "currency": "USD",
    "type": "one_time"
  }'

# Update product
curl -X PUT "https://services.leadconnectorhq.com/products/prod123" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Version: 2021-07-28" \
  -H "Content-Type: application/json" \
  -d '{"name": "Updated Product Name", "description": "Updated description"}'

# Delete product
curl -X DELETE "https://services.leadconnectorhq.com/products/prod123" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Version: 2021-07-28"
```

---

## Location Tags API

Manage tags at the location level for organizing and categorizing contacts.

```bash
# Get all tags for a location
curl -X GET "https://services.leadconnectorhq.com/locations/ve9EPM428h8vShlRW1KT/tags" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Version: 2021-07-28"

# Create a new tag
curl -X POST "https://services.leadconnectorhq.com/locations/ve9EPM428h8vShlRW1KT/tags/" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Version: 2021-07-28" \
  -H "Content-Type: application/json" \
  -d '{"name": "VIP Customer"}'

# Update a tag
curl -X PUT "https://services.leadconnectorhq.com/locations/ve9EPM428h8vShlRW1KT/tags/tag123" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Version: 2021-07-28" \
  -H "Content-Type: application/json" \
  -d '{"name": "Premium Customer"}'

# Delete a tag
curl -X DELETE "https://services.leadconnectorhq.com/locations/ve9EPM428h8vShlRW1KT/tags/tag123" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Version: 2021-07-28"
```

---

## Media Library API

Upload and manage media files for use across the platform.

```bash
# List media files
curl -X GET "https://services.leadconnectorhq.com/medias/files?altId=ve9EPM428h8vShlRW1KT&altType=location&limit=50" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Version: 2021-07-28"

# Upload a file
curl -X POST "https://services.leadconnectorhq.com/medias/upload-file" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Version: 2021-07-28" \
  -F "file=@/path/to/image.jpg" \
  -F "altId=ve9EPM428h8vShlRW1KT" \
  -F "altType=location"

# Delete a file
curl -X DELETE "https://services.leadconnectorhq.com/medias/file123" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Version: 2021-07-28"
```

---

## Funnels API

Access funnels and landing pages. Manage redirects and page counts.

```bash
# List funnels
curl -X GET "https://services.leadconnectorhq.com/funnels/funnel/list?locationId=ve9EPM428h8vShlRW1KT" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Version: 2021-07-28"

# Get funnel pages
curl -X GET "https://services.leadconnectorhq.com/funnels/page?locationId=ve9EPM428h8vShlRW1KT&funnelId=funnel123&limit=50" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Version: 2021-07-28"

# Get page count
curl -X GET "https://services.leadconnectorhq.com/funnels/page/count?locationId=ve9EPM428h8vShlRW1KT&funnelId=funnel123" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Version: 2021-07-28"

# Create a redirect
curl -X POST "https://services.leadconnectorhq.com/funnels/lookup/redirect" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Version: 2021-07-28" \
  -H "Content-Type: application/json" \
  -d '{
    "locationId": "ve9EPM428h8vShlRW1KT",
    "domain": "example.com",
    "path": "/old-page",
    "target": "https://example.com/new-page",
    "action": "redirect"
  }'
```

---

## Social Media Posting API

Manage social media accounts and schedule posts across multiple platforms.

```bash
# Get connected social media accounts
curl -X GET "https://services.leadconnectorhq.com/social-media-posting/ve9EPM428h8vShlRW1KT/accounts" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Version: 2021-07-28"

# List posts
curl -X POST "https://services.leadconnectorhq.com/social-media-posting/ve9EPM428h8vShlRW1KT/posts/list" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Version: 2021-07-28" \
  -H "Content-Type: application/json" \
  -d '{"skip": 0, "limit": 20}'

# Create a social media post
curl -X POST "https://services.leadconnectorhq.com/social-media-posting/ve9EPM428h8vShlRW1KT/posts" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Version: 2021-07-28" \
  -H "Content-Type: application/json" \
  -d '{
    "accountIds": ["account1", "account2"],
    "content": "Check out our latest blog post! #marketing #business",
    "mediaUrls": ["https://example.com/image.jpg"],
    "scheduleTime": "2024-01-20T10:00:00.000Z"
  }'

# Update a post
curl -X PUT "https://services.leadconnectorhq.com/social-media-posting/ve9EPM428h8vShlRW1KT/posts/post123" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Version: 2021-07-28" \
  -H "Content-Type: application/json" \
  -d '{"content": "Updated post content #updated"}'

# Delete a post
curl -X DELETE "https://services.leadconnectorhq.com/social-media-posting/ve9EPM428h8vShlRW1KT/posts/post123" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Version: 2021-07-28"
```

---

## Webhook Events

Subscribe to webhook events to receive real-time notifications when data changes. Register webhooks through the marketplace app configuration.

```json
// ContactCreate webhook payload
{
  "type": "ContactCreate",
  "locationId": "ve9EPM428h8vShlRW1KT",
  "id": "nmFmQEsNgz6AVpgLVUJ0",
  "firstName": "John",
  "lastName": "Doe",
  "email": "john.doe@example.com",
  "phone": "+14155551234",
  "tags": ["lead", "website"],
  "dateAdded": "2024-01-15T10:30:00.000Z",
  "customFields": [
    {"id": "BcdmQEsNgz6AVpgLVUJ0", "value": "Enterprise"}
  ]
}

// OpportunityCreate webhook payload
{
  "type": "OpportunityCreate",
  "locationId": "ve9EPM428h8vShlRW1KT",
  "id": "opp123",
  "name": "New Deal",
  "monetaryValue": 25000,
  "pipelineId": "pipeline1",
  "pipelineStageId": "stage1",
  "status": "open",
  "contactId": "nmFmQEsNgz6AVpgLVUJ0"
}

// AppointmentCreate webhook payload
{
  "type": "AppointmentCreate",
  "locationId": "ve9EPM428h8vShlRW1KT",
  "id": "apt123",
  "calendarId": "calendar123",
  "contactId": "nmFmQEsNgz6AVpgLVUJ0",
  "title": "Sales Meeting",
  "startTime": "2024-01-20T10:00:00.000Z",
  "endTime": "2024-01-20T11:00:00.000Z",
  "status": "confirmed"
}

// InboundMessage webhook payload
{
  "type": "InboundMessage",
  "locationId": "ve9EPM428h8vShlRW1KT",
  "contactId": "nmFmQEsNgz6AVpgLVUJ0",
  "conversationId": "conv123",
  "messageType": "SMS",
  "body": "Yes, I'm interested in learning more!",
  "dateAdded": "2024-01-15T10:30:00.000Z"
}
```

---

## Webhook Signature Verification

Verify webhook authenticity by validating the X-GHL-Signature header using HMAC-SHA256.

```javascript
const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secretKey) {
  const expectedSignature = crypto
    .createHmac('sha256', secretKey)
    .update(JSON.stringify(payload))
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

// Express.js webhook handler
app.post('/webhook', express.json(), (req, res) => {
  const signature = req.headers['x-ghl-signature'];
  const payload = req.body;

  if (!verifyWebhookSignature(payload, signature, process.env.GHL_WEBHOOK_SECRET)) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  // Process webhook
  switch (payload.type) {
    case 'ContactCreate':
      handleContactCreate(payload);
      break;
    case 'OpportunityCreate':
      handleOpportunityCreate(payload);
      break;
    case 'InboundMessage':
      handleInboundMessage(payload);
      break;
  }

  res.status(200).json({ received: true });
});
```

---

## Error Handling

All API endpoints return standard HTTP status codes. Handle errors appropriately in your integration.

```bash
# Common error responses:

# 400 Bad Request - Invalid parameters
# {
#   "statusCode": 400,
#   "message": "Validation failed",
#   "error": "Bad Request"
# }

# 401 Unauthorized - Invalid or expired token
# {
#   "statusCode": 401,
#   "message": "Unauthorized",
#   "error": "Unauthorized"
# }

# 422 Unprocessable Entity - Business logic error
# {
#   "statusCode": 422,
#   "message": "Contact with this email already exists",
#   "error": "Unprocessable Entity"
# }

# 429 Rate Limited - Too many requests
# {
#   "statusCode": 429,
#   "message": "Rate limit exceeded",
#   "error": "Too Many Requests"
# }
```

```javascript
// JavaScript error handling example
async function makeApiRequest(endpoint, options) {
  try {
    const response = await fetch(`https://services.leadconnectorhq.com${endpoint}`, {
      ...options,
      headers: {
        'Authorization': `Bearer ${accessToken}`,
        'Version': '2021-07-28',
        'Content-Type': 'application/json',
        ...options.headers
      }
    });

    if (!response.ok) {
      const error = await response.json();

      if (response.status === 401) {
        // Token expired, refresh and retry
        await refreshAccessToken();
        return makeApiRequest(endpoint, options);
      }

      if (response.status === 429) {
        // Rate limited, wait and retry
        const retryAfter = response.headers.get('Retry-After') || 60;
        await sleep(retryAfter * 1000);
        return makeApiRequest(endpoint, options);
      }

      throw new Error(`API Error: ${error.message}`);
    }

    return response.json();
  } catch (error) {
    console.error('Request failed:', error);
    throw error;
  }
}
```

---

## Summary

The GoHighLevel API V2 provides a comprehensive solution for building integrations with the GHL platform. It enables developers to automate CRM workflows, manage multi-channel communications, handle scheduling and appointments, track sales opportunities through pipelines, process payments and invoices, and build custom marketplace applications. The OAuth 2.0 authentication system supports both Agency-level and Sub-Account-level access, allowing for flexible permission management.

Common integration patterns include syncing contacts between external systems and GHL, building custom conversation providers for alternative messaging channels (SMS, Email, Call), automating lead routing and follow-up sequences, creating dashboards with opportunity and pipeline analytics, processing form submissions and survey responses, and managing appointments across multiple calendars. The webhook system enables real-time event-driven architectures, while the extensive scope system ensures applications only access the data they need. For marketplace applications, developers can create white-label integrations that extend GHL's functionality while maintaining security and data isolation between sub-accounts.