Integrate HubSpot CRM with OAuth and batch operations

Covers HubSpot CRM integration patterns for Node.js, with Python equivalents noted, across seven areas: OAuth 2.0 authentication for public or multi-account apps (authorization URL, token exchange, refresh before the 30-minute access-token expiry), Private App tokens for single-account integrations that don't expire but should be rotated every 6 months, CRUD and search operations on CRM objects like contacts (create/read/update/archive/search with cursor-based pagination, since the Search API caps at 10k results), batch operations of up to 100 items per request that save up to 80% of rate-limit quota with per-item atomic partial success, the Associations v4 API for linking records such as contact-to-company or deal-to-contact using numbered standard association type IDs and custom USER_DEFINED labels, requiring SDK 9.0.0+, webhook handling with HMAC-SHA256 signature validation via X-HubSpot-Signature-v3, a 5-minute replay-attack timestamp window, and queued async processing since HubSpot expects a response within 5 seconds, and custom objects with typed property schemas, Enterprise-tier only, capped at 10 custom objects per account.

const hubspotClient = new Client({
  accessToken: process.env.HUBSPOT_PRIVATE_APP_TOKEN,
});

Use it when building or hardening a HubSpot CRM integration - OAuth flows, contact/company/deal CRUD, bulk data sync, real-time webhook handling, or custom object modeling. Choose OAuth 2.0 for a public app serving multiple HubSpot accounts, and a Private App token for an internal, single-account integration. The skill delegates adjacent work to sibling skills rather than covering it itself: email-marketing automation beyond HubSpot's built-in tools, a custom CRM UI or portal, an ETL pipeline from HubSpot to a data warehouse, HubSpot-Salesforce sync, payments beyond HubSpot quotes, and custom analytics reporting are all explicitly out of scope and routed elsewhere. It also flags API keys as a deprecated, CRITICAL-severity auth method, superseded by OAuth or Private App tokens.

Inputs are HubSpot CRM objects - contacts, companies, deals, custom objects - and their properties; outputs are typed API calls through @hubspot/api-client (crm.contacts.basicApi, .batchApi, .searchApi, crm.associations.v4, crm.schemas.coreApi) returning HubSpot's paginated result objects. The skill documents eight "sharp edges" at HIGH/CRITICAL severity - rate limits varying by app type and hub tier, a 5% error-rate threshold enforced on marketplace apps, deprecated API keys, 30-minute OAuth token expiry, mandatory webhook signature validation, required pagination on every list endpoint, breaking changes in the Associations v4 API, and a 100,000-request daily polling cap - plus ten automated validation-check messages, such as "Hardcoded HubSpot access token" at ERROR, or "Individual API calls in loop" at INFO recommending batch operations instead.

Built on the official @hubspot/api-client Node.js SDK, with a parallel Python hubspot SDK shown for the same calls, using HubSpot's own OAuth 2.0 token endpoint, webhook signature header (X-HubSpot-Signature-v3), and Associations v4 API. It explicitly hands off adjacent needs to five sibling skills: email-marketing, frontend, data-engineer, salesforce-development, stripe-integration, and analytics-specialist.

Backend developers integrating an application with HubSpot's CRM - contacts, companies, deals, custom objects - who need working auth, batch, association, and webhook patterns plus HubSpot's specific rate-limit and validation gotchas, in either Node.js or Python.