# GoHighLevel API V2 Documentation

## Introduction

GoHighLevel API V2 is a comprehensive RESTful API platform designed to integrate third-party applications with the HighLevel CRM and marketing automation platform. The API provides programmatic access to manage contacts, conversations, calendars, opportunities, payments, campaigns, and numerous other resources within the GoHighLevel ecosystem. Built on OAuth 2.0 authentication, it enables developers to create marketplace applications that can be installed across multiple sub-accounts (locations) and agencies, with granular permission controls through a robust scopes system.

The API follows modern REST conventions with JSON request/response formats and standard HTTP methods (GET, POST, PUT, DELETE). It includes webhook support for real-time event notifications, rate limiting to ensure platform stability (100 requests per 10 seconds burst, 200,000 daily per location), and comprehensive error handling. All endpoints are hosted at `https://services.leadconnectorhq.com` and require API version headers for versioning control. The platform supports both agency-level and sub-account-level access tokens, enabling flexible integration patterns for SaaS providers, marketing agencies, and custom application developers.

## OAuth 2.0 Authentication

### Authorization Code Flow

Obtain access tokens using the OAuth 2.0 authorization code grant flow to authenticate API requests.

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

# Step 2: User authorizes and gets redirected back with code
# https://myapp.com/oauth/callback/gohighlevel?code=7676cjcbdc6t76cdcbkjcd09821jknnkj

# Step 3: 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=7676cjcbdc6t76cdcbkjcd09821jknnkj" \
  -d "redirect_uri=https://myapp.com/oauth/callback/gohighlevel"

# Response:
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 86400,
  "refresh_token": "def50200a1b2c3d4e5f6...",
  "scope": "contacts.readonly contacts.write opportunities.readonly",
  "userType": "Location",
  "locationId": "ve9EPM428h8vShlRW1KT"
}
```

### Refresh Access Token

Refresh expired access tokens to maintain continuous API access without re-authorization.

```bash
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=def50200a1b2c3d4e5f6..."

# Response:
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.NEW_TOKEN...",
  "token_type": "Bearer",
  "expires_in": 86400,
  "refresh_token": "def50200NEW_REFRESH_TOKEN...",
  "scope": "contacts.readonly contacts.write opportunities.readonly",
  "userType": "Location",
  "locationId": "ve9EPM428h8vShlRW1KT"
}

# Note: Access tokens expire after 24 hours
# Refresh tokens expire after 1 year or when used (new refresh token issued)
# Rate limits: 100 requests per 10 seconds, 200,000 requests per day per location
```

## Contacts API

### Create Contact

Create a new contact with comprehensive details including custom fields, tags, and source attribution.

```bash
curl -X POST https://services.leadconnectorhq.com/contacts/ \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Version: 2021-07-28" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "John",
    "lastName": "Doe",
    "email": "john.doe@example.com",
    "phone": "+12025550107",
    "locationId": "ve9EPM428h8vShlRW1KT",
    "tags": ["lead", "high-priority"],
    "customField": {
      "contact.budget": "50000",
      "contact.industry": "Technology"
    },
    "source": "website_form",
    "companyName": "Acme Corp",
    "address1": "123 Main St",
    "city": "New York",
    "state": "NY",
    "postalCode": "10001",
    "country": "US"
  }'

# Response (201 Created):
{
  "contact": {
    "id": "mTkSCb1UBjb5tk4OvB69",
    "locationId": "ve9EPM428h8vShlRW1KT",
    "firstName": "John",
    "lastName": "Doe",
    "email": "john.doe@example.com",
    "phone": "+12025550107",
    "tags": ["lead", "high-priority"],
    "source": "website_form",
    "companyName": "Acme Corp",
    "dateAdded": "2021-08-03T04:55:17.355Z",
    "dateUpdated": "2021-08-03T04:55:17.355Z"
  }
}
```

### Search Contacts

Search and filter contacts with pagination support and multiple query parameters.

```bash
curl -X GET "https://services.leadconnectorhq.com/contacts/?locationId=ve9EPM428h8vShlRW1KT&query=john&limit=20" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Version: 2021-07-28"

