GoHighLevel npm Package: Install the Official Node.js SDK & API

Node.js + HighLevel API

Use the Official GoHighLevel npm Package to Build API Integrations

Want to connect a Node.js application to GoHighLevel? The official @gohighlevel/api-client package provides a JavaScript and TypeScript SDK for working with HighLevel's API. Learn how to install it, configure authentication, make requests, manage tokens, and troubleshoot common development problems.

Explore GoHighLevel Official Node.js SDK Docs JS Node.js app Your application Business logic npm SDK Authentication Typed API methods HighLevel Contacts and deals Supported API resources Install → authenticate → call API methods

What Is the GoHighLevel npm Package?

The official package is named @gohighlevel/api-client. It is a JavaScript and TypeScript SDK that helps developers call HighLevel's REST API from Node.js applications.

Instead of building every HTTP request, response handler, and token-management step yourself, you can use SDK methods that map to supported HighLevel API resources. The official SDK documentation describes features including OAuth support, Private Integration Token support, token refresh, typed service methods, webhook helpers, and error handling.

For example, a developer might use the SDK to search contacts, retrieve opportunity information, or connect a custom application to a HighLevel location. The exact operation still depends on the endpoint, required scopes, token type, and account permissions.

Install through npm

Add the SDK to a Node.js project with the package manager you already use.

Use supported authentication

Configure OAuth credentials or an appropriate Private Integration Token for your integration type.

Call API resources

Use SDK methods to interact with supported CRM resources instead of manually building every request.

Handle integration events

Use the documented webhook helpers to support app-installation events and other integration logic.

Important: this npm package is an SDK for developers building applications with the HighLevel API. It is not the same as HighLevel's MCP server, Marketplace CLI, or a browser extension.

What You Need Before Installing

  • Node.js 18 or later. Check the SDK's current requirements before starting.
  • npm, yarn, or pnpm. Use whichever package manager your project already supports.
  • A HighLevel account. You need access to the relevant agency or sub-account.
  • API authentication. Choose OAuth for an app integration or a supported Private Integration Token for a suitable private connection.
  • Required scopes and permissions. The token must be allowed to access the resources you want to use.
  • A safe development environment. Keep secrets outside source code and test with non-production data first.

If you're new to APIs, first read our GoHighLevel API guide and GoHighLevel developer portal guide. They explain the wider API ecosystem before you start writing code.

How to Install the Official GoHighLevel npm Package

Open a terminal in your Node.js project folder and run the installation command.

1

Check your Node.js version

Run these commands:

node --version npm --version

Confirm that your installed Node.js version meets the SDK's current minimum requirement. If you're setting up a new project, use a supported long-term support release where practical.

2

Create a project if needed

If you don't already have a Node.js project, create a folder and initialize npm:

mkdir highlevel-integration cd highlevel-integration npm init -y

This creates a package.json file that records your project's dependencies and settings.

3

Install the SDK

npm install @gohighlevel/api-client

If your project uses yarn or pnpm instead, the corresponding commands are:

yarn add @gohighlevel/api-client pnpm add @gohighlevel/api-client

Use only the command for the package manager your project uses. Avoid mixing lockfiles from different package managers without a reason.

4

Confirm the dependency is installed

Run:

npm ls @gohighlevel/api-client

The output should show the package installed in your project. If npm reports an error, review the package name, network connection, Node.js version, and any dependency conflict reported by the terminal.

Official package: View @gohighlevel/api-client on npm. Always check the package's current version, release notes, and requirements before deploying it to production.

Configure Authentication for the SDK

Installing the package does not grant access to your HighLevel data. Your application must initialize the client with a supported authentication method and have the right permissions for each operation.

OAuth for app integrations

Use OAuth when building an app that agencies or locations authorize. Your app typically needs client credentials, an authorization flow, and secure storage for the resulting tokens.

Choose the scopes your app genuinely needs. Avoid requesting broad access by default.

Private Integration Token

A Private Integration Token can suit a private integration for a specific HighLevel account. It is a secret credential and should be stored securely.

Confirm the token's available scopes and whether it fits the type of access your application requires.

