HubSpot API Client for Node.js

Common errors

• TypeError: Cannot read properties of undefined (reading 'contacts')

  cause 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

  cause 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')

  cause 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.

Warnings

• gotcha HubSpot 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`.
• gotcha Methods 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.
• gotcha By 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.
• gotcha In 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.

Install

• npm install node-hubspot-api npm
• yarn add node-hubspot-api yarn
• pnpm add node-hubspot-api pnpm

Imports

• NodeHubSpotApi
  wrong:

  const NodeHubSpotApi = require('node-hubspot-api')

  correct:

  import NodeHubSpotApi from '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.

Quickstart

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);
  }
});