# Response (200 OK):
{
  "contacts": [
    {
      "id": "mTkSCb1UBjb5tk4OvB69",
      "firstName": "John",
      "lastName": "Doe",
      "email": "john.doe@example.com",
      "phone": "+12025550107",
      "tags": ["lead", "high-priority"],
      "dateAdded": "2021-08-03T04:55:17.355Z"
    }
  ],
  "meta": {
    "total": 1,
    "currentPage": 1,
    "nextPage": null,
    "prevPage": null
  }
}
```

### Update Contact

Update existing contact information including tags, custom fields, and contact details.

```bash
curl -X PUT https://services.leadconnectorhq.com/contacts/mTkSCb1UBjb5tk4OvB69 \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Version: 2021-07-28" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "John",
    "lastName": "Smith",
    "email": "john.smith@example.com",
    "tags": ["customer", "vip"]
  }'

# Response (200 OK):
{
  "contact": {
    "id": "mTkSCb1UBjb5tk4OvB69",
    "firstName": "John",
    "lastName": "Smith",
    "email": "john.smith@example.com",
    "tags": ["customer", "vip"],
    "dateUpdated": "2021-08-04T10:30:00.000Z"
  }
}
```

### Add Tags to Contact

Add multiple tags to a contact for categorization and segmentation.

```bash
curl -X POST https://services.leadconnectorhq.com/contacts/mTkSCb1UBjb5tk4OvB69/tags \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Version: 2021-07-28" \
  -H "Content-Type: application/json" \
  -d '{
    "tags": ["newsletter-subscriber", "event-attendee"]
  }'

# Response (200 OK):
{
  "tags": ["customer", "vip", "newsletter-subscriber", "event-attendee"]
}
```

### Create Contact Note

Add notes to contacts for tracking interactions and important information.

```bash
curl -X POST https://services.leadconnectorhq.com/contacts/mTkSCb1UBjb5tk4OvB69/notes \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Version: 2021-07-28" \
  -H "Content-Type: application/json" \
  -d '{
    "body": "Customer called regarding pricing for enterprise plan. Very interested. Follow up next week.",
    "userId": "082goXVW3lIExEQPOnd3"
  }'

# Response (200 OK):
{
  "note": {
    "id": "note_abc123",
    "body": "Customer called regarding pricing for enterprise plan. Very interested. Follow up next week.",
    "userId": "082goXVW3lIExEQPOnd3",
    "dateAdded": "2021-08-04T14:20:00.000Z"
  }
}
```

## Opportunities API

### Create Opportunity

Create a new sales opportunity linked to a contact in a specific pipeline stage.

```bash
curl -X POST https://services.leadconnectorhq.com/opportunities/ \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Version: 2021-07-28" \
  -H "Content-Type: application/json" \
  -d '{
    "pipelineId": "VDm7RPYC2GLUvdpKmBfC",
    "locationId": "ve9EPM428h8vShlRW1KT",
    "name": "Enterprise Software Deal",
    "pipelineStageId": "7915dedc-8f18-44d5-8bc3-77c04e994a10",
    "status": "open",
    "contactId": "mTkSCb1UBjb5tk4OvB69",
    "monetaryValue": 50000,
    "assignedTo": "082goXVW3lIExEQPOnd3",
    "customFields": [
      {
        "id": "6dvNaf7VhkQ9snc5vnjJ",
        "field_value": "Q4 2024"
      }
    ]
  }'

