Skip to main content
hubspot-integration Expert patterns for HubSpot CRM integration with the Node.js and Python SDKs — OAuth authentication, CRM objects, associations, batch operations, webhooks, and custom objects. USE WHEN integrating an app with HubSpot CRM, syncing contacts/deals, wiring webhooks, or building a public/multi-account HubSpot app.
Jump to install Skills Marketplace Discover and explore AI skills built by the community.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Show prompt details A direct command skips the review prompt. Inspect the source before running it.
npx skills add https://github.com/Sheshiyer/skill-clusters --skill hubspot-integrationThe command stays on one line. Scroll horizontally to inspect it before copying.
Prefer a local copy? Download the files currently available to SkillsMP.
Download Zip Downloading... Related occupations SOC
Based on SOC occupation classification
name hubspot-integration description Expert patterns for HubSpot CRM integration with the Node.js and Python SDKs — OAuth authentication, CRM objects, associations, batch operations, webhooks, and custom objects. USE WHEN integrating an app with HubSpot CRM, syncing contacts/deals, wiring webhooks, or building a public/multi-account HubSpot app. cluster python-backend version 1.0.0 origin antigravity-awesome-skills (MIT) risk unknown source vibeship-spawner-skills (Apache 2.0) date_added "2026-02-27T00:00:00.000Z"
HubSpot Integration
Expert patterns for HubSpot CRM integration including OAuth authentication,
CRM objects, associations, batch operations, webhooks, and custom objects.
Covers Node.js and Python SDKs.
Patterns
OAuth 2.0 Authentication
Secure authentication for public apps
When to use : Building public app or multi-account integration
Template
// OAuth 2.0 flow for HubSpot
import { Client } from "@hubspot/api-client";
// Environment variables
const CLIENT_ID = process.env.HUBSPOT_CLIENT_ID;
const CLIENT_SECRET = process.env.HUBSPOT_CLIENT_SECRET;
const REDIRECT_URI = process.env.HUBSPOT_REDIRECT_URI;
const SCOPES = "crm.objects.contacts.read crm.objects.contacts.write";
// Step 1: Generate authorization URL
function getAuthUrl(): string {
const authUrl = new URL("https://app.hubspot.com/oauth/authorize ");
authUrl.searchParams.set("client_id", CLIENT_ID);
authUrl.searchParams.set("redirect_uri", REDIRECT_URI);
authUrl.searchParams.set("scope", SCOPES);
return authUrl.toString();
}
// Step 2: Handle OAuth callback
async function handleOAuthCallback(code: string) {
const response = await fetch("https://api.hubapi.com/oauth/v1/token ", {
method: "POST",
headers: { "Content-Type": "application/x-www-form-urlencoded" },
body: new URLSearchParams({
grant_type: "authorization_code",
client_id: CLIENT_ID,
client_secret: CLIENT_SECRET,
redirect_uri: REDIRECT_URI,
code: code,
}),
});
const tokens = await response.json();
// {
// access_token: "xxx",
// refresh_token: "xxx",
// expires_in: 1800 // 30 minutes
// }
// Store tokens securely
await storeTokens(tokens);
return tokens;
}
// Step 3: Refresh access token (before expiry)
async function refreshAccessToken(refreshToken: string) {
const response = await fetch("https://api.hubapi.com/oauth/v1/token ", {
method: "POST",
headers: { "Content-Type": "application/x-www-form-urlencoded" },
body: new URLSearchParams({
grant_type: "refresh_token",
client_id: CLIENT_ID,
client_secret: CLIENT_SECRET,
refresh_token: refreshToken,
}),
});
return response.json();
}
// Step 4: Create authenticated client
function createClient(accessToken: string): Client {
const hubspotClient = new Client({ accessToken });
return hubspotClient;
}
Notes
Access tokens expire in 30 minutes
Refresh tokens before expiry
Store refresh tokens securely
Rotate tokens every 6 months
Private App Token
Authentication for single-account integrations
When to use : Building internal integration for one HubSpot account
Template // Private App Token - simpler for single account
import { Client } from "@hubspot/api-client";
// Create client with private app token
const hubspotClient = new Client({
accessToken: process.env.HUBSPOT_PRIVATE_APP_TOKEN,
});
// Private app tokens don't expire
// But should be rotated every 6 months for security
// Example: Get contacts
async function getContacts() {
try {
const response = await hubspotClient.crm.contacts.basicApi.getPage(
100, // limit
undefined, // after cursor
["firstname", "lastname", "email", "phone"], // properties
);
} catch (error) {
if (error.code === 429) {
// Rate limited - implement backoff
const retryAfter = error.headers?.["retry-after"] || 10;
await sleep(retryAfter * 1000);
return getContacts();
}
throw error;
}
}
// Python equivalent
// from hubspot import HubSpot
//
// client = HubSpot(access_token=os.environ["HUBSPOT_PRIVATE_APP_TOKEN"])
//
// contacts = client.crm.contacts.basic_api.get_page(
// limit=100,
// properties=["firstname", "lastname", "email"]
// )
Notes
Private app tokens don't expire
All private apps share daily rate limit
Each private app has own burst limit
Recommended: Rotate every 6 months
CRM Object CRUD Operations Create, read, update, delete CRM records
When to use : Working with contacts, companies, deals, tickets
Template import { Client } from "@hubspot/api-client";
const hubspotClient = new Client({
accessToken: process.env.HUBSPOT_TOKEN,
});
// CREATE contact
async function createContact(data: {
email: string;
firstname: string;
lastname: string;
}) {
const response = await hubspotClient.crm.contacts.basicApi.create({
properties: {
email: data.email,
firstname: data.firstname,
lastname: data.lastname,
},
});
// READ contact by ID
async function getContact(contactId: string) {
const response = await hubspotClient.crm.contacts.basicApi.getById(
contactId,
["firstname", "lastname", "email", "phone", "company"],
);
// UPDATE contact
async function updateContact(contactId: string, properties: object) {
const response = await hubspotClient.crm.contacts.basicApi.update(
contactId,
{ properties },
);
// DELETE contact
async function deleteContact(contactId: string) {
await hubspotClient.crm.contacts.basicApi.archive(contactId);
}
// SEARCH contacts
async function searchContacts(query: string) {
const response = await hubspotClient.crm.contacts.searchApi.doSearch({
query,
limit: 100,
properties: ["firstname", "lastname", "email"],
sorts: [{ propertyName: "createdate", direction: "DESCENDING" }],
});
return response.results;
}
// LIST with pagination
async function getAllContacts() {
const allContacts = [];
let after = undefined;
do {
const response = await hubspotClient.crm.contacts.basicApi.getPage(
100,
after,
["firstname", "lastname", "email"],
);
allContacts.push(...response.results);
after = response.paging?.next?.after;
Notes
Use properties param to fetch only needed fields
Search API has 10k result limit
Always implement pagination for lists
Archive (soft delete) vs. GDPR delete available
Batch Operations Bulk create, update, or read records efficiently
When to use : Processing multiple records (reduce rate limit usage)
Template import { Client } from "@hubspot/api-client";
const hubspotClient = new Client({
accessToken: process.env.HUBSPOT_TOKEN,
});
// BATCH CREATE contacts (up to 100 per batch)
async function batchCreateContacts(contacts: Array<{
email: string;
firstname: string;
lastname: string;
}>) {
const inputs = contacts.map((contact) => ({
properties: {
email: contact.email,
firstname: contact.firstname,
lastname: contact.lastname,
},
}));
const response = await hubspotClient.crm.contacts.batchApi.create({
inputs,
});
return response.results;
}
// BATCH UPDATE contacts
async function batchUpdateContacts(
updates: Array<{ id: string; properties: object }>
) {
const inputs = updates.map(({ id, properties }) => ({
id,
properties,
}));
const response = await hubspotClient.crm.contacts.batchApi.update({
inputs,
});
return response.results;
}
// BATCH READ contacts by ID
async function batchReadContacts(
ids: string[],
properties: string[] = ["firstname", "lastname", "email"]
) {
const response = await hubspotClient.crm.contacts.batchApi.read({
inputs: ids.map((id) => ({ id })),
properties,
});
return response.results;
}
// BATCH ARCHIVE contacts
async function batchDeleteContacts(ids: string[]) {
await hubspotClient.crm.contacts.batchApi.archive({
inputs: ids.map((id) => ({ id })),
});
}
// Process large dataset in chunks
async function processLargeDataset(allContacts: any[]) {
const BATCH_SIZE = 100;
const results = [];
for (let i = 0; i < allContacts.length; i += BATCH_SIZE) {
const batch = allContacts.slice(i, i + BATCH_SIZE);
const batchResults = await batchCreateContacts(batch);
results.push(...batchResults);
// Respect rate limits - wait between batches
if (i + BATCH_SIZE < allContacts.length) {
await sleep(100); // 100ms between batches
}
Notes
Max 100 items per batch request
Saves up to 80% of rate limit quota
Batch operations are atomic per item (partial success possible)
Check response.errors for failed items
Associations v4 API Create relationships between CRM records
When to use : Linking contacts to companies, deals, etc.
Template import { Client, AssociationTypes } from "@hubspot/api-client";
const hubspotClient = new Client({
accessToken: process.env.HUBSPOT_TOKEN,
});
// CREATE association (Contact to Company)
async function associateContactToCompany(
contactId: string,
companyId: string
) {
await hubspotClient.crm.associations.v4.basicApi.create(
"contacts",
contactId,
"companies",
companyId,
[
{
associationCategory: "HUBSPOT_DEFINED",
associationTypeId: AssociationTypes.contactToCompany,
},
]
);
}
// CREATE association (Deal to Contact)
async function associateDealToContact(dealId: string, contactId: string) {
await hubspotClient.crm.associations.v4.basicApi.create(
"deals",
dealId,
"contacts",
contactId,
[
{
associationCategory: "HUBSPOT_DEFINED",
associationTypeId: 3, // deal_to_contact
},
]
);
}
// GET associations for a record
async function getContactCompanies(contactId: string) {
const response = await hubspotClient.crm.associations.v4.basicApi.getPage(
"contacts",
contactId,
"companies",
undefined,
500
);
return response.results;
}
// CREATE association with custom label
async function createLabeledAssociation(
contactId: string,
companyId: string,
labelId: number // Custom association label ID
) {
await hubspotClient.crm.associations.v4.basicApi.create(
"contacts",
contactId,
"companies",
companyId,
[
{
associationCategory: "USER_DEFINED",
associationTypeId: labelId,
},
]
);
}
// BATCH create associations
async function batchAssociateContactsToCompany(
contactIds: string[],
companyId: string
) {
const inputs = contactIds.map((contactId) => ({
_from: { id: contactId },
to: { id: companyId },
types: [
{
associationCategory: "HUBSPOT_DEFINED",
associationTypeId: AssociationTypes.contactToCompany,
},
],
}));
await hubspotClient.crm.associations.v4.batchApi.create(
"contacts",
"companies",
{ inputs }
);
}
// Common association type IDs
// Contact to Company: 1
// Company to Contact: 2
// Deal to Contact: 3
// Contact to Deal: 4
// Deal to Company: 5
// Company to Deal: 6
Notes
Requires SDK version 9.0.0+ for v4 API
Association labels supported for custom relationships
Use batch API for multiple associations
HUBSPOT_DEFINED for standard, USER_DEFINED for custom labels
Webhook Handling Receive real-time notifications from HubSpot
When to use : Need instant updates on CRM changes
Template import crypto from "crypto";
import { Client } from "@hubspot/api-client";
// Webhook signature validation
function validateWebhookSignature(
requestBody: string,
signature: string,
clientSecret: string
): boolean {
// For v2 signature (most common)
const expectedSignature = crypto
.createHmac("sha256", clientSecret)
.update(requestBody)
.digest("hex");
return signature === expectedSignature;
}
// Express webhook handler
app.post("/webhooks/hubspot", async (req, res) => {
const signature = req.headers["x-hubspot-signature-v3"] as string;
const timestamp = req.headers["x-hubspot-request-timestamp"] as string;
const requestBody = JSON.stringify(req.body);
// Validate signature
const isValid = validateWebhookSignature(
requestBody,
signature,
process.env.HUBSPOT_CLIENT_SECRET
);
if (!isValid) {
console.error("Invalid webhook signature");
return res.status(401).send("Unauthorized");
}
// Check timestamp (prevent replay attacks)
const timestampAge = Date.now() - parseInt(timestamp);
if (timestampAge > 300000) { // 5 minutes
console.error("Webhook timestamp too old");
return res.status(401).send("Timestamp expired");
}
// Process events - respond quickly!
const events = req.body;
// Queue for async processing
for (const event of events) {
await queue.add("hubspot-webhook", event);
}
// Respond immediately
res.status(200).send("OK");
});
// Async processor
async function processWebhookEvent(event: any) {
const { subscriptionType, objectId, propertyName, propertyValue } = event;
switch (subscriptionType) {
case "contact.creation":
await handleContactCreated(objectId);
break;
case "contact.propertyChange":
await handleContactPropertyChange(objectId, propertyName, propertyValue);
break;
case "deal.creation":
await handleDealCreated(objectId);
break;
case "contact.deletion":
await handleContactDeleted(objectId);
break;
default:
console.log(`Unhandled event: ${subscriptionType}`);
// Webhook subscription types:
// contact.creation, contact.deletion, contact.propertyChange
// company.creation, company.deletion, company.propertyChange
// deal.creation, deal.deletion, deal.propertyChange
Notes
Validate signature before processing
Respond within 5 seconds
Queue heavy processing for async
Max 1000 webhook subscriptions per app
Custom Objects Create and manage custom object types
When to use : Standard objects don't fit your data model
Template import { Client } from "@hubspot/api-client";
const hubspotClient = new Client({
accessToken: process.env.HUBSPOT_TOKEN,
});
// CREATE custom object schema
async function createCustomObjectSchema() {
const schema = {
name: "projects",
labels: {
singular: "Project",
plural: "Projects",
},
primaryDisplayProperty: "project_name",
requiredProperties: ["project_name"],
properties: [
{
name: "project_name",
label: "Project Name",
type: "string",
fieldType: "text",
},
{
name: "status",
label: "Status",
type: "enumeration",
fieldType: "select",
options: [
{ label: "Active", value: "active" },
{ label: "Completed", value: "completed" },
{ label: "On Hold", value: "on_hold" },
],
},
{
name: "budget",
label: "Budget",
type: "number",
fieldType: "number",
},
{
name: "start_date",
label: "Start Date",
type: "date",
fieldType: "date",
},
],
associatedObjects: ["CONTACT", "COMPANY"],
};
const response = await hubspotClient.crm.schemas.coreApi.create(schema);
return response;
}
// CREATE custom object record
async function createProject(data: {
project_name: string;
status: string;
budget: number;
}) {
const response = await hubspotClient.crm.objects.basicApi.create(
"projects", // Custom object name
{ properties: data }
);
// READ custom object by ID
async function getProject(projectId: string) {
const response = await hubspotClient.crm.objects.basicApi.getById(
"projects",
projectId,
["project_name", "status", "budget", "start_date"]
);
// UPDATE custom object
async function updateProject(projectId: string, properties: object) {
const response = await hubspotClient.crm.objects.basicApi.update(
"projects",
projectId,
{ properties }
);
// SEARCH custom objects
async function searchProjects(status: string) {
const response = await hubspotClient.crm.objects.searchApi.doSearch(
"projects",
{
filterGroups: [
{
filters: [
{
propertyName: "status",
operator: "EQ",
value: status,
},
],
},
],
properties: ["project_name", "status", "budget"],
limit: 100,
}
);
return response.results;
}
Notes
Custom objects require Enterprise tier
Max 10 custom objects per account
Use crm.objects API with object name as parameter
Can associate with standard and other custom objects
Sharp Edges
Rate Limits Vary by App Type and Hub Tier
5% Error Rate Threshold for Marketplace Apps
API Keys Deprecated - Use OAuth or Private App Tokens
OAuth Access Tokens Expire in 30 Minutes
Webhook Requests Must Be Validated
All List Endpoints Require Pagination
Associations v4 API Has Breaking Changes
Polling Limited to 100,000 Requests Per Day
Validation Checks
Hardcoded HubSpot API Key API keys must never be hardcoded
Message: Hardcoded HubSpot API key detected. Use environment variables. Note: API keys are deprecated - use Private App tokens.
Hardcoded HubSpot Access Token Access tokens must use environment variables
Message: Hardcoded HubSpot access token. Use environment variables.
Hardcoded Client Secret OAuth client secrets must be secured
Message: Hardcoded client secret. Use environment variables.
Missing Webhook Signature Validation Webhook endpoints must validate HubSpot signatures
Message: Webhook endpoint without signature validation. Validate X-HubSpot-Signature-v3.
Missing Rate Limit Handling API calls should handle 429 responses
Message: HubSpot API calls without rate limit handling. Implement retry logic with backoff.
Unthrottled Parallel API Calls Parallel calls can exceed rate limits
Message: Parallel HubSpot API calls without throttling. Use rate limiter.
Missing Pagination for List Calls List endpoints return paginated results
Message: API call without pagination handling. Implement cursor-based pagination.
Individual Operations in Loop Use batch operations for multiple items
Message: Individual API calls in loop. Consider batch operations for better performance.
Token Storage Without Expiry OAuth tokens expire and need refresh logic
Message: Token storage without expiry tracking. Store expiresAt for refresh logic.
Deprecated API Key Usage Message: Using deprecated API key. Migrate to Private App token or OAuth 2.0.
Collaboration
Delegation Triggers
user needs email marketing automation -> email-marketing (Beyond HubSpot's built-in email tools)
user needs custom CRM UI -> frontend (Building portal or dashboard)
user needs data pipeline -> data-engineer (ETL from HubSpot to warehouse)
user needs Salesforce integration -> salesforce-development (HubSpot + Salesforce sync)
user needs payment processing -> stripe-integration (Payments beyond HubSpot quotes)
user needs analytics dashboard -> analytics-specialist (Custom reporting beyond HubSpot)
When to Use
User mentions or implies: hubspot
User mentions or implies: hubspot api
User mentions or implies: hubspot crm
User mentions or implies: hubspot integration
User mentions or implies: contacts api
Limitations
Use this skill only when the task clearly matches the scope described above.
Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.
More from this repository Arcplume runs Grok through the Grok Build CLI's own OAuth-authenticated session (grok login) for image generation, with strict preflight validation, secret-safe handling, and headless CLI-driven execution -- no separate XAI_API_KEY billing. Video falls back to the billed xAI API. USE WHEN a user wants to generate an image via a locally logged-in Grok Build CLI session, e.g. 'generate an image with grok', 'use grok build', or 'use my logged-in grok session'.
Shared reference for the Selemene cluster: the two report surfaces (deterministic Rust reports vs. narrative witness-pipeline readings), the @selemene/bridge CLI contract, the output manifest format, and non-prescriptive witnessing tone. USE WHEN deciding which Selemene surface to invoke or when routing between birth/compatibility/transit reports and solo/dyadic readings.
Route Selemene Engine tasks to the right surface: deterministic reports (birth/compatibility/transit) via selemene-core and the @selemene/bridge CLI, or narrative witness readings via selemene-report. USE WHEN the user wants anything under the Selemene/Noesis umbrella but has not named the exact surface.
