Back to Details

hubspot-revops-skill

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese
<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>
<objective> 基于HubSpot API + SQL数据仓库构建收入分析基础设施。涵盖ICP验证、ML线索评分、竞争情报、活动分析以及销售管道预测——将CRM数据转化为可落地的智能产品。 </objective>
<quick_start>
  1. 创建具备所需CRM权限范围（联系人、公司、交易、负责人、时间线）的HubSpot私有应用
  2. 确认数据仓库的SQL副本访问权限和架构前缀
  3. 运行ICP验证查询（UC1）以细分转化率
  4. 利用各阶段历史赢单率构建销售管道预测（UC5） </quick_start>
<success_criteria>
  • HubSpot私有应用已通过所有必要权限范围的认证
  • SQL数据仓库已连接，且数据新鲜度已验证（同步延迟<24小时）
  • 至少一个用例（ICP、评分、竞争情报、活动分析、预测）已产出结果
  • 线索评分模型基于200+历史已结交易训练，且具备可衡量的AUC值
  • Enrichment管道可将评分写回HubSpot，且无重复数据 </success_criteria>

HubSpot RevOps Analytics

HubSpot RevOps收入分析

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
.
基于HubSpot API + SQL数据仓库的收入分析基础设施。打通CRM数据→分析→智能产品→收入影响的全链路。
适用范围： HubSpot专属分析栈。如需基础CRM增删改查操作，请使用
crm-integration-skill
。如需通用仪表板，请使用
data-analysis-skill
。

Setup Checklist

配置检查清单

1. HubSpot Private App

1. HubSpot私有应用

Create at Settings → Integrations → Private Apps:
ScopePermissionWhy
crm.objects.contacts.read/write
Read/WriteContact enrichment
crm.objects.companies.read
ReadCompany data
crm.objects.deals.read/write
Read/WritePipeline analytics
crm.schemas.custom.read
ReadCustom objects
crm.objects.owners.read
ReadRep attribution
timeline
ReadActivity data
在设置→集成→私有应用中创建：
权限范围权限原因
crm.objects.contacts.read/write
读/写联系人Enrichment
crm.objects.companies.read
读公司数据获取
crm.objects.deals.read/write
读/写销售管道分析
crm.schemas.custom.read
读自定义对象访问
crm.objects.owners.read
读销售代表归因
timeline
读活动数据获取

2. SQL Replica Access

2. SQL副本访问

Discovery questions for your data warehouse:
QuestionOptions
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
针对数据仓库的调研问题：
问题选项
HubSpot数据复制到哪里？Snowflake / BigQuery / Postgres / Redshift
使用什么ETL工具同步？Fivetran / Airbyte / Stitch / HubSpot Data Sync
同步频率？实时 / 每小时 / 每日
架构前缀？
hubspot.
/ 
raw_hubspot.
/ 自定义

3. Python Environment

3. Python环境

bash
pip install hubspot-api-client pandas scikit-learn requests
python
undefined
bash
pip install hubspot-api-client pandas scikit-learn requests
python
undefined

SDK initialization

SDK初始化

from hubspot import HubSpot client = HubSpot(access_token="pat-na1-xxxxx")
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"

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

---

Core Use Cases

核心用例

#Use CaseInputOutputTools
1ICP ValidationContact + company dataSegment conversion ratesSQL + Clay
2Lead ScoringHistorical dealsWin probability per leadSQL + ML + API
3Competitive IntelDeal close reasonsWin/loss by competitorSQL + webhook
4Activity AnalysisEngagement dataActivity→outcome correlationSQL
5Pipeline ForecastOpen deals + stage historyWeighted revenue forecastSQL
#用例输入输出工具
1ICP验证联系人+公司数据细分转化率SQL + Clay
2线索评分历史交易数据每条线索的赢单概率SQL + ML + API
3竞争情报交易关闭原因按竞争对手统计赢/输单情况SQL + webhook
4活动分析互动数据活动与结果的相关性SQL
5销售管道预测未结交易+阶段历史数据加权收入预测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 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.
UC1 — ICP验证： 在SQL中关联联系人+公司+交易数据，按行业/规模/地域细分，计算各细分群体的转化率。将结果导入Clay以完成Enrichment并写回HubSpot。
UC2 — 线索评分： 基于历史赢单/输单交易训练GradientBoostingClassifier模型。特征包括：公司规模、行业、互动评分、销售管道停留天数。将评分作为自定义属性通过API部署到HubSpot。
UC3 — 竞争情报： 从交易的
closed_lost_reason
字段提取竞争对手提及信息。构建按竞争对手划分的赢/输单矩阵。针对竞争对手替代模式设置webhook告警。
UC4 — 活动分析： 将邮件打开、会议预约、通话记录等互动数据与交易结果关联，识别真正能推动交易进展的活动类型。
UC5 — 销售管道预测： 利用各阶段历史赢单率计算加权预测值。同时考虑交易时长、推进速度和销售代表绩效。
参考： 各用例完整SQL模板请查看
reference/sql-analytics.md
。

Quick Reference: HubSpot API Endpoints

快速参考：HubSpot API端点

