hubspot-revops-skill

The saved excerpt is a snapshot from review. The external source remains the complete and most current version.

---
name: hubspot-revops-skill
description: Use when building revenue analytics on HubSpot — SQL warehouse queries,
  API enrichment pipelines, lead scoring models, pipeline forecasting, competitive
  intelligence. Triggers on "hubspot analytics", "revops dashboard", "lead scoring",
  "pipeline forecast", "ICP analysis", "hubspot SQL".
---

<objective>
Build revenue analytics infrastructure on HubSpot API + SQL data warehouse. Covers ICP validation, ML lead scoring, competitive intelligence, activity analysis, and pipeline forecasting — bridging CRM data into actionable intelligence products.
</objective>

<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:

| Scope | Permission | Why |
|-------|-----------|-----|
| `crm.objects.contacts.read/write` | Read/Write | Contact enrichment |
| `crm.objects.companies.read` | Read | Company data |
| `crm.objects.deals.read/write` | Read/Write | Pipeline analytics |
| `crm.schemas.custom.read` | Read | Custom objects |
| `crm.objects.owners.read` | Read | Rep attribution |
| `timeline` | Read | Activity data |

### 2. SQL Replica Access

Discovery questions for your data warehouse:

| Question | Options |
|----------|---------|
| Where is HubSpot data replicated? | Snowflake / BigQuery / Postgres / Redshift |
| What ETL tool syncs it? | Fivetran / Airbyte / Stitch / HubSpot Data Sync |
| Sync frequency? | Real-time / Hourly / Daily |
| Schema prefix? | `hubspot.` / `raw_hubspot.` / custom |

### 3. Python Environment

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

```python
# 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 | Input | Output | Tools |
|---|----------|-------|--------|-------|
| 1 | ICP Validation | Contact + company data | Segment conversion rates | SQL + Clay |
| 2 | Lead Scoring | Historical deals | Win probability per lead | SQL + ML + API |
| 3 | Competitive Intel | Deal close reasons | Win/loss by competitor | SQL + webhook |
| 4 | Activity Analysis | Engagement data | Activity→outcome correlation | SQL |
| 5 | Pipeline Forecast | Open deals + stage history | Weighted revenue forecast | SQL |

### 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-point