Batch enrich HubSpot contacts missing job title or company size using a Claude Code skill

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

---
name: batch-enrich
description: Finds HubSpot contacts missing critical fields (job title, company, phone) and batch-enriches them via Apollo. Only fills empty fields — never overwrites existing data.
disable-model-invocation: true
allowed-tools: Bash, Read
---
 
## Workflow
 
1. Read `references/hubspot-contacts-api.md` for Search API patterns
2. Read `references/apollo-bulk-match-api.md` for bulk enrichment patterns
3. Read `templates/field-mapping.md` for field mapping rules
4. Search HubSpot for contacts missing the requested field (default: jobtitle) using NOT_HAS_PROPERTY
5. Filter to business emails only (exclude gmail.com, yahoo.com, hotmail.com, outlook.com, aol.com)
6. Batch contacts into groups of 10 and call Apollo's bulk_match endpoint for each batch
7. For each match, build an update payload using ONLY fields that are currently empty on the contact
8. PATCH each contact in HubSpot with the enrichment data plus enrichment_date and enrichment_source metadata
9. Print a summary: total searched, matched, enriched, and fields filled
 
## Rules
 
- NEVER overwrite existing field values — only fill fields that are null/empty
- Always set enrichment_date (YYYY-MM-DD) and enrichment_source ("apollo-batch") on every updated contact
- Rate limit: 1 second between Apollo bulk_match calls, 200ms between HubSpot paginated searches
- Filter out personal email domains before calling Apollo to save credits
- Use environment variables: HUBSPOT_ACCESS_TOKEN, APOLLO_API_KEY

# HubSpot Contacts API Reference
 
## Search for contacts missing fields
 
```
POST https://api.hubapi.com/crm/v3/objects/contacts/search
Authorization: Bearer {HUBSPOT_ACCESS_TOKEN}
Content-Type: application/json
```
 
Request body — find contacts where jobtitle is not set:
```json
{
  "filterGroups": [{
    "filters": [{
      "propertyName": "jobtitle",
      "operator": "NOT_HAS_PROPERTY"
    }]
  }],
  "properties": ["email", "firstname", "lastname", "jobtitle", "company", "phone", "linkedin_url", "industry"],
  "limit": 100,
  "after": 0
}
```
 
Response:
```json
{
  "results": [
    {
      "id": "123",
      "properties": {
        "email": "jane@acme.com",
        "firstname": "Jane",
        "lastname": "Smith",
        "jobtitle": null,
        "company": "Acme Inc"
      }
    }
  ],
  "paging": { "next": { "after": "100" } }
}
```
 
Pagination: continue calling with `after` value until `paging.next` is absent. Rate limit: 5 req/sec, add 200ms delay between pages.
 
Multiple missing fields: use separate `filterGroups` (OR logic) to find contacts missing ANY of several fields.
 
## Update a contact
 
```
PATCH https://api.hubapi.com/crm/v3/objects/contacts/{contactId}
Authorization: Bearer {HUBSPOT_ACCESS_TOKEN}
Content-Type: application/json
```
 
Request body:
```json
{
  "properties": {
    "jobtitle": "Director of Marketing",
    "enrichment_date": "2026-03-05",
    "enrichment_source": "apollo-batch"
  }
}
```
 
Rate limit: 150 req/10 sec. No delay needed for batches under 150 contacts.
 
Note: NOT_HAS_PROPERTY matches contacts where the property was never set. Empty string values are considered "set" and won't match. To catch both, combine NOT_HAS_PROPERTY with EQ '' using separate filterGroups.

# Apollo Bulk Match API Reference
 
## Bulk match people by email
 
```
POST https://api.apollo.io/api/v1/people/bulk_match
x-api-key: {APOLLO_API_KEY}
Content-Type: application/json
```
 
Request body (up to 10 records per request):
```json
{
  "details": [
    { "email": "jane@acme.com" },
    { "email": "bob@widgets.co" }
  ]
}
```
 
Response:
```json
{
  "matches": [
    {
      "title": "Director of Marketing",
      "organization": {
        "name": "Acme Inc",
        "industry": "Computer Software",
        "estimated_num_employees": 250
      },
      "phone_numbers": [
        { "sanitized_number": "+12125550198", "type": "work_direct" }
      ],
      "linkedin_url": "https://www.linkedin.com/in/janesmith"
    },
    null
  ]
}
```
 
Key behaviors:
- matches array is in the same order as the input details array
- Unmatched emails return null at their index position
- Maximum 10 records per request
- 1 credit per person in the request (even for null results)
- Rate limit: 5 req/sec on Basic plan — add 1 second delay between bulk calls
 
The individual match endpoint (POST /api/v1/people/match) accepts a single person with email, first_name, last_name, or organization_name. Use bulk_match for batch processing.

# Field Mapping: Apollo → HubSpot
 
## Mapping rules
 
| Apollo field | HubSpot property | Notes |
|---|---|---|
| title | jobtitle | Job title |
| organization.name | company | Company name |
| phone_numbers[0].sanitized_number | phone | Primary phone |
| linkedin_url | linkedin_url | LinkedIn profile URL |
| organization.industry | industry | Industry classification |
| organization.estimated_num_employees | numemployees | Employee count range |
 
## Update rules
 
1. ONLY update a HubSpot field if its current value is null/empty
2. If the contact already has a value for a field, skip it — even if Apollo has a different value
3. Always add these metadata fields to every updated contact:
   - enrichment_date: current date in YYYY-MM-DD format
   - enrichment_source: "apollo-batch"
4. Set enrichment_date even on contacts where Apollo returned null (to exclude from future runs)
 
## Personal email domains to skip
 
Do not send these domains to Apollo (wastes credits, near-zero B2B match rate):
gmail.com, yahoo.com, hotmail.com, outlook.com, aol.com, protonmail.com, icloud.com, me.com, live.com

# In Claude Code
/batch-enrich

# Run weekly on Sunday at 10 PM
0 22 * * 0 cd /path/to/project && claude -p "Run /batch-enrich for all contacts missing job titles. Limit to 200." --allowedTools 'Bash,Read' 2>&1 >> /var/log/batch-enrich.log

name: Weekly Batch Enrichment
on:
  schedule:
    - cron: '0 3 * * 0'  # 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 /batch-enrich for all contacts missing job titles. Limit to 200."
          allowed_tools: "Bash,Read"
        env:
          HUBSPOT_ACCESS_TOKEN: ${{ secrets.HUBSPOT_ACCESS_TOKEN }}
          APOLLO_API_KEY: ${{ secrets.APOLLO_API_KEY }}