# Response (201 Created):
{
  "opportunity": {
    "id": "yWQobCRIhRguQtD2llvk",
    "name": "Enterprise Software Deal",
    "monetaryValue": 50000,
    "pipelineId": "VDm7RPYC2GLUvdpKmBfC",
    "pipelineStageId": "7915dedc-8f18-44d5-8bc3-77c04e994a10",
    "assignedTo": "082goXVW3lIExEQPOnd3",
    "status": "open",
    "contactId": "mTkSCb1UBjb5tk4OvB69",
    "locationId": "ve9EPM428h8vShlRW1KT",
    "createdAt": "2021-08-03T04:55:17.355Z"
  }
}
```

### Search Opportunities

Search opportunities with extensive filtering options including pipeline, stage, status, and contact.

```bash
curl -X GET "https://services.leadconnectorhq.com/opportunities/search?location_id=ve9EPM428h8vShlRW1KT&pipeline_id=VDm7RPYC2GLUvdpKmBfC&status=open&assigned_to=082goXVW3lIExEQPOnd3&limit=20" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Version: 2021-07-28"

# Response (200 OK):
{
  "opportunities": [
    {
      "id": "yWQobCRIhRguQtD2llvk",
      "name": "Enterprise Software Deal",
      "monetaryValue": 50000,
      "pipelineId": "VDm7RPYC2GLUvdpKmBfC",
      "pipelineStageId": "7915dedc-8f18-44d5-8bc3-77c04e994a10",
      "assignedTo": "082goXVW3lIExEQPOnd3",
      "status": "open",
      "contactId": "mTkSCb1UBjb5tk4OvB69",
      "createdAt": "2021-08-03T04:55:17.355Z",
      "contact": {
        "id": "mTkSCb1UBjb5tk4OvB69",
        "name": "John Smith",
        "email": "john.smith@example.com"
      }
    }
  ],
  "meta": {
    "total": 1,
    "currentPage": 1
  }
}
```

### Update Opportunity Status

Change the status of an opportunity (open, won, lost, abandoned).

```bash
curl -X PUT https://services.leadconnectorhq.com/opportunities/yWQobCRIhRguQtD2llvk/status \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Version: 2021-07-28" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "won"
  }'

# Response (200 OK):
{
  "succeded": true
}
```

### Get Pipelines

Retrieve all sales pipelines and their stages for a location.

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

# Response (200 OK):
{
  "pipelines": [
    {
      "id": "VDm7RPYC2GLUvdpKmBfC",
      "name": "Sales Pipeline",
      "stages": [
        {
          "id": "7915dedc-8f18-44d5-8bc3-77c04e994a10",
          "name": "Qualified Lead"
        },
        {
          "id": "8a26efed-9g29-55e6-9ad4-88d15fe95b21",
          "name": "Proposal Sent"
        }
      ],
      "locationId": "ve9EPM428h8vShlRW1KT"
    }
  ]
}
```

## Conversations API

### Search Conversations

Search and filter conversations with support for assignment, status, and message type filtering.

```bash
curl -X GET "https://services.leadconnectorhq.com/conversations/search?locationId=ABCHkzuJQ8ZMd4Te84GK&contactId=9VEmS0si86GW6gXWU89b&limit=20" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Version: 2021-04-15"

# Response (200 OK):
{
  "conversations": [
    {
      "id": "conv_123abc",
      "contactId": "9VEmS0si86GW6gXWU89b",
      "locationId": "ABCHkzuJQ8ZMd4Te84GK",
      "assignedTo": "user_456def",
      "lastMessageType": "TYPE_SMS",
      "lastMessageBody": "Thank you for your inquiry!",
      "lastMessageDate": "2021-08-04T15:30:00.000Z",
      "unreadCount": 0
    }
  ],
  "meta": {
    "total": 1
  }
}
```

### Send Message

Send SMS, email, or other message types through the conversations API.

```bash
curl -X POST https://services.leadconnectorhq.com/conversations/messages \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Version: 2021-04-15" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "SMS",
    "contactId": "9VEmS0si86GW6gXWU89b",
    "locationId": "ABCHkzuJQ8ZMd4Te84GK",
    "message": "Hi John, your appointment is confirmed for tomorrow at 2 PM. See you then!"
  }'

# Response (201 Created):
{
  "message": {
    "id": "msg_789ghi",
    "conversationId": "conv_123abc",
    "type": "TYPE_SMS",
    "body": "Hi John, your appointment is confirmed for tomorrow at 2 PM. See you then!",
    "direction": "outbound",
    "status": "sent",
    "dateAdded": "2021-08-04T16:00:00.000Z"
  }
}
```