The official SDK documentation shows initialization with OAuth client credentials and also supports token-based configurations. Follow the current SDK examples for the exact constructor options required by your chosen authentication method.

Example: Initialize the client with OAuth credentials

import { HighLevel } from '@gohighlevel/api-client'; const highLevel = new HighLevel({ clientId: process.env.HIGHLEVEL_CLIENT_ID, clientSecret: process.env.HIGHLEVEL_CLIENT_SECRET, });

This example uses environment variables so the credentials aren't written directly into the source code. It initializes the SDK client; your app still needs the appropriate OAuth authorization and token handling for the operations it performs.

Example: Initialize with a Private Integration Token

import { HighLevel } from '@gohighlevel/api-client'; const highLevel = new HighLevel({ privateIntegrationToken: process.env.HIGHLEVEL_PRIVATE_INTEGRATION_TOKEN, });

Use this pattern only when a Private Integration Token is appropriate for your use case and supported by your installed SDK version. Never publish the token in a public repository, frontend JavaScript, or a shared screenshot.

Security note: Environment variables are one useful starting point, but production applications also need appropriate secret storage, access controls, and a plan for rotating or revoking credentials.

Make Your First GoHighLevel API Request

Once your client and authentication are configured, use a documented SDK method to perform a small test. The example below follows the official Node.js SDK pattern for searching contacts.

Example: Search contacts

import { HighLevel } from '@gohighlevel/api-client'; const highLevel = new HighLevel({ clientId: process.env.HIGHLEVEL_CLIENT_ID, clientSecret: process.env.HIGHLEVEL_CLIENT_SECRET, }); async function listContacts() { try { const response = await highLevel.contacts.searchContactsAdvanced({ locationId: process.env.HIGHLEVEL_LOCATION_ID, pageLimit: 5, }); console.log(response); } catch (error) { console.error('HighLevel API request failed:', error); } } listContacts();

This example asks the SDK to search contacts for a specific location and limits the result size to five. The exact returned fields depend on the API response and the SDK version you're using.

Before running it:

  • Set the OAuth client credentials in your environment.
  • Set HIGHLEVEL_LOCATION_ID to the location you are authorized to access.
  • Confirm that your authentication method and scopes permit contact search.
  • Use a development account or test location if possible.

To find the right method for a different task, consult the official Node.js SDK reference. SDK methods can change as endpoints and package versions evolve, so verify method names and required parameters against the version installed in your project.

Using the SDK With TypeScript

The package includes TypeScript declarations, making it useful for projects that benefit from typed request parameters and editor assistance. You can import the client into a TypeScript application just as you would in JavaScript.

import { HighLevel } from '@gohighlevel/api-client'; const highLevel = new HighLevel({ clientId: process.env.HIGHLEVEL_CLIENT_ID ?? '', clientSecret: process.env.HIGHLEVEL_CLIENT_SECRET ?? '', }); async function searchContacts() { const response = await highLevel.contacts.searchContactsAdvanced({ locationId: process.env.HIGHLEVEL_LOCATION_ID ?? '', pageLimit: 5, }); return response; }

This illustrates the general TypeScript structure, not a complete production application. Validate environment variables before creating the client, and add error handling appropriate to your application. Empty fallback strings prevent a TypeScript value from being undefined, but they do not create valid credentials.

If your project uses ES modules, make sure your TypeScript and Node.js module settings are consistent. Follow the package's current examples if your build system requires a different import pattern.

OAuth Token Storage and Refresh

For OAuth-based applications, access tokens can expire. A production integration needs to store and refresh tokens correctly so users do not have to reconnect every time a token expires.

The official SDK supports session storage options and token refresh. Its documentation explains that tokens are stored in memory by default and shows how to configure persistent storage such as MongoDB.

Why persistent storage matters

In-memory storage can be convenient during local development. However, tokens stored only in memory may be lost when a process restarts. If your app needs to maintain connections across deployments or server restarts, configure an appropriate persistent storage adapter.

Illustrative MongoDB storage configuration

import { HighLevel, MongoDBSessionStorage, } from '@gohighlevel/api-client'; const highLevel = new HighLevel({ clientId: process.env.HIGHLEVEL_CLIENT_ID, clientSecret: process.env.HIGHLEVEL_CLIENT_SECRET, sessionStorage: new MongoDBSessionStorage({ dbUrl: process.env.MONGODB_URL, dbName: 'highlevel_sessions', }), });

