@gnosticdev/highlevel-sdk NPM

HighLevel API SDK

Typescript SDK for working with HighLevel API endpoints. Every endpoint for both v1 and v2 of the API has a fully typed client SDK, and the types are generated from HighLevel's OpenAPI v3 documentation so will always be compatible and up to date.

Features

NEW Support for Private Integrations
API Endpoints generated from HighLevel's OpenAPI v3 documentation, using openapi-typescript
Fully typed client SDK (using native fetch) built with openapi-fetch
OAuth2 helpers for working with HighLevel's OAuth2 implementation
Scopes builder for easily adding the appropriate scopes to your app
Webhooks client with typed responses
Support for both v1 (legacy API keys) and v2 (OAuth & Private Integrations)

Resources

API v2 Documentation (OAuth & Private Integrations)
API v1 Documentation (Legacy API Keys)

Installation

bun add @gnosticdev/highlevel-sdk
# or
pnpm add @gnosticdev/highlevel-sdk
# or
npm add @gnosticdev/highlevel-sdk

Usage

Using the HighLevel Client

The HighLevel client uses the v2 API by default (see below for v1 client). It can be created with different configurations:

Basic Client: Without built-in authentication.

const client = createHighLevelClient()

// or pass in the client config
const client = createHighLevelClient({
  baseUrl: 'https://api.custom-url.com',
})

Client with OAuth: Requires OAuth configuration.

// The first argument is always the client config, so pass an empty object if you don't need it
const client = createHighLevelClient({}, 'oauth', {
    clientId: 'your-client-id',
    clientSecret: 'your-client-secret',
    redirectUri: 'http://localhost:3000/callback',
    accessType: 'Sub-Account',
    scopes: ['contacts.readonly']
})

Client with Private Integration: Requires private integration configuration.

const client = createHighLevelClient({}, 'integration', {
    privateToken: process.env.HIGHLEVEL_PRIVATE_TOKEN!,
    accessType: 'Agency',
    scopes: ['saas/company.write', 'saas/company.read']
})

Error Handling

The SDK uses openapi-fetch under the hood, which returns both data and error properties for type-safe error handling.

import { createHighLevelClient } from "@gnosticdev/highlevel-sdk"

// Create client with OAuth2 support
const client = createHighLevelClient({}, 'oauth', {
    clientId: process.env.HIGHLEVEL_CLIENT_ID!,
    clientSecret: process.env.HIGHLEVEL_CLIENT_SECRET!,
    redirectUri: 'http://localhost:3000/oauth/callback',
    accessType: 'Sub-Account',
    scopes: ['contacts.readonly'],
    // Optional: store tokens in your database
    storageFunction: async (tokenData) => {
        await db.saveTokenResponse({
            access_token: tokenData.access_token,
            expiresAt: tokenData.expiresAt,
            refresh_token: tokenData.refresh_token,
            locationId: tokenData.locationId,
            userId: tokenData.userId,
        })
        return tokenData
    }
})

// Example: Get contacts with error handling
const { data, error } = await client.contacts.GET('/contacts/', {
    params: {
        query: {
            locationId: '1234567890',
            query: 'John Doe',
            limit: 10,
        },
    },
})

if (error) {
    console.error('Error fetching contacts:', error.message)
    // Handle error appropriately
    return
}

// Type-safe response data
console.log(data.contacts)

OAuth2 Support

The OAuth client is available on the HighLevelClient instance when created with OAuth configuration:

// Generate authorization URL
const authUrl = client.oauth.getAuthorizationUrl()

// Exchange auth code for token
const token = await client.oauth.exchangeToken(authCode)

// Get access token (automatically refreshes if expired)
const accessToken = await client.oauth.getAccessToken()

Using the v1 Client

The v1 client requires an API key and automatically adds the authorization header to all requests.

import { createHighLevelV1Client } from "@gnosticdev/highlevel-sdk"