## Calendars API

### Get Calendar Free Slots

Retrieve available time slots for booking appointments on a specific calendar.

```bash
curl -X GET "https://services.leadconnectorhq.com/calendars/cal_abc123/free-slots?startDate=2024-08-10&endDate=2024-08-17&timezone=America/New_York" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Version: 2021-07-28"

# Response (200 OK):
{
  "slots": [
    {
      "date": "2024-08-10",
      "slots": [
        {
          "startTime": "09:00",
          "endTime": "09:30"
        },
        {
          "startTime": "10:00",
          "endTime": "10:30"
        },
        {
          "startTime": "14:00",
          "endTime": "14:30"
        }
      ]
    }
  ]
}
```

### Create Appointment

Book a new appointment for a contact on a specific calendar.

```bash
curl -X POST https://services.leadconnectorhq.com/calendars/events/appointments \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Version: 2021-07-28" \
  -H "Content-Type: application/json" \
  -d '{
    "calendarId": "cal_abc123",
    "contactId": "mTkSCb1UBjb5tk4OvB69",
    "locationId": "ve9EPM428h8vShlRW1KT",
    "startTime": "2024-08-10T14:00:00.000Z",
    "endTime": "2024-08-10T14:30:00.000Z",
    "title": "Initial Consultation",
    "appointmentStatus": "confirmed"
  }'

# Response (201 Created):
{
  "event": {
    "id": "appt_xyz789",
    "calendarId": "cal_abc123",
    "contactId": "mTkSCb1UBjb5tk4OvB69",
    "title": "Initial Consultation",
    "startTime": "2024-08-10T14:00:00.000Z",
    "endTime": "2024-08-10T14:30:00.000Z",
    "appointmentStatus": "confirmed"
  }
}
```

## Users API

### Search Users

Search for users within a company or location with filtering options.

```bash
curl -X GET "https://services.leadconnectorhq.com/users/search?companyId=5DP41231LkQsiKESj6rh&query=John&role=admin&limit=10" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Version: 2021-07-28"

# Response (200 OK):
{
  "users": [
    {
      "id": "082goXVW3lIExEQPOnd3",
      "name": "John Admin",
      "firstName": "John",
      "lastName": "Admin",
      "email": "john.admin@example.com",
      "phone": "+12025550199",
      "role": "admin",
      "type": "account"
    }
  ],
  "meta": {
    "total": 1,
    "skip": 0,
    "limit": 10
  }
}
```

### Get User by ID

Retrieve detailed information about a specific user.

```bash
curl -X GET https://services.leadconnectorhq.com/users/082goXVW3lIExEQPOnd3 \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Version: 2021-07-28"

# Response (200 OK):
{
  "user": {
    "id": "082goXVW3lIExEQPOnd3",
    "name": "John Admin",
    "firstName": "John",
    "lastName": "Admin",
    "email": "john.admin@example.com",
    "phone": "+12025550199",
    "extension": "101",
    "role": "admin",
    "permissions": {
      "campaignsEnabled": true,
      "contactsEnabled": true
    }
  }
}
```

## Campaigns API

### Get Campaigns

Retrieve all campaigns for a specific location with optional status filtering.

```bash
curl -X GET "https://services.leadconnectorhq.com/campaigns/?locationId=ve9EPM428h8vShlRW1KT&status=published" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Version: 2021-07-28"

# Response (200 OK):
{
  "campaigns": [
    {
      "id": "mIVALPYuTD7YjUHnFEx4",
      "name": "Summer Promotion 2024",
      "status": "published",
      "locationId": "ve9EPM428h8vShlRW1KT"
    },
    {
      "id": "nJWBQMZvUE8ZkVIoGFy5",
      "name": "Welcome Series",
      "status": "published",
      "locationId": "ve9EPM428h8vShlRW1KT"
    }
  ]
}
```

## Locations (Sub-Accounts) API

