<quick_start>

1. Create a HubSpot Private App with required CRM scopes (contacts, companies, deals, owners, timeline)
2. Confirm SQL replica access and schema prefix for your data warehouse
3. Run ICP validation query (UC1) to segment conversion rates
4. Build pipeline forecast (UC5) using stage-specific historical win rates </quick_start>

<success_criteria>

• HubSpot Private App authenticated with all required scopes
• SQL warehouse connected and data freshness validated (sync lag < 24h)
• At least one use case (ICP, scoring, competitive, activity, forecast) producing results
• Lead scoring model trained on 200+ historical closed deals with measurable AUC
• Enrichment pipeline writing scores back to HubSpot without duplicates </success_criteria>

HubSpot RevOps Analytics

Revenue analytics infrastructure on HubSpot API + SQL data warehouse. Bridges CRM data → analytics → intelligence products → revenue impact.

Scope: HubSpot-specific analytics stack. For basic CRM CRUD, use crm-integration-skill. For generic dashboards, use data-analysis-skill.

Setup Checklist

1. HubSpot Private App

Note: Tim's HubSpot is accessed via the Epiphan CRM MCP connector — no Private App setup needed. All hubspot_* tools are available directly.

Create at Settings → Integrations → Private Apps:

2. SQL Replica Access

Discovery questions for your data warehouse:

3. Python Environment

pip install hubspot-api-client pandas scikit-learn requests

# SDK initialization
from hubspot import HubSpot
client = HubSpot(access_token="pat-na1-xxxxx")

# Or raw requests
import requests
HEADERS = {"Authorization": "Bearer pat-na1-xxxxx", "Content-Type": "application/json"}
BASE = "https://api.hubapi.com"

Core Use Cases

Use Case Details

UC1 — ICP Validation: Join contacts + companies + deals in SQL, segment by industry/size/geo, compute conversion rates per segment. Feed results to Clay MCP waterfall for enrichment:

1. find-and-enrich-company or find-and-enrich-contacts-at-company to identify target contacts
2. add-contact-data-points / add-company-data-points to queue enrichment jobs
3. get-existing-search to poll for results and check state: completed
4. Write enriched data back to HubSpot via API or Epiphan CRM integration

Alternative: Use Apollo MCP (apollo_people_match) for direct enrichment without waterfall wait.

UC2 — Lead Scoring: Train GradientBoostingClassifier on historical won/lost deals. Features: company size, industry, engagement score, days in pipeline. Deploy scores back to HubSpot as custom property.

UC3 — Competitive Intel: Extract competitor mentions from deal closed_lost_reason. Build win/loss matrix by competitor. Trigger webhook alerts on competitive displacement patterns.

UC4 — Activity Analysis: Correlate email opens, meetings booked, calls logged with deal outcomes. Identify which activities actually move deals forward.

UC5 — Pipeline Forecast: Calculate weighted forecast using stage-specific win rates from historical data. Factor in deal age, velocity, and rep performance.

Reference: See reference/sql-analytics.md for complete SQL templates per use case.

Golden Rules for Prospect Quality

Tim's BDR targeting criteria (as of March 2026) — Apply these filters before outreach:

-- Exclude existing customers and channels
WHERE lifecyclestage NOT IN ('customer')
  AND custom.first_conversion NOT LIKE '%Pearl%' 
  AND custom.first_conversion NOT LIKE '%setup%'
  AND custom.first_conversion NOT LIKE '%Connect%'
  AND custom.first_conversion NOT LIKE '%signup%'
  AND device_count < 1
  AND is_channel = false

-- Target only AE territories (Lex Evans, Ron Epstein, Phillip Sandler)
  AND hubspot_owner_id IN (82625923, 423155215, 190030668)

-- Optionally segment by company size, industry, location

Use this filter in:

• ICP Validation queries (UC1) before Clay enrichment
• Lead scoring model (UC2) training data
• Prospect research cadence (prospect-research-to-cadence-skill)

Note: See phone-verification-waterfall-skill for full Golden Rules implementation with Clay MCP integration.

Quick Reference: HubSpot API Endpoints

Reference: See reference/api-guide.md for auth, SDK patterns, batch operations.

Quick Reference: SQL Object Model

Join pattern: contacts → associations → companies/deals (via association tables)

Integration Points

MCP Integration Points

Common Mistakes

Workflow Phases

Phase 1: Foundation

1. Set up Private App with required scopes
2. Confirm SQL replica access and schema
3. Run schema discovery queries
4. Validate data freshness (sync lag)

Phase 2: Analytics

5. Build ICP validation queries (UC1)
6. Create pipeline velocity dashboard (UC2, UC5)
7. Set up competitive intelligence tracking (UC3)

Phase 3: Intelligence

8. Train lead scoring model on historical deals
9. Deploy scores to HubSpot via API
10. Build enrichment pipelines (Clay → HubSpot)
11. Set up automated alerts and webhooks

Reference: See reference/enrichment-pipelines.md for ML scoring and Clay integration. Reference: See reference/architecture.md for deployment patterns and cost estimates.

Emit Outcome Sidecar

As the final step, write to ~/.claude/skill-analytics/last-outcome-hubspot-revops.json:

{"ts":"[UTC ISO8601]","skill":"hubspot-revops","version":"1.0.0","variant":"default",
 "status":"[success|partial|error]","runtime_ms":[estimated ms from start],
 "metrics":{"queries_executed":[n],"reports_generated":[n],"insights_found":[n]},
 "error":null,"session_id":"[YYYY-MM-DD]"}

Use status "partial" if some stages failed but results were produced. Use "error" only if no output was generated.