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.
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.
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.
Check your Node.js version
Run these commands:
node --version npm --versionConfirm 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.
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 -yThis creates a package.json file that records your project's dependencies and settings.
Install the SDK
npm install @gohighlevel/api-clientIf your project uses yarn or pnpm instead, the corresponding commands are:
yarn add @gohighlevel/api-client pnpm add @gohighlevel/api-clientUse only the command for the package manager your project uses. Avoid mixing lockfiles from different package managers without a reason.
Confirm the dependency is installed
Run:
npm ls @gohighlevel/api-clientThe 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.
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.
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_IDto 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.
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.
| Problem | What to check | Suggested response |
|---|---|---|
| Authentication error | Credentials, token validity, OAuth authorization, and account access. | Fix the credential or reauthorize using the documented flow. |
| Permission denied | Token type, required scopes, and location-level permissions. | Review the endpoint's scope requirements and request only necessary access. |
| Invalid request | Required fields, data types, IDs, and request parameters. | Validate input before making the API call. |
| Record not found | Contact or opportunity ID, selected location, and data availability. | Confirm the identifier and handle missing results safely. |
| Rate limit response | Request volume and the endpoint's current rate-limit policy. | Apply controlled retries and backoff rather than repeatedly sending requests. |
| Network or server error | Connectivity, 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.
| Consideration | Official npm SDK | Direct HTTP requests |
|---|---|---|
| Getting started | Install the package and initialize the client. | Configure an HTTP library, URL, headers, and request handling. |
| Method interface | Provides typed SDK methods for supported API resources. | You construct each request from the API documentation. |
| Authentication | Offers documented token and OAuth support. | You implement or configure authentication handling yourself. |
| Error handling | Uses SDK error behavior and supported helpers. | You manage status codes, responses, and retries yourself. |
| Flexibility | Convenient when a suitable SDK method exists. | Useful when you need direct control over a particular HTTP request. |
| Maintenance | Keep 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.
| Feature | Node.js npm SDK | MCP server |
|---|---|---|
| Primary audience | Developers building applications in JavaScript or TypeScript. | People using compatible AI clients that need access to supported tools. |
| How it works | Your code calls SDK methods. | An AI client discovers and invokes tools through the MCP protocol. |
| Typical task | Build 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 fit | Repeatable 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 GuideWe 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.