### Get Location

Retrieve detailed information about a specific location/sub-account.

```bash
curl -X GET https://services.leadconnectorhq.com/locations/ve9EPM428h8vShlRW1KT \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Version: 2021-07-28"

# Response (200 OK):
{
  "location": {
    "id": "ve9EPM428h8vShlRW1KT",
    "name": "Downtown Office",
    "address": "456 Business Ave",
    "city": "Los Angeles",
    "state": "CA",
    "country": "US",
    "postalCode": "90001",
    "website": "https://downtown.example.com",
    "timezone": "America/Los_Angeles",
    "email": "info@downtown.example.com",
    "phone": "+13105550123"
  }
}
```

### Search Locations

Search locations within a company with filtering and pagination.

```bash
curl -X GET "https://services.leadconnectorhq.com/locations/search?companyId=5DP41231LkQsiKESj6rh&limit=20&skip=0" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Version: 2021-07-28"

# Response (200 OK):
{
  "locations": [
    {
      "id": "ve9EPM428h8vShlRW1KT",
      "name": "Downtown Office",
      "city": "Los Angeles",
      "state": "CA"
    }
  ],
  "count": 1
}
```

## Custom Fields API

### Get Custom Fields

Retrieve all custom fields configured for a location.

```bash
curl -X GET https://services.leadconnectorhq.com/locations/ve9EPM428h8vShlRW1KT/customFields \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Version: 2021-07-28"

# Response (200 OK):
{
  "customFields": [
    {
      "id": "6dvNaf7VhkQ9snc5vnjJ",
      "name": "Budget",
      "fieldKey": "contact.budget",
      "dataType": "TEXT",
      "position": 1
    },
    {
      "id": "7ewObg8WimRatoD6wokK",
      "name": "Industry",
      "fieldKey": "contact.industry",
      "dataType": "DROPDOWN",
      "position": 2,
      "options": ["Technology", "Finance", "Healthcare"]
    }
  ]
}
```

## Webhooks

### Webhook Authentication

Verify webhook authenticity using signature validation to ensure requests originate from GoHighLevel.

```javascript
// Node.js example for webhook signature verification
const crypto = require('crypto');

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

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

// Express.js webhook endpoint
app.post('/webhooks/gohighlevel', (req, res) => {
  const signature = req.headers['x-ghl-signature'];
  const webhookSecret = process.env.GHL_WEBHOOK_SECRET;

  if (!verifyWebhookSignature(req.body, signature, webhookSecret)) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  // Process webhook event
  const { type, locationId, data } = req.body;

  switch(type) {
    case 'ContactCreate':
      console.log('New contact created:', data.contact.id);
      break;
    case 'OpportunityStatusUpdate':
      console.log('Opportunity status changed:', data.opportunity.status);
      break;
    case 'InboundMessage':
      console.log('Received message:', data.message.body);
      break;
  }

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

### Contact Webhook Events

Handle real-time contact events for immediate response to customer interactions.

```json
// ContactCreate Webhook Payload
{
  "type": "ContactCreate",
  "locationId": "ve9EPM428h8vShlRW1KT",
  "id": "event_abc123",
  "timestamp": "2024-08-04T10:30:00.000Z",
  "contact": {
    "id": "mTkSCb1UBjb5tk4OvB69",
    "firstName": "Jane",
    "lastName": "Doe",
    "email": "jane.doe@example.com",
    "phone": "+12025550108",
    "tags": ["lead"],
    "source": "Landing Page"
  }
}

