hubspot

# HubSpot Use HubSpot for CRM facts: deal status, amount, stage, owner, forecast, associated account context, contacts, companies, and tickets. Analytics' HubSpot actions use its native provider credential or granted workspace connection. A missing optional HubSpot MCP server does not mean HubSpot is disconnected. Never send the user to HubSpot MCP setup to answer an Analytics data question. If availability is unclear, call `data-source-status` with `key: "hubspot"`; when it reports HubSpot configured, run the native HubSpot action directly. `hubspot-deals` is a legacy-named deal analytics shortcut, not the boundary of the HubSpot integration. If the user asks for any HubSpot object, endpoint, association, property, filter, batch read/write, or API version that the typed actions do not expose, inspect the provider catalog/docs and call `provider-api-request` with `provider: "hubspot"`. ## Actions - `account-deep-dive` — first choice for the CRM side of a named account/deal deep dive (use `run-gong-native-insight` for what was said in calls). It searches matching HubSpot deals, loads associated companies, contacts, tickets, notes, and emails, then pairs that CRM context with Gong evidence. - `hubspot-deals` — deals with normalized stage, pipeline, owner, forecast, and NBM fields. For a named customer/deal/account, pass `query`; do not fetch all deals first. For a deal cohort, use structured filters such as `product`, `pipeline`, `closedStatus`, `closedDateFrom`, and `closedDateTo`. - `hubspot-records` — generic HubSpot search/list for contacts, companies, deals, and tickets. Use this to enrich a deep dive with company, contact, or ticket records. - `hubspot-pipelines` / `hubspot-metrics` — pipeline definitions and aggregate sales metrics. - For HubSpot **property metadata** (available fields before requesting custom ones) there is no first-class action — call `provider-api-request` (provider `hubspot`, e.g. `/crm/v3/properties/deals`) via `provider-api-docs`. - `provider-api-request` with `provider: "hubspot"` — arbitrary HubSpot HTTP API calls when first-class actions are too narrow. ## Pipeline Stage Timing — Use Stage-Entry Date Fields **Always use `hs_v2_date_entered_{stageId}` for deterministic pipeline-stage timing**, not keyword or amount heuristics: - Each pipeline stage has a unique numeric ID (visible in pipeline definitions). - The property `hs_v2_date_entered_{stageId}` records the exact timestamp when the deal first entered that stage. Use this to filter deals that reached a specific stage within a date window. - **Why this matters**: heuristic filters (e.g., `amount > $30K`, keyword searches) have been found to diverge from stage-date filters by ~48% — nearly half the deals are different. Stage-entry date fields provide verifiable, auditable results. To discover stage IDs, call `hubspot-pipelines` first and read the `stageId` fields in the returned pipeline structure. Example use: to count deals that reached "Qualified Opportunity" stage in Q1: ``` provider-api-request( provider: "hubspot", path: "/crm/v3/objects/deals/search", method: "POST", body: { "filterGroups": [{ "filters": [{ "propertyName": "hs_v2_date_entered_<stageId>", "operator": "BETWEEN", "value": "2026-01-01", "highValue": "2026-03-31" }] }], "properties": ["dealname", "amount", "hs_v2_date_entered_<stageId>"] } ) ``` ## Multi-Dimensional Closed-Lost Analysis **Deals are rarely lost for a single reason.** When analyzing closed-lost deals: - Use a multi-factor matrix with notation: primary factor (★★), contributing factor (★), possible factor (~). - Track 8-10 common loss factors per deal: Budget, Product Fit, Implementation Friction, Competitive Loss, Security/Compliance, Wrong Persona/Champion, Timeline Mismatch, Support/Success Gaps, etc. - Identify combination patterns — e.g., "Product Fit + Implementation Friction" may affect multiple deals simultaneously. - Do not force a single root cause categorization. Real losses are multi-dimensional, and flattening to one reason distorts win/loss patterns. - Report both the count of deals per single factor AND the top multi-factor combinations. ## Patterns For account or deal deep dives: 1. Call `data-source-status` if you are not sure HubSpot is connected. 2. Call `account-deep-dive` with `query` set to the company, domain, deal, or opportunity name. Use its associated companies, contacts, tickets, notes, and emails as the CRM backbone of the answer. 3. If a specific CRM gap remains, call `hubspot-deals` or `hubspot-records` with bounded filters for that missing object only. 4. Cite which records you inspected and keep unsupported associations as caveats. Example: ```txt account-deep-dive(query: "The Knot", days: 180, gongLimit: 10, transcriptLimit: 5) hubspot-deals(query: "The Knot", limit: 10) hubspot-records(objectType: "companies", query: "theknot.com", limit: 5) hubspot-records(objectType: "contacts", query: "theknot.com", limit: 25) ``` Do not use warehouse copies of HubSpot as a substitute unless the user asks for the warehouse data or the live HubSpot action is unavailable and the user chooses that fallback. For deal cohorts: 1. Translate the cohort definition into structured `hubspot-deals` filters. Example: "new business deals where products field is Publish, closed won in the last 12 months" means `product: "Publish"`, `pipeline: "New Business"`, `closedStatus: "won"`, and explicit close-date bounds. 2. Do not use `query` for property-specific filters. `query: "Publish"` is a broad HubSpot search across deal text and can include unrelated deals. 3. Report the cohort count, filters, and date window before synthesizing. If the count looks too low, inspect deal property metadata (`/crm/v3/properties/deals`) or use stage-entry date fields via `provider-api-request`. 4. When pairing a cohort with Gong, use returned deal/company/contact evidence to run bounded Gong follow-ups and state Gong coverage separately from the HubSpot cohort size. If `hubspot-deals` still cannot express the needed HubSpot query, do not stop or approximate. Call `provider-api-catalog(provider: "hubspot")`, fetch the HubSpot docs/spec with `provider-api-docs` if needed, then call `provider-api-request(provider: "hubspot", ...)` with the exact CRM endpoint, filters, properties, associations, and pagination body.