{"id":16143,"library":"node-hubspot-api","title":"HubSpot API Client for Node.js","description":"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.","status":"active","version":"1.3.1","language":"javascript","source_language":"en","source_url":"https://github.com/hmschreiner/node-hubspot-api","tags":["javascript","hubspot","api"],"install":[{"cmd":"npm install node-hubspot-api","lang":"bash","label":"npm"},{"cmd":"yarn add node-hubspot-api","lang":"bash","label":"yarn"},{"cmd":"pnpm add node-hubspot-api","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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`.","wrong":"const NodeHubSpotApi = require('node-hubspot-api')","symbol":"NodeHubSpotApi","correct":"import NodeHubSpotApi from 'node-hubspot-api'"},{"note":"If using TypeScript, `NodeHubSpotApi` is the main class. Check package for explicit type definitions if strict typing is needed.","symbol":"NodeHubSpotApi (type)","correct":"import type { NodeHubSpotApi } from 'node-hubspot-api'"}],"quickstart":{"code":"import NodeHubSpotApi from 'node-hubspot-api';\n\n// It is crucial to manage API keys securely, e.g., via environment variables.\nconst HUBSPOT_API_KEY = process.env.HUBSPOT_API_KEY ?? 'YOUR_SECRET_API_KEY'; \n\nconst api = new NodeHubSpotApi(HUBSPOT_API_KEY);\n\n// Example: Get all contacts with specific properties\napi.contacts.getAll({\n  count: 2, // Fetch a small number for a quick example\n  property: [\n    'firstname', 'lastname', 'email', 'company'\n  ],\n  showListMemberships: false\n})\n.then(response => {\n  console.log('Successfully fetched contacts:');\n  if (response.data && response.data.contacts) {\n    response.data.contacts.forEach(contact => {\n      console.log(`- ${contact.properties.firstname?.value} ${contact.properties.lastname?.value} (${contact.properties.email?.value})`);\n    });\n  } else {\n    console.log('No contacts found or unexpected response structure.');\n  }\n})\n.catch(error => {\n  console.error('Error fetching contacts:', error.response ? error.response.data : error.message);\n});\n\n// Example: Get a contact by email\nconst targetEmail = 'test@example.com'; // Replace with a real email for testing\napi.contacts.getContactByEmail(targetEmail, {\n  property: ['firstname', 'lastname', 'email'],\n})\n.then(response => {\n  console.log(`\\nSuccessfully fetched contact by email \"${targetEmail}\":`);\n  console.log(response.data);\n})\n.catch(error => {\n  if (error.response && error.response.status === 404) {\n    console.warn(`\\nContact with email \"${targetEmail}\" not found.`);\n  } else {\n    console.error(`\\nError fetching contact by email \"${targetEmail}\":`, error.response ? error.response.data : error.message);\n  }\n});","lang":"javascript","description":"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."},"warnings":[{"fix":"Store your HubSpot API key in an environment variable (e.g., `HUBSPOT_API_KEY`) and access it via `process.env.HUBSPOT_API_KEY`.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Iteratively call the `getAll` method, updating the `vidOffset` with the value from the previous response until no more contacts are returned.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Include `property: ['email', 'firstname', 'lastname', ...]` in your method call options to specify desired contact properties.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"<1.3.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Ensure you `new NodeHubSpotApi(YOUR_API_KEY)` and the `api` object is available before attempting to call `api.contacts.anything()`.","cause":"The `NodeHubSpotApi` instance was not correctly initialized or the `contacts` property was accessed before the API client was ready.","error":"TypeError: Cannot read properties of undefined (reading 'contacts')"},{"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.","cause":"The provided HubSpot API key is invalid, expired, or missing, leading to an unauthorized request.","error":"Error: Request failed with status code 401"},{"fix":"Double-check the contact ID or email address for accuracy. Confirm the HubSpot API documentation for the correct endpoint and parameters.","cause":"The requested contact ID or email address does not exist in HubSpot, or there is an issue with the API endpoint path.","error":"Error: Request failed with status code 404 (or similar 'Contact not found')"}],"ecosystem":"npm"}