// ContactTagUpdate Webhook Payload
{
  "type": "ContactTagUpdate",
  "locationId": "ve9EPM428h8vShlRW1KT",
  "id": "event_def456",
  "timestamp": "2024-08-04T11:00:00.000Z",
  "contact": {
    "id": "mTkSCb1UBjb5tk4OvB69",
    "tagsAdded": ["customer"],
    "tagsRemoved": ["lead"]
  }
}
```

### Opportunity Webhook Events

Monitor sales pipeline changes in real-time for automated workflows.

```json
// OpportunityCreate Webhook Payload
{
  "type": "OpportunityCreate",
  "locationId": "ve9EPM428h8vShlRW1KT",
  "id": "event_ghi789",
  "timestamp": "2024-08-04T12:00:00.000Z",
  "opportunity": {
    "id": "yWQobCRIhRguQtD2llvk",
    "name": "Enterprise Deal",
    "monetaryValue": 50000,
    "pipelineId": "VDm7RPYC2GLUvdpKmBfC",
    "pipelineStageId": "7915dedc-8f18-44d5-8bc3-77c04e994a10",
    "contactId": "mTkSCb1UBjb5tk4OvB69",
    "status": "open"
  }
}

// OpportunityStatusUpdate Webhook Payload
{
  "type": "OpportunityStatusUpdate",
  "locationId": "ve9EPM428h8vShlRW1KT",
  "id": "event_jkl012",
  "timestamp": "2024-08-04T16:00:00.000Z",
  "opportunity": {
    "id": "yWQobCRIhRguQtD2llvk",
    "oldStatus": "open",
    "newStatus": "won",
    "monetaryValue": 50000
  }
}
```

## Error Handling

### Common Error Responses

Handle API errors gracefully with standard HTTP status codes and detailed error messages.

```javascript
// JavaScript error handling example
async function createContact(contactData) {
  try {
    const response = await fetch('https://services.leadconnectorhq.com/contacts/', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${accessToken}`,
        'Version': '2021-07-28',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(contactData)
    });

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

      switch (response.status) {
        case 400:
          // Bad Request - validation error
          console.error('Validation error:', error.message);
          break;
        case 401:
          // Unauthorized - token expired or invalid
          console.error('Authentication failed. Refreshing token...');
          await refreshAccessToken();
          return createContact(contactData); // Retry
        case 422:
          // Unprocessable Entity - business logic error
          console.error('Business logic error:', error.message);
          break;
        case 429:
          // Rate limit exceeded
          const retryAfter = response.headers.get('Retry-After') || 10;
          console.error(`Rate limit exceeded. Retry after ${retryAfter}s`);
          await sleep(retryAfter * 1000);
          return createContact(contactData); // Retry
        default:
          console.error('API error:', error);
      }

      throw new Error(error.message);
    }

    return await response.json();

  } catch (error) {
    console.error('Request failed:', error);
    throw error;
  }
}

// Example error response (400 Bad Request)
{
  "statusCode": 400,
  "message": "Invalid email format",
  "traceId": "abc123def456"
}

// Example error response (401 Unauthorized)
{
  "statusCode": 401,
  "message": "Access token expired",
  "traceId": "ghi789jkl012"
}
```

## Summary

The GoHighLevel API V2 serves as the backbone for building sophisticated marketing automation and CRM integrations. Primary use cases include creating custom marketplace applications that sync data between GoHighLevel and external systems, building automated workflows triggered by webhook events, developing white-labeled solutions for agencies, and constructing analytics dashboards that aggregate data across multiple locations. The API enables bulk operations for managing contacts and opportunities at scale, facilitates appointment scheduling integrations with third-party calendar systems, and supports payment processing integrations for e-commerce workflows. Developers can leverage the API to build chatbot integrations through the conversations endpoints, create custom reporting tools, and implement automated lead scoring systems.

Integration patterns typically follow OAuth 2.0 best practices with token refresh logic, webhook signature verification for security, and proper error handling with exponential backoff for rate limiting. Most applications implement a multi-tenant architecture where a single app installation serves multiple locations, requiring careful token management and scope configuration. The API's comprehensive scope system allows fine-grained permission control, enabling applications to request only necessary access. Rate limiting (100 requests per 10 seconds burst, 200,000 daily per location) necessitates request queuing and batch operations for high-volume integrations. Webhook events provide real-time notifications for building reactive systems, while pagination support and search endpoints enable efficient data retrieval. The API version header requirement ensures backward compatibility as the platform evolves, making it suitable for long-term production integrations.