<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

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 for enrichment writeback.

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.

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

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.