Enrich HubSpot companies with technographic data from BuiltWith using a Claude Code skill

mkdir -p .claude/skills/tech-enrich/{templates,references}

---
name: tech-enrich
description: Looks up what technologies HubSpot companies use via BuiltWith. Categorizes technologies into CRM, marketing, and analytics stacks and writes them to custom HubSpot company properties.
disable-model-invocation: true
allowed-tools: Bash, Read
---
 
## Workflow
 
1. Read `references/builtwith-api.md` for the BuiltWith lookup API
2. Read `references/hubspot-companies-api.md` for HubSpot search and update patterns
3. Read `templates/category-mapping.md` for the technology categorization rules
4. Search HubSpot for companies where tech_stack_crm has no value (NOT_HAS_PROPERTY)
5. For each company with a domain, call BuiltWith API with the domain
6. Parse the deeply nested response: Results[0].Result.Paths[0].Technologies[]
7. Categorize each technology into CRM, marketing, analytics, or other using the mapping rules
8. PATCH each company in HubSpot with categorized tech stacks and tech_enrichment_date
9. Print a summary: companies processed, enriched, skipped (no domain or no tech data)
 
## Rules
 
- Skip companies without a domain property — BuiltWith requires a domain
- Rate limit: 2 seconds between BuiltWith API calls
- Always set tech_enrichment_date on enriched companies
- Use environment variables: HUBSPOT_ACCESS_TOKEN, BUILTWITH_API_KEY
- BuiltWith credits are expensive (~$0.59/lookup on Pro) — keep batch sizes reasonable

# BuiltWith API Reference
 
## Look up technologies for a domain
 
```
GET https://api.builtwith.com/v21/api.json?KEY={BUILTWITH_API_KEY}&LOOKUP={domain}
```
 
Response structure (deeply nested):
```json
{
  "Results": [
    {
      "Result": {
        "Paths": [
          {
            "Technologies": [
              {
                "Name": "Salesforce",
                "Tag": "crm",
                "Categories": ["CRM", "Customer Relationship Management"]
              },
              {
                "Name": "Google Analytics",
                "Tag": "analytics",
                "Categories": ["Analytics", "Web Analytics"]
              }
            ]
          }
        ]
      }
    }
  ]
}
```
 
Key behaviors:
- Domain should be bare (e.g., "acme.com"), not a full URL
- If the domain isn't recognized, Results may be empty or Paths may have no Technologies
- Each Technology has a Name, Tag (category identifier), and Categories array
- Always use optional chaining at every nesting level: Results?.[0]?.Result?.Paths?.[0]?.Technologies
- Rate limit varies by plan — use 2-second delay between calls on Pro plan
- Pro plan: 500 calls/month ($295/mo). Enterprise: 2,000 calls/month ($495/mo)

# HubSpot Companies API Reference
 
## Search for companies missing tech data
 
```
POST https://api.hubapi.com/crm/v3/objects/companies/search
Authorization: Bearer {HUBSPOT_ACCESS_TOKEN}
Content-Type: application/json
```
 
Request body:
```json
{
  "filterGroups": [{
    "filters": [{
      "propertyName": "tech_stack_crm",
      "operator": "NOT_HAS_PROPERTY"
    }]
  }],
  "properties": ["domain", "name"],
  "limit": 50,
  "after": 0
}
```
 
Response:
```json
{
  "results": [
    {
      "id": "456",
      "properties": {
        "domain": "acme.com",
        "name": "Acme Inc"
      }
    }
  ],
  "paging": { "next": { "after": "50" } }
}
```
 
Pagination: continue with `after` value until `paging.next` is absent.
 
## Update a company
 
```
PATCH https://api.hubapi.com/crm/v3/objects/companies/{companyId}
Authorization: Bearer {HUBSPOT_ACCESS_TOKEN}
Content-Type: application/json
```
 
Request body:
```json
{
  "properties": {
    "tech_stack_crm": "Salesforce, HubSpot",
    "tech_stack_marketing": "Marketo, Mailchimp",
    "tech_stack_analytics": "Google Analytics, Mixpanel",
    "tech_stack_all": "Salesforce, HubSpot, Marketo, ...",
    "tech_enrichment_date": "2026-03-05"
  }
}
```
 
Custom properties must be created in HubSpot first:
- tech_stack_crm (single-line text)
- tech_stack_marketing (single-line text)
- tech_stack_analytics (single-line text)
- tech_stack_all (multi-line text)
- tech_enrichment_date (date, YYYY-MM-DD format)

# Technology Category Mapping
 
## Category rules
 
Map each technology to a category based on its Tag and Categories fields:
 
| Category | Tag patterns | Example technologies |
|---|---|---|
| CRM | crm, customer-relationship | Salesforce, HubSpot, Zoho CRM |
| Marketing | marketing-automation, email, marketing | Marketo, Pardot, Mailchimp, ActiveCampaign |
| Analytics | analytics, web-analytics | Google Analytics, Mixpanel, Amplitude, Hotjar |
| E-commerce | ecommerce, shopping-cart, payment | Shopify, WooCommerce, Stripe, PayPal |
| Hosting | hosting, cdn, cloud-paas | AWS, Cloudflare, Vercel, Netlify |
 
## Matching logic
 
1. Convert the Tag to lowercase
2. Check if any category pattern is a substring of the Tag
3. Also check the Categories array (lowercase) for pattern matches
4. If a technology matches multiple categories, assign it to the first match
5. Technologies that don't match any category are included in tech_stack_all but not in specific category fields
 
## HubSpot property values
 
- If a category has matches: join technology names with ", " (e.g., "Salesforce, HubSpot")
- If a category has no matches: write "None detected"
- tech_stack_all: join ALL technology names regardless of category

# In Claude Code
/tech-enrich

# Run weekly on Sunday at 10 PM
0 22 * * 0 cd /path/to/project && claude -p "Run /tech-enrich for companies without tech data. Limit to 50." --allowedTools 'Bash,Read' 2>&1 >> /var/log/tech-enrich.log

name: Technographic Enrichment
on:
  schedule:
    - cron: '0 3 * * 0'  # Weekly Sunday 3 AM UTC
  workflow_dispatch: {}
jobs:
  enrich:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: anthropics/claude-code-action@v1
        with:
          prompt: "Run /tech-enrich for companies without tech data. Limit to 50."
          allowed_tools: "Bash,Read"
        env:
          HUBSPOT_ACCESS_TOKEN: ${{ secrets.HUBSPOT_ACCESS_TOKEN }}
          BUILTWITH_API_KEY: ${{ secrets.BUILTWITH_API_KEY }}