HubSpot CRM Integration

Connection

• Base URL: https://api.hubapi.com
• Auth: Authorization: Bearer $HUBSPOT_PRIVATE_APP_TOKEN or legacy HUBSPOT_ACCESS_TOKEN
• Env vars: HUBSPOT_PRIVATE_APP_TOKEN preferred, HUBSPOT_ACCESS_TOKEN legacy
• Caching: 10-minute in-memory cache, max 120 entries

Server Lib

• File: server/lib/hubspot.ts

Exported Functions

Function	Description
getDealPipelines()	All deal pipelines with stages
getVisiblePipelines(pipelines)	Filter to visible pipelines
getMetricsPipelines(pipelines)	Filter to metrics-relevant pipelines
getDealProperties()	HubSpot deal property metadata
getAllDeals(extraProperties?)	All deals (paginated, up to ~10k)
getDealOwners()	HubSpot owner id → owner name map
computeSalesMetrics(deals, pipelines, filter?)	Compute won/lost/pipeline metrics

Script Usage

# Search deals for a named account/deal
pnpm action hubspot-deals --query="Example Corp" --limit=10 --properties=dealname,amount,dealstage

# Structured cohort: products field = Publish, closed-won New Business deals
pnpm action hubspot-deals --product=Publish --pipeline="New Business" --closedStatus=won --closedDateFrom=2025-06-01 --closedDateTo=2026-06-01

# List deals
pnpm action hubspot-deals --properties=dealname,amount,dealstage

# Find custom fields before requesting them
pnpm action hubspot-deal-properties --search=nbm

Key Patterns & Gotchas

• getAllDeals paginates using limit=100 and HubSpot after token (up to 100 pages)
• hubspot-deals --query="Customer" uses HubSpot search and should be the first path for named account/deal deep dives. Avoid pulling every deal first.
• For deal cohorts, use structured hubspot-deals filters (product, pipeline, closedStatus, closedDateFrom, closedDateTo) and report the returned filters/count in the methodology.
• Do not use query for property-specific filters. query="Publish" is broad full-text search across deals and can include records where products is not Publish.
• If hubspot-deals cannot express the needed CRM endpoint/filter/body/pagination, use provider-api-catalog --provider=hubspot, optionally provider-api-docs, then provider-api-request --provider=hubspot with the exact HubSpot API request.
• hubspot-deals returns normalized stage_name, pipeline_name, owner_name, is_closed_won, and is_deal_closed fields under deal.properties
• For AE QBR or NBM deck work, HubSpot is the source of truth. Request nbm_meeting_booked_date, nbm_meeting_complete_date, and hs_manual_forecast_category through hubspot-deals; do not use warehouse SQL as the first path unless HubSpot is unavailable and the user approves the fallback
• Optional deal properties are filtered against HubSpot property metadata before fetching, so deployments without a custom field do not fail the whole action
• The default deal fetch includes the hard-coded hs_v2_date_entered stage property names with embedded stage IDs when they exist in the connected portal
• computeSalesMetrics infers won/lost stages from probability metadata or label text; identifies POV stages by names containing "proof of value", "pov", "poc"
• When looking up a customer, search deals by name, then get associated company via /crm/v3/objects/deals/{id}/associations/companies, then contacts via /crm/v3/objects/companies/{id}/associations/contacts

HubSpot Company Properties (BigQuery staging table)

Table: your-project-id.dbt_staging.hubspot_companies

• company_name, company_id, company_domain_name
• upcoming_renewal_date, customer_stage, hs_csm_sentiment
• company_owner_name, root_org_id
• customer_segmentation, current_enterprise_arr, company_status

Cross-Reference

• HubSpot company → contacts → dim_hs_contacts.builder_user_id → BigQuery usage data
• HubSpot deal → company → Pylon support tickets, Gong sales calls