Identify website visitors with Clearbit Reveal and create HubSpot companies using a Claude Code skill

mkdir -p .claude/skills/identify-visitors/{templates,references}

.claude/skills/identify-visitors/
├── SKILL.md                          # workflow guidelines + config
├── templates/
│   └── hubspot-field-mapping.md      # HubSpot property name mapping
└── references/
    ├── clearbit-reveal-api.md        # Clearbit Reveal endpoint + response format
    └── hubspot-companies-api.md      # HubSpot company search + creation

---
name: identify-visitors
description: Resolve website visitor IPs to companies via Clearbit Reveal and create matching companies in HubSpot
disable-model-invocation: true
allowed-tools: Bash, Read
---
 
## Goal
 
Given a log file or CSV of visitor IP addresses, resolve them to companies via Clearbit Reveal, filter for ICP matches, and create new company records in HubSpot.
 
## Configuration
 
Read these environment variables:
 
- `CLEARBIT_API_KEY` — Clearbit Reveal API key (required)
- `HUBSPOT_ACCESS_TOKEN` — HubSpot private app token with companies read/write scopes (required)
 
Default ICP filter: companies with 50+ employees. The user may request a different threshold or additional filters.
 
## Workflow
 
1. Validate that all required env vars are set. If any are missing, print which ones and exit.
2. Extract unique public IPv4 addresses from the input file. Filter out private/reserved ranges (10.x, 172.16-31.x, 192.168.x, 127.x). See `references/clearbit-reveal-api.md` for IP handling notes.
3. For each unique IP, call Clearbit Reveal to resolve it to a company. See `references/clearbit-reveal-api.md` for the endpoint and response format.
4. Deduplicate resolved companies by domain (multiple IPs may resolve to the same company).
5. Filter for ICP matches (default: 50+ employees). Skip companies that don't match.
6. For each ICP-matching company, check if it already exists in HubSpot by domain. See `references/hubspot-companies-api.md`.
7. Create new HubSpot company records using the field mapping in `templates/hubspot-field-mapping.md`.
8. Print a summary: IPs processed, companies resolved, ICP matches, created, already existing.
 
## Important notes
 
- Only 20-30% of B2B visitor IPs resolve to a company. Consumer ISPs, VPNs, and mobile carriers always return null. This is expected.
- Each Clearbit Reveal lookup costs 1 credit regardless of whether it resolves. Log credit usage.
- Clearbit returns 404 for unresolvable IPs — handle this gracefully, don't treat it as an error.
- The `company.type` field must equal `"company"` — filter out ISPs and educational institutions.
- HubSpot uses `numberofemployees` (no underscore) as the property name for employee count.
- Add a 100ms delay between Clearbit API calls to respect rate limits.
- Use `urllib.request` for HTTP calls (no external dependencies required).

# Clearbit Reveal API Reference
 
## Resolve an IP to a company
 
**Request:**
 
```
GET https://reveal.clearbit.com/v1/companies/find
Authorization: Bearer <CLEARBIT_API_KEY>
```
 
**Query parameter:** `ip=203.0.113.42`
 
**Response shape (success):**
 
```json
{
  "ip": "203.0.113.42",
  "company": {
    "id": "abc123",
    "name": "Acme Corp",
    "domain": "acmecorp.com",
    "type": "company",
    "category": {
      "industry": "Software",
      "sector": "Technology"
    },
    "metrics": {
      "employees": 350,
      "raised": 45000000
    },
    "geo": {
      "city": "San Francisco",
      "state": "California",
      "country": "United States"
    },
    "description": "Enterprise software company..."
  }
}
```
 
**Response (unresolvable IP):** HTTP 404
 
## Notes
 
- Only 20-30% of B2B IPs resolve. Consumer ISPs, VPNs, and mobile carriers return 404.
- Check `company.type` equals `"company"` — ISPs and educational institutions have different types.
- Each lookup costs 1 credit regardless of whether it resolves.
- Rate limit: ~10 requests/second. Add 100ms delay between calls.
- `company.metrics.employees` may be null for very small companies.
- Private/reserved IP ranges never resolve: 10.x, 172.16-31.x, 192.168.x, 127.x — filter these before calling the API.