const v1Client = createHighLevelV1Client({
    apiKey: process.env.HIGHLEVEL_API_KEY!
})

const { data, error } = await v1Client.GET('/v1/contacts', {
    params: {
        query: {
            locationId: '1234567890',
        }
        // No need to add Authorization header - it's added automatically
    }
})

if (error) {
    console.error('Error fetching contacts:', error)
    return
}

console.log(data.contacts)

Using the Webhooks Client

The SDK includes a typed client for handling HighLevel webhooks. This provides type safety and validation for incoming webhook payloads:

import { createWebhooksClient } from "@gnosticdev/highlevel-sdk/webhooks"

const webhooks = createWebhooksClient()

// Example: Hono route handler for Contact Create webhook
app.post('/webhooks/contact-create', async (ctx) => {
  const { data, error } = await webhooks.ContactCreate.POST({
    body: ctx.req.body
  })

  if (error) {
    console.error('Invalid webhook payload:', error)
    return res.status(400).json(error)
  }

  // data is fully typed based on the webhook type
  console.log('Contact created:', data)
  res.status(200).end()
})

// Example: Handle App Installation webhook
app.post('/webhooks/app-install', async (req, res) => {
  const { data, error } = await webhooks.AppInstall.POST({
    body: req.body
  })

  if (error) {
    console.error('Invalid app install payload:', error)
    return res.status(400).json(error)
  }

  // Handle new app installation
  const { locationId, userId, companyId } = data
  await db.saveNewInstallation({ locationId, userId, companyId })

  res.status(200).end()
})

Available webhook types include:
- AppointmentCreate
- AppInstall
- ContactCreate
- ContactUpdate
- NoteCreate
- NoteUpdate
- OpportunityCreate
- UserCreate
- And more...

The webhooks client provides full type safety and validation for all webhook payloads defined in the HighLevel API.

### Endpoint Types

If you just want to get types for the API endpoints, you can use them like this:

```ts
import type * as Locations from "@gnosticdev/highlevel-sdk/types/locations"

// Example: the response type for the `GET /locations/{locationId}` endpoint
type LocationCustomValues =
    NonNullable<Locations.operations['get-custom-values']['responses']['200']['content']['application/json']['customValues']>

const customValues: LocationCustomValues = [{
    fieldKey: 'contact.lead_source',
    id: 'lead_source_id',
    locationId: 'my_location_id',
    name: 'Lead Source',
    value: 'Google',
}]

Module Exports

The SDK provides several module exports for better organization and tree-shaking:

// Main client
import { createHighLevelClient } from "@gnosticdev/highlevel-sdk"

// OAuth specific functionality
import { OAuthClient } from "@gnosticdev/highlevel-sdk/oauth"

// Scopes builder
import { ScopesBuilder } from "@gnosticdev/highlevel-sdk/scopes"

// V1 API client
import { createHighLevelV1Client } from "@gnosticdev/highlevel-sdk/v1"

// Webhooks client
import { createWebhooksClient } from "@gnosticdev/highlevel-sdk/webhooks"

// Types
import type * as Locations from "@gnosticdev/highlevel-sdk/types/locations"

Scopes

Once you have added your scopes to your app, you can collect them from the dev console on your app's settings page in the Highlevel Marketplace:

/**
 * Navigate to your apps' setting page -  `https://marketplace.highlevel.com/app-settins/<your-app-id>/auth`
 * Press cmd + J on keyboard
 */
$$('.n-tag__content')
    .map((scope) => scope.textContent.trim())
    .toSorted()

Copy the resulting array

Create a new ScopesBuilder instance and paste the scopes to it.

const client = createHighLevelClient({}, 'oauth', {
    clientId: 'your-client-id',
    clientSecret: 'your-client-secret',
    redirectUri: 'http://localhost:3000/callback',
    scopes: [
        'locations.write',
        'contacts.readonly',
        // ... your scopes here
    ]
})