hubspot

# 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 ```bash # 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