ObjectEndpointKey Operations
Contacts
/crm/v3/objects/contacts
Search, create, update, batch
Companies
/crm/v3/objects/companies
Search, associate to contacts
Deals
/crm/v3/objects/deals
Pipeline, stage history
Engagements
/crm/v3/objects/engagements
Emails, calls, meetings
Properties
/crm/v3/properties/{object}
Custom property CRUD
Associations
/crm/v4/associations/{from}/{to}
Object linking
Search
/crm/v3/objects/{object}/search
Filter + sort (max 10k)
Reference: See 
reference/api-guide.md
for auth, SDK patterns, batch operations.
对象端点核心操作
Contacts
/crm/v3/objects/contacts
搜索、创建、更新、批量操作
Companies
/crm/v3/objects/companies
搜索、与联系人关联
Deals
/crm/v3/objects/deals
销售管道、阶段历史
Engagements
/crm/v3/objects/engagements
邮件、通话、会议
Properties
/crm/v3/properties/{object}
自定义属性增删改查
Associations
/crm/v4/associations/{from}/{to}
对象关联
Search
/crm/v3/objects/{object}/search
筛选+排序（最多10k条结果）
参考： 认证、SDK模式、批量操作详情请查看
reference/api-guide.md
。

Quick Reference: SQL Object Model

快速参考：SQL对象模型

HubSpot ObjectSQL Table (typical)Key ColumnsJoin Key
Contacts
hubspot.contacts
email, lifecycle_stage, lead_scorecontact_id
Companies
hubspot.companies
domain, industry, employee_countcompany_id
Deals
hubspot.deals
amount, stage, close_date, pipelinedeal_id
Deal Stages
hubspot.deal_stage_history
stage, timestamp, durationdeal_id
Engagements
hubspot.engagements
type, created_at, contact_idengagement_id
Owners
hubspot.owners
email, first_name, teamowner_id
Join pattern: contacts → associations → companies/deals (via association tables)
HubSpot对象典型SQL表核心字段关联键
Contacts
hubspot.contacts
email, lifecycle_stage, lead_scorecontact_id
Companies
hubspot.companies
domain, industry, employee_countcompany_id
Deals
hubspot.deals
amount, stage, close_date, pipelinedeal_id
Deal Stages
hubspot.deal_stage_history
stage, timestamp, durationdeal_id
Engagements
hubspot.engagements
type, created_at, contact_idengagement_id
Owners
hubspot.owners
email, first_name, teamowner_id
关联模式： contacts → associations → companies/deals（通过关联表）

Integration Points

集成点

SkillRelationship
crm-integration-skill
Base CRUD patterns, auth setup
data-analysis-skill
Visualization, Streamlit dashboards
sales-revenue-skill
Pipeline metrics, MEDDIC context, forecasting
research-skill
Market/competitive research methodology
cost-metering-skill
Track API calls + Clay enrichment spend
Skill关系
crm-integration-skill
基础增删改查模式、认证设置
data-analysis-skill
可视化、Streamlit仪表板
sales-revenue-skill
销售管道指标、MEDDIC框架、预测
research-skill
市场/竞争研究方法论
cost-metering-skill
追踪API调用+Clay Enrichment成本

Common Mistakes

常见错误

MistakeFix
Exceeding 100 requests/10s rate limitUse batch endpoints, add exponential backoff
Using Search API for >10k resultsSwitch to SQL warehouse for bulk analytics
Hardcoded property internal namesFetch property definitions first: 
GET /crm/v3/properties/{object}
Missing association API for object linksUse v4 associations: 
POST /crm/v4/associations/{from}/{to}/batch/read
SQL 
DATEDIFF
in Postgres		Use 
AGE()
or 
EXTRACT(EPOCH FROM ...)
— see dialect notes
Not handling HubSpot's 
hs_object_id
Always include 
hs_object_id
in property requests
Clay enrichment without dedupCheck existing property values before writeback
Scoring model trained on small datasetNeed 200+ closed deals minimum for reliable ML scores
错误修复方案
超过100请求/10秒的速率限制使用批量端点，添加指数退避机制
对>10k条结果使用Search API切换到SQL数据仓库进行批量分析
硬编码属性内部名称先获取属性定义：
GET /crm/v3/properties/{object}
对象关联时缺少Association API使用v4关联接口：
POST /crm/v4/associations/{from}/{to}/batch/read
Postgres中使用SQL 
DATEDIFF
使用
AGE()
或
EXTRACT(EPOCH FROM ...)
——查看方言说明
未处理HubSpot的
hs_object_id
在属性请求中始终包含
hs_object_id
Clay Enrichment未去重写回前检查现有属性值
评分模型基于小数据集训练至少需要200+已结交易才能获得可靠的ML评分

Workflow Phases

工作流阶段

Phase 1: Foundation

阶段1：基础搭建

  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)
  1. 设置具备所需权限范围的私有应用
  2. 确认SQL副本访问权限和架构
  3. 运行架构发现查询
  4. 验证数据新鲜度（同步延迟）

Phase 2: Analytics

阶段2：分析构建

  1. Build ICP validation queries (UC1)
  2. Create pipeline velocity dashboard (UC2, UC5)
  3. Set up competitive intelligence tracking (UC3)
  1. 构建ICP验证查询（UC1）
  2. 创建销售管道速度仪表板（UC2、UC5）
  3. 设置竞争情报追踪（UC3）

Phase 3: Intelligence

阶段3：智能落地

  1. Train lead scoring model on historical deals
  2. Deploy scores to HubSpot via API
  3. Build enrichment pipelines (Clay → HubSpot)
  4. 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.
  1. 基于历史交易训练线索评分模型
  2. 通过API将评分部署到HubSpot
  3. 构建Enrichment管道（Clay → HubSpot）
  4. 设置自动化告警和webhook
参考： ML评分和Clay集成详情请查看
reference/enrichment-pipelines.md
。 参考： 部署模式和成本估算请查看
reference/architecture.md
。