Find decision makers at a HubSpot company using Apollo and a Claude Code skill

mkdir -p .claude/skills/find-decision-makers/{templates,references}

.claude/skills/find-decision-makers/
├── SKILL.md                          # workflow guidelines + config
├── templates/
│   └── hubspot-field-mapping.md      # HubSpot property name mapping
└── references/
    ├── apollo-people-api.md          # Apollo People Search + Match endpoints
    └── hubspot-contacts-api.md       # HubSpot company lookup, contact creation, associations

---
name: find-decision-makers
description: Find VP+ decision makers at a target HubSpot company using Apollo, enrich them, and create associated contacts
disable-model-invocation: true
allowed-tools: Bash, Read
---
 
## Goal
 
Given a target company (by name or HubSpot ID), find VP+/C-suite decision makers via Apollo's People Search API, enrich them for verified emails, and create associated contacts in HubSpot.
 
## Configuration
 
Read these environment variables:
 
- `HUBSPOT_ACCESS_TOKEN` — HubSpot private app token with contacts read/write and companies read scopes (required)
- `APOLLO_API_KEY` — Apollo API key for People Search and People Match (required)
 
Default target titles: VP Sales, CRO, VP Marketing, CMO, VP RevOps, Head of Sales, VP Engineering, CTO
Default seniorities: vp, c_suite, director
The user may request different titles or departments.
 
## Workflow
 
1. Validate that all required env vars are set. If any are missing, print which ones and exit.
2. Look up the target company in HubSpot by ID or name search. Get the company's domain and record ID. See `references/hubspot-contacts-api.md`.
3. If the company has no domain, print an error and exit (Apollo requires a domain to search).
4. Search Apollo for decision makers at that domain, filtered by target titles and seniorities. See `references/apollo-people-api.md`.
5. For each person found, enrich via Apollo People Match to get a verified email. Skip people without verified emails.
6. For each enriched person, check if a HubSpot contact with that email already exists. If yes, skip creation but still associate.
7. Create new HubSpot contacts using the field mapping in `templates/hubspot-field-mapping.md`.
8. Associate each contact (new or existing) with the target company.
9. Print a summary of how many contacts were found, created, and associated.
 
## Important notes
 
- Apollo People Search costs 1 credit per result returned. People Match costs 1 additional credit per call. Log credit usage.
- Apollo rate limits are ~5 requests/second. Add a 200ms delay between API calls.
- HubSpot uses internal property names: `firstname` (not first_name), `jobtitle` (not job_title). See the field mapping template.
- Apollo People Match returns a single person under the `person` key (singular), not `people` (plural).
- Some contacts may have left the company — Apollo will return null email for these. Skip them.
- Use `urllib.request` for HTTP calls (no external dependencies required).
- Use `requests` library if available, but don't fail if it's not installed — fall back to urllib.

# Apollo People API Reference
 
## People Search
 
Find people at a company by domain, titles, and seniority.
 
**Request:**
 
```
POST https://api.apollo.io/api/v1/mixed_people/search
Content-Type: application/json
X-Api-Key: <APOLLO_API_KEY>
```
 
**Body:**
 
```json
{
  "q_organization_domains_list": ["targetco.com"],
  "person_titles": ["VP Sales", "CRO", "VP Marketing", "CMO"],
  "person_seniorities": ["vp", "c_suite", "director"],
  "page": 1,
  "per_page": 25
}
```
 
**Response shape:**
 
```json
{
  "people": [
    {
      "id": "abc123",
      "first_name": "Sarah",
      "last_name": "Chen",
      "title": "VP of Engineering",
      "organization": {
        "name": "TargetCo",
        "primary_domain": "targetco.com"
      },
      "email": null
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 25,
    "total_entries": 8
  }
}
```
 
**Notes:**
- Costs 1 credit per result returned.
- Email in search results is often null — use People Match for verified emails.
- Rate limit: ~5 requests/second. Add 200ms delay between calls.
 
## People Match (Enrichment)
 
Get verified email for a specific person.
 
**Request:**
 
```
POST https://api.apollo.io/api/v1/people/match
Content-Type: application/json
X-Api-Key: <APOLLO_API_KEY>
```
 
**Body:**
 
```json
{
  "first_name": "Sarah",
  "last_name": "Chen",
  "organization_name": "TargetCo",
  "reveal_personal_emails": false
}
```
 
**Response shape:**
 
```json
{
  "person": {
    "id": "abc123",
    "first_name": "Sarah",
    "last_name": "Chen",
    "title": "VP of Engineering",
    "email": "schen@targetco.com",
    "linkedin_url": "https://linkedin.com/in/sarahchen",
    "phone_numbers": [
      { "sanitized_number": "+14155551234" }
    ],
    "organization": {
      "name": "TargetCo"
    }
  }
}
```
 
