/hubspot-enrichment-scoring

name: hubspot-enrichment-scoring
description: "HubSpot CRM enrichment and lead scoring skill for Claude Code and Codex: pull companies from HubSpot, match and enrich them via Vibe Prospecting with firmographics, tech stack, funding history, and intent signals, compute an ICP fit score (0-100) and A/B/C tier, and write everything back to HubSpot as custom properties. Use for CRM enrichment, account scoring, and segmentation prep. Triggers on 'enrich my HubSpot', 'score my HubSpot companies', 'CRM enrichment', 'write ICP scores to HubSpot'. Works in Claude Code, Codex, Grok, and Claude Cowork."
compatibility: "Requires: Vibe Prospecting CLI (npx @vibeprospecting/vpai@latest) or connector, HubSpot Private App token with crm.objects.companies.read/write scopes"

HubSpot Enrichment & Scoring

Enrich your HubSpot CRM with Explorium data and write ICP fit scores directly back to your records. Claude runs the full pipeline: pull from HubSpot → match & enrich via Vibe Prospecting → score → push back.

**What you'll end up with:**

• Enriched company records: firmographics, tech stack, funding history, intent signals
• An ICP fit score (0–100) and tier (A/B/C) on every company
• All of it written back to HubSpot as custom properties, ready for segmentation and sequencing

---

Step 0 — Credential Check (Claude: always do this first)

Do not touch Phase 1 until both checks pass.

Vibe Prospecting

**Cowork mode:** look for a tool matching `mcp__*__fetch-entities` in your tool list.

• ✅ Found → proceed
• ❌ Missing → tell the user: *"Please connect the Vibe Prospecting connector from the connector store, then let me know when it's done."* Wait. Do not continue until the tool appears.

**Claude Code / terminal:**

npx @vibeprospecting/vpai@latest --help

• ✅ Lists tools → proceed
• ❌ Error → run: `npx @vibeprospecting/vpai@latest config --api-key "YOUR_VP_API_KEY"` (get key from vibeprospecting.com → Settings → API Keys)

HubSpot Token

Ask the user: *"Please paste your HubSpot Private App token (starts with `pat-`). I'll verify it and we'll get started."*

**Don't have one yet?** Create it in HubSpot → Settings → Integrations → Private Apps → Create a private app. Enable scopes: `crm.objects.companies.read`, `crm.objects.companies.write`. Click Create and copy the token.

Once the user provides the token, verify it:

export HUBSPOT_TOKEN="<token-from-user>"

curl -s "https://api.hubapi.com/crm/v3/objects/companies?limit=1" \
  -H "Authorization: Bearer $HUBSPOT_TOKEN" \
  | python3 -c "
import json, sys
d = json.load(sys.stdin)
print('✅ Connected') if d.get('results') is not None else print('❌ Failed:', d.get('message','unknown error'))
"

• ✅ Connected → tell the user *"Both credentials verified — let's go."* Proceed to Phase 1.
• ❌ Failed → tell the user the token didn't work, ask them to check the scopes and try again. Do not proceed.

> The token lives only in the session environment variable. It is never stored or logged.

---

Phase 1 — Pull Companies from HubSpot

Export your HubSpot company records. The match keys are `name` and `domain` — domain is the more reliable one.

**For up to 100 companies:**

curl -s "https://api.hubapi.com/crm/v3/objects/companies?limit=100&properties=name,domain,hs_object_id,lifecyclestage,numberofemployees,annualrevenue,industry" \
  -H "Authorization: Bearer $HUBSPOT_TOKEN" \
  | python3 -c "
import json, sys, csv

data = json.load(sys.stdin)
fields = ['hs_object_id','name','domain','lifecyclestage','numberofemployees','annualrevenue','industry']
w = csv.DictWriter(sys.stdout, fieldnames=fields, extrasaction='ignore')
w.writeheader()
for r in data['results']:
    row = {'hs_object_id': r['id']}
    row.update(r['properties'])
    w.writerow(row)
" > hs-companies-raw.csv

echo "Exported $(wc -l < hs-companies-raw.csv) rows"

**For larger exports (paginated):**

import csv, os, requests

TOKEN = os.environ["HUBSPOT_TOKEN"]
HEADERS = {"Authorization": f"Bearer {TOKEN}"}
PROPS = "name,domain,hs_object_id,lifecyclestage,numberofemployees,annualrevenue,industry"
FIELDS = ['hs_object_id','name','domain','lifecyclestage','numberofemployees','annualrevenue','industry']

rows, params = [], {"limit": 100, "properties": PROPS}
while True:
    resp = requests.get("https://api.hubapi.com/crm/v3/objects/companies", headers=HEADERS, params=params)
    resp.raise_for_status()
    data = resp.json()
    for r in data["results"]:
        row = {"hs_object_id": r["id"]}
        row.update(r["properties"])
        rows.append(row)
    after = data.get("paging", {}).get("next", {}).get("after")
    if not after:
        break
    params["after"] = after

with open("hs-companies-raw.csv", "w", newline="") as f:
    w = csv.DictWriter(f, fieldnames=FIELDS, extrasaction="ignore")
    w.writeheader()
    w.writerows(rows)

print(f"Exported {len(rows)} companies")

**Tips:**

• If many records are missing `domain`, clean those in HubSpot before running this skill — domain is the primary match key and missing domains won't match.
• To enrich only a subset (e.g. leads and MQLs), filter `lifecyclestage` after export before passing to Phase 2.

**Output:** `hs-companies-raw.csv`

> **Starting from scratch with no existing HubSpot records?** Skip to Phase 2 and use `fetch-entities` to build a net-new account list from your ICP, then push those as new HubSpot companies in Phase 5.

---

Phase 2 — Match to Vibe Prospecting IDs

Resolve company names and domains to Explorium business IDs. These IDs are required for all enrichment steps.

# Always check schema before first use
npx @vibeprospecting/vpai@latest match-business --all-parameters

# Match from the exported CSV
npx @vibeprospecting/vpai@latest match-business \
  --file-path hs-companies-raw.csv \
  --schema '{"name":"name","domain":"domain"}' \
  --tool-reasoning 'Match HubSpot companies to Vibe Prospecting IDs for enrichment'

Note the `session_id` and `tab