# HubSpot Companies API Reference
 
## Search companies by domain (deduplication)
 
```
POST https://api.hubapi.com/crm/v3/objects/companies/search
Authorization: Bearer <HUBSPOT_ACCESS_TOKEN>
Content-Type: application/json
```
 
Body:
```json
{
  "filterGroups": [{"filters": [{
    "propertyName": "domain",
    "operator": "EQ",
    "value": "acmecorp.com"
  }]}]
}
```
 
Returns `results` array — if length > 0, company exists.
 
## Create a company
 
```
POST https://api.hubapi.com/crm/v3/objects/companies
Authorization: Bearer <HUBSPOT_ACCESS_TOKEN>
Content-Type: application/json
```
 
Body:
```json
{
  "properties": {
    "domain": "acmecorp.com",
    "name": "Acme Corp",
    "industry": "Software",
    "numberofemployees": "350",
    "city": "San Francisco",
    "state": "California",
    "country": "United States",
    "description": "Enterprise software company..."
  }
}
```
 
**Important:** `numberofemployees` must be a string, not a number. HubSpot rejects numeric values for this property.
 
## Notes
 
- HubSpot allows 150 requests per 10 seconds for general API calls and 5 per second for search.
- Company domain search is case-insensitive.
- For batch creation (100+ companies), use the batch endpoint: POST /crm/v3/objects/companies/batch/create.

# HubSpot Field Mapping
 
Map Clearbit Reveal fields to HubSpot company properties:
 
| Clearbit field | HubSpot property | Notes |
|---|---|---|
| `company.domain` | `domain` | Required — skip if null |
| `company.name` | `name` | Required |
| `company.category.industry` | `industry` | May be null |
| `company.metrics.employees` | `numberofemployees` | Must be string, not number |
| `company.geo.city` | `city` | May be null |
| `company.geo.state` | `state` | May be null |
| `company.geo.country` | `country` | May be null |
| `company.description` | `description` | May be null |
 
**Optional custom properties** (must be created in HubSpot first):
- `website_visitor_source` — set to "Clearbit Reveal"
- `website_visitor_date` — date of the visitor identification

/identify-visitors /var/log/nginx/access.log

Found 847 unique public IPs
 
Resolving IPs via Clearbit Reveal...
  Resolved: 203 companies (24% match rate)
  Deduplicated: 156 unique companies
 
Filtering for ICP (50+ employees)...
  ICP matches: 42 companies
 
Creating HubSpot records...
  CREATED: Acme Corp — 350 employees
  CREATED: NovaTech Industries — 2,000 employees
  EXISTS: Meridian Systems (already in HubSpot)
  CREATED: Apex Digital — 180 employees
  ...
 
--- Summary ---
IPs processed: 847
Companies resolved: 203 (24%)
ICP matches: 42
Created in HubSpot: 38
Already in HubSpot: 4
Clearbit credits used: 847

# Run daily at 7 AM to process yesterday's logs
0 7 * * * cd /path/to/your/project && claude -p "Run /identify-visitors /var/log/nginx/access.log.1" --allowedTools 'Bash(*)' 'Read(*)'

name: Identify Website Visitors
on:
  schedule:
    - cron: '0 8 * * *'  # Daily at 8 AM UTC
  workflow_dispatch: {}
jobs:
  identify:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Download logs
        run: aws s3 cp s3://your-bucket/logs/access.log /tmp/access.log
        env:
          AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
          AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
      - uses: anthropics/claude-code-action@v1
        with:
          prompt: "Run /identify-visitors /tmp/access.log"
          allowed_tools: "Bash(*),Read(*)"
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
          CLEARBIT_API_KEY: ${{ secrets.CLEARBIT_API_KEY }}
          HUBSPOT_ACCESS_TOKEN: ${{ secrets.HUBSPOT_ACCESS_TOKEN }}