**Notes:**
- Returns a single person under `person` key (singular).
- Costs 1 credit per call.
- Email may be null if no verified work email exists.
- `phone_numbers` is an array — access first element's `sanitized_number`.

# HubSpot Contacts API Reference
 
## Look up a company by ID
 
```
GET https://api.hubapi.com/crm/v3/objects/companies/<COMPANY_ID>
Authorization: Bearer <HUBSPOT_ACCESS_TOKEN>
```
 
Query parameter: `properties=domain,name`
 
## Search companies by name
 
```
POST https://api.hubapi.com/crm/v3/objects/companies/search
Authorization: Bearer <HUBSPOT_ACCESS_TOKEN>
Content-Type: application/json
```
 
Body:
```json
{
  "filterGroups": [{"filters": [{
    "propertyName": "name",
    "operator": "CONTAINS_TOKEN",
    "value": "TargetCo"
  }]}],
  "properties": ["domain", "name"],
  "limit": 1
}
```
 
## Search contacts by email (deduplication)
 
```
POST https://api.hubapi.com/crm/v3/objects/contacts/search
Authorization: Bearer <HUBSPOT_ACCESS_TOKEN>
Content-Type: application/json
```
 
Body:
```json
{
  "filterGroups": [{"filters": [{
    "propertyName": "email",
    "operator": "EQ",
    "value": "schen@targetco.com"
  }]}]
}
```
 
Returns `results` array — if length > 0, contact exists.
 
## Create a contact
 
```
POST https://api.hubapi.com/crm/v3/objects/contacts
Authorization: Bearer <HUBSPOT_ACCESS_TOKEN>
Content-Type: application/json
```
 
Body:
```json
{
  "properties": {
    "email": "schen@targetco.com",
    "firstname": "Sarah",
    "lastname": "Chen",
    "jobtitle": "VP of Engineering",
    "company": "TargetCo",
    "phone": "+14155551234",
    "hs_lead_status": "NEW"
  }
}
```
 
**Important:** HubSpot uses `firstname` (not first_name), `lastname` (not last_name), `jobtitle` (not job_title).
 
## Associate contact with company
 
```
PUT https://api.hubapi.com/crm/v3/objects/contacts/<CONTACT_ID>/associations/companies/<COMPANY_ID>/contact_to_company
Authorization: Bearer <HUBSPOT_ACCESS_TOKEN>
```
 
No body required.

# HubSpot Field Mapping
 
Map Apollo enrichment fields to HubSpot contact properties:
 
| Apollo field | HubSpot property | Notes |
|---|---|---|
| `person.email` | `email` | Required — skip contact if null |
| `person.first_name` | `firstname` | Not `first_name` |
| `person.last_name` | `lastname` | Not `last_name` |
| `person.title` | `jobtitle` | Not `job_title` |
| `person.organization.name` | `company` | Company name as text |
| `person.phone_numbers[0].sanitized_number` | `phone` | May be null |
| `person.linkedin_url` | `linkedin_url` | Custom property — must exist in HubSpot |
 
Set `hs_lead_status` to `NEW` for all created contacts.
 
**Important:** The `linkedin_url` property is custom — it must be created in HubSpot (Settings > Properties > Create property) before the script can write to it. If it doesn't exist, omit it from the contact creation payload.

/find-decision-makers Acme Corp

Company: Acme Corp (acme.com) — HubSpot ID: 12345678
Searching Apollo for decision makers...
Found 8 people
 
  CREATED: schen@acme.com — VP of Engineering
  CREATED: jmiller@acme.com — CRO
  EXISTS: tkim@acme.com (ID: 87654321), associating
  CREATED: agarcia@acme.com — VP Marketing
  SKIPPED: Bob Wilson — no verified email
  CREATED: lnguyen@acme.com — VP RevOps
  CREATED: mrobinson@acme.com — Head of Sales
  CREATED: dthompson@acme.com — CTO
 
Done. 6 contacts created, 1 existing associated, 1 skipped. ~16 Apollo credits used.

# Run weekly on Monday mornings for new target accounts
0 9 * * 1 cd /path/to/your/project && claude -p "Run /find-decision-makers for all Tier 1 companies without contacts" --allowedTools 'Bash(*)' 'Read(*)'

name: Find Decision Makers
on:
  schedule:
    - cron: '0 14 * * 1'  # Weekly on Monday at 9 AM ET
  workflow_dispatch: {}
jobs:
  run:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: anthropics/claude-code-action@v1
        with:
          prompt: "Run /find-decision-makers for all Tier 1 ABM companies that have 0 associated contacts"
          allowed_tools: "Bash(*),Read(*)"
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
          HUBSPOT_ACCESS_TOKEN: ${{ secrets.HUBSPOT_ACCESS_TOKEN }}
          APOLLO_API_KEY: ${{ secrets.APOLLO_API_KEY }}