Registry / crm-productivity / node-hubspot-api

node-hubspot-api

JSON →
library1.3.1jsnpmunverified

The `node-hubspot-api` package provides a Node.js wrapper for interacting with the HubSpot API. Currently at version 1.3.1, this library simplifies common API operations such as retrieving, creating, and updating contacts, and fetching deals. It employs a promises-based architecture for asynchronous operations, returning data in `.then()` and catching errors in `.catch()`. The release cadence is moderate, with several minor releases since v1.0.0, indicating ongoing maintenance and incremental feature additions, such as new methods for getting contacts by email or ID, and bug fixes. Its primary differentiator is its straightforward, idiomatic JavaScript interface to the HubSpot CRM platform, abstracting the underlying HTTP complexities. This wrapper directly exposes common HubSpot API endpoints through a convenient object structure, focusing on essential CRM entities.

npm install node-hubspot-api
INSTALL
IMPORT
SIG · NODE-HUBSPOT-API
N
node-hubspot-api
crm-productivityjavascriptv1.3.1
Install
—
Import
—
Disk
—
Pass rate
0/ 6
Env Coverage0 / 6
glibc
18–22
musl
18–22
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18–226 runs
build_error
glibc
node 18–226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

NodeHubSpotApi
✓ import NodeHubSpotApi from 'node-hubspot-api'
✗ const NodeHubSpotApi = require('node-hubspot-api')
The library primarily uses ES Module syntax (`import`). While CommonJS `require()` might work in some transpiled or older Node.js environments, the official examples use `import`.
NodeHubSpotApi (type)
✓ import type { NodeHubSpotApi } from 'node-hubspot-api'
If using TypeScript, `NodeHubSpotApi` is the main class. Check package for explicit type definitions if strict typing is needed.

This quickstart demonstrates how to initialize the HubSpot API client with an API key and perform basic operations like fetching a list of contacts and a single contact by email.

import NodeHubSpotApi from 'node-hubspot-api'; // It is crucial to manage API keys securely, e.g., via environment variables. const HUBSPOT_API_KEY = process.env.HUBSPOT_API_KEY ?? 'YOUR_SECRET_API_KEY'; const api = new NodeHubSpotApi(HUBSPOT_API_KEY); // Example: Get all contacts with specific properties api.contacts.getAll({ count: 2, // Fetch a small number for a quick example property: [ 'firstname', 'lastname', 'email', 'company' ], showListMemberships: false }) .then(response => { console.log('Successfully fetched contacts:'); if (response.data && response.data.contacts) { response.data.contacts.forEach(contact => { console.log(`- ${contact.properties.firstname?.value} ${contact.properties.lastname?.value} (${contact.properties.email?.value})`); }); } else { console.log('No contacts found or unexpected response structure.'); } }) .catch(error => { console.error('Error fetching contacts:', error.response ? error.response.data : error.message); }); // Example: Get a contact by email const targetEmail = 'test@example.com'; // Replace with a real email for testing api.contacts.getContactByEmail(targetEmail, { property: ['firstname', 'lastname', 'email'], }) .then(response => { console.log(`\nSuccessfully fetched contact by email "${targetEmail}":`); console.log(response.data); }) .catch(error => { if (error.response && error.response.status === 404) { console.warn(`\nContact with email "${targetEmail}" not found.`); } else { console.error(`\nError fetching contact by email "${targetEmail}":`, error.response ? error.response.data : error.message); } });
Debug
Known issues
gotchaHubSpot API keys are sensitive credentials. Hardcoding them directly in your source code or checking them into version control is a security risk. Always use environment variables or a secure configuration management system.
fix
Store your HubSpot API key in an environment variable (e.g., `HUBSPOT_API_KEY`) and access it via `process.env.HUBSPOT_API_KEY`.
affects: >=0.1.0
gotchaMethods like `contacts.getAll()` return paginated results, typically with a maximum of 100 contacts per page. To retrieve all contacts, you must implement pagination logic using the `vidOffset` parameter.
fix
Iteratively call the `getAll` method, updating the `vidOffset` with the value from the previous response until no more contacts are returned.
affects: >=0.1.0
gotchaBy default, HubSpot API responses for contacts (e.g., `getAll`, `getContactById`, `getContactByEmail`) only include a few standard properties. To receive specific properties, you must explicitly request them using the `property` array parameter.
fix
Include `property: ['email', 'firstname', 'lastname', ...]` in your method call options to specify desired contact properties.
affects: >=0.1.0
gotchaIn version 1.3.0, a bug was fixed where 'overwriting properties/property parameters on any API method' was not working as intended. If upgrading from versions prior to 1.3.0, the behavior of merging or overriding parameters in API calls might change to correctly apply user-provided values.
fix
Ensure you are on `v1.3.0` or higher to benefit from correct parameter handling. Review your API calls for methods that involve property or parameter overriding to ensure they function as expected after upgrading.
affects: <1.3.0
Errors
Common errors & fixes
TypeError: Cannot read properties of undefined (reading 'contacts')
The `NodeHubSpotApi` instance was not correctly initialized or the `contacts` property was accessed before the API client was ready.
fix
Ensure you `new NodeHubSpotApi(YOUR_API_KEY)` and the `api` object is available before attempting to call `api.contacts.anything()`.
Error: Request failed with status code 401
The provided HubSpot API key is invalid, expired, or missing, leading to an unauthorized request.
fix
Verify your `HUBSPOT_API_KEY` is correct and active. Ensure it has the necessary permissions for the API endpoints you are trying to access.
Error: Request failed with status code 404 (or similar 'Contact not found')
The requested contact ID or email address does not exist in HubSpot, or there is an issue with the API endpoint path.
fix
Double-check the contact ID or email address for accuracy. Confirm the HubSpot API documentation for the correct endpoint and parameters.
Upgrade
Version history
1.3.1latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
34 hits · last 30 days
node
32
OpenAI (training)
1
Resources
node-hubspot-api — npm install node-hubspot-api · libregistry