Check the installed package's current documentation for the exact storage adapter constructor signature and configuration options. Protect your database connection string and restrict access to stored tokens.

Do not store tokens casually. Choose storage with appropriate access controls, backups, encryption where applicable, and a defined retention and revocation process. Never commit production secrets to Git.

Handle API Errors and Rate Limits

Even a correctly configured SDK can receive errors. A contact may not exist, an input may be invalid, a token may lack a required scope, or an API endpoint may temporarily reject requests.

ProblemWhat to checkSuggested response
Authentication errorCredentials, token validity, OAuth authorization, and account access.Fix the credential or reauthorize using the documented flow.
Permission deniedToken type, required scopes, and location-level permissions.Review the endpoint's scope requirements and request only necessary access.
Invalid requestRequired fields, data types, IDs, and request parameters.Validate input before making the API call.
Record not foundContact or opportunity ID, selected location, and data availability.Confirm the identifier and handle missing results safely.
Rate limit responseRequest volume and the endpoint's current rate-limit policy.Apply controlled retries and backoff rather than repeatedly sending requests.
Network or server errorConnectivity, service status, timeout, and response details.Retry only when appropriate, log the failure, and avoid duplicating write operations.

Use clear error handling

async function findContacts(locationId) { try { const response = await highLevel.contacts.searchContactsAdvanced({ locationId, pageLimit: 5, }); return response; } catch (error) { // Log enough detail to troubleshoot. // Never log access tokens or client secrets. console.error('Contact search failed:', error); throw error; } }

Keep error handling specific to the application. For example, a user-facing service may return a friendly message while recording safe diagnostic details for developers. Avoid logging full contact records or other sensitive customer data unless there is a clear, protected need.

For production use, review the official API documentation for current rate limits, retry behavior, and endpoint-specific requirements. Do not assume every error is temporary or safe to retry.

Use the SDK With Webhooks

API requests let your application ask HighLevel for information or perform supported actions. Webhooks can help your application react to events without continuously polling for changes.

The official SDK documents webhook middleware for Express-compatible applications. It can help validate webhook signatures and handle app installation or uninstallation events as part of an OAuth app integration.

Illustrative Express middleware pattern

app.use( '/api/webhooks/ghl', highLevel.webhooks.subscribe() ); app.post('/api/webhooks/ghl', (req, res) => { // Add your event-specific business logic here. res.json({ ok: true }); });

This snippet illustrates the documented middleware pattern; it is not a complete server. You must initialize Express, configure the SDK and its storage correctly, and follow the package's current webhook instructions. Check how your server parses request bodies because signature validation can depend on the original request payload.

Webhooks are useful for event-driven integrations, but your application still needs to handle duplicate delivery, failures, and event-specific logic. Design handlers to be safe if the same event is received more than once.

Read the HighLevel API documentation for webhook events and endpoint requirements.

GoHighLevel npm Package vs. Direct API Requests

You can call HighLevel's REST API directly with an HTTP client, or use the official SDK to simplify common integration tasks.

ConsiderationOfficial npm SDKDirect HTTP requests
Getting startedInstall the package and initialize the client.Configure an HTTP library, URL, headers, and request handling.
Method interfaceProvides typed SDK methods for supported API resources.You construct each request from the API documentation.
AuthenticationOffers documented token and OAuth support.You implement or configure authentication handling yourself.
Error handlingUses SDK error behavior and supported helpers.You manage status codes, responses, and retries yourself.
FlexibilityConvenient when a suitable SDK method exists.Useful when you need direct control over a particular HTTP request.
MaintenanceKeep the dependency updated and check SDK changes.Maintain your request code as API requirements change.

For most Node.js developers who want a maintained, typed interface to HighLevel's API, the official SDK is a sensible starting point. Direct HTTP requests can still be appropriate when you need to debug an endpoint, test an API feature, or use an operation not yet exposed by your installed SDK version.

GoHighLevel npm Package vs. MCP Server

The npm SDK and the MCP server solve different problems. Knowing the difference helps you avoid installing a tool that does not match your goal.

FeatureNode.js npm SDKMCP server
Primary audienceDevelopers building applications in JavaScript or TypeScript.People using compatible AI clients that need access to supported tools.
How it worksYour code calls SDK methods.An AI client discovers and invokes tools through the MCP protocol.
Typical taskBuild a backend that searches contacts and synchronizes data.Ask an AI assistant to search or summarize CRM records through available tools.
Requires a Node.js project?Yes, for using the package directly.Not necessarily; the remote MCP server can connect through a compatible client.
Best fitRepeatable custom integrations and software development.Natural-language interaction with supported CRM tools.

If your goal is to build a custom app, start with the API guide and the developer portal guide. If you want to connect an AI assistant to CRM tools, read our GoHighLevel MCP server guide or Claude MCP setup guide.

Common GoHighLevel npm Installation Problems

npm says the package cannot be found

Check that you typed @gohighlevel/api-client exactly, that your terminal has internet access, and that npm is using the expected registry. Visit the official package page to verify its current availability and installation instructions.

The import statement fails

Check your installed package version and whether your project uses CommonJS or ES modules. The SDK documentation includes import examples for different module styles. Also check the project's Node.js and TypeScript settings if you're using a build step.

The API returns an authentication error

Confirm that your environment variables are set, that the token belongs to the intended account, and that the authentication method matches your integration. OAuth apps need a valid authorization flow; Private Integration Tokens must be valid and permitted for the operation.

The request fails because of a missing location ID

Many location-specific operations need a valid locationId. Confirm the correct location ID and ensure the token has access to it. Do not substitute a company or agency ID where a location ID is required.

The method shown in a tutorial does not exist

The tutorial may use another SDK version or an outdated method name. Check the installed version, current Node.js SDK reference, and package release notes. Do not assume a method exists just because the underlying REST endpoint exists.

Token refresh works locally but fails after deployment

Review your persistent session storage, database connection, environment variables, and deployment permissions. The SDK's default in-memory token storage may not survive process restarts. Configure a supported persistent storage adapter where required.

How should I handle rate limits?

Follow the current API rate-limit policy and SDK documentation. Use sensible request pacing and bounded retries with backoff for temporary rate-limit responses. Avoid retrying non-idempotent write operations blindly, because that may create duplicates.

Frequently Asked Questions

What is the official GoHighLevel npm package?

The official Node.js SDK package is @gohighlevel/api-client. It provides JavaScript and TypeScript methods for working with HighLevel's supported REST API resources.

How do I install the HighLevel SDK?

Run npm install @gohighlevel/api-client in your Node.js project folder. Check the official package page for the latest requirements and release information.

Does the SDK support TypeScript?

Yes. The package includes TypeScript declarations, and the official documentation provides TypeScript examples.

Can I use a Private Integration Token with the SDK?

The official SDK documents support for Private Integration Tokens. Confirm that this authentication method fits your use case and that the token has the required permissions for the endpoint you need.

Does the SDK automatically refresh OAuth tokens?

The official SDK documents automatic token refresh support. For production OAuth integrations, configure appropriate session storage and follow the current SDK instructions so tokens and updated session data are handled correctly.

Can I use the SDK in a browser frontend?

Do not expose client secrets or private integration tokens in browser JavaScript. Keep privileged API operations on a secure backend and let your frontend communicate with your own server using an appropriately secured application design.

Is the npm package free?

The package is publicly available on npm. That does not mean every HighLevel API feature, account plan, or external service is free. Check the current HighLevel plan and API requirements for your intended integration.

Where can I find official examples?

Start with the official Node.js SDK guide, the HighLevel API documentation, and the npm package page.

Build Your Next HighLevel Integration

The official Node.js SDK can reduce the work involved in connecting a custom application to HighLevel. Start with one small, well-defined API request, confirm that authentication and permissions work, then expand into webhooks and more complex workflows.

Explore GoHighLevel Read the GoHighLevel API Guide

We may earn a commission if you purchase through our affiliate link, at no additional cost to you. Verify current features, API access, and pricing before purchasing.

Replace 100 tools with One Platform

Business platform dashboard Get Started