Two-phase Apollo.io prospecting: free People Search to discover ICP-matching leads, then selective enrichment to reveal emails/phones (credits per contact). Creates Apollo lists. Deduplicates against Supabase.
Two-phase Apollo.io prospecting: free People Search for lead discovery, then selective paid enrichment to reveal emails and phone numbers. Creates Apollo lists and contacts. Deduplicates against Supabase.
Key advantage over CrustData: Apollo People Search is free (no credits consumed). Credits are only spent when enriching contacts to reveal email/phone. This lets you search tens of thousands of leads at zero cost, review results, then selectively enrich only the best matches.
Get your API key from Apollo.io Settings > Integrations > API. Add to .env:
APOLLO_API_KEY=your-api-key-here
Same Supabase project used by crustdata-supabase. The full schema lives in tools/supabase/schema.sql. This skill writes to the table (dedup by UNIQUE constraint). Run if setting up fresh.
peoplelinkedin_urlpython3 tools/supabase/setup_database.pyEnsure .env has all three keys:
APOLLO_API_KEY=...
SUPABASE_URL=https://xxx.supabase.co
SUPABASE_SERVICE_ROLE_KEY=eyJ...
Ask the user these questions to build the Apollo filter config:
Build the config JSON with Apollo's filter format:
{
"client_name": "example-client",
"search_config_name": "vp-sales-us-midmarket",
"icp_segment": "sales-leaders",
"apollo_filters": {
"person_titles": ["VP of Sales", "Head of Sales", "Director of Sales"],
"person_seniority": ["vp", "director"],
"person_locations": ["United States"],
"organization_num_employees_ranges": ["51,200", "201,500", "501,1000"],
"q_organization_keyword_tags": ["SaaS", "Software"]
},
"enrichment_filters": {
"exclude_titles_containing": ["intern", "assistant"]
},
"apollo_list_name_prefix": "example-sales-leaders",
"create_apollo_list": true,
"mode": "standard",
"max_pages": 50
}
Available Apollo search filters:
person_titles — job title keywords (array of strings)person_seniority — seniority levels: owner, founder, c_suite, partner, vp, director, manager, senior, entryperson_locations — geographic locations (array of strings)organization_num_employees_ranges — employee count ranges, format "min,max" (e.g., "51,200")q_organization_keyword_tags — company keyword tags (e.g., "SaaS", "Software")person_not_titles — titles to exclude (array of strings)q_organization_name — organization name searchorganization_locations — company HQ locationsSave config:
skills/apollo-lead-finder/configs/{client-name}.json
python3 skills/apollo-lead-finder/scripts/apollo_lead_finder.py \
--config skills/apollo-lead-finder/configs/{client}.json \
--phase search \
[--test] [--yes] [--dry-run]
Apollo's api_search endpoint returns limited preview data: Apollo person ID, first name, obfuscated last name, title, company name, and boolean flags (has_email, has_phone). No LinkedIn URLs, emails, or full names — those require enrichment.
Step 1: Build Apollo search payload — Map config filters to Apollo People Search format.
Step 2: Search page 1 — Get first 100 results + total_entries for total count.
Step 3: Paginate — Fetch remaining pages (100 per page, up to mode cap). Apply title filters.
Step 4: Save manifest — Write Apollo person IDs + preview data to a JSON manifest file for the enrich phase.
Step 5: Export preview CSV — Write search results to output/{client-name}-search-{timestamp}.csv (limited data — full data after enrichment).
| Parameter | Test | Standard | Full |
|---|---|---|---|
| Max pages | 1 | 50 | 500 |
| Max results | 100 | 5,000 | 50,000 |
| Search credits | 0 | 0 | 0 |
Cost: FREE. People Search does not consume Apollo credits.
CRITICAL: Never upsert leads to Supabase without explicit user approval.
This skill writes to the people table during the enrich phase. The search phase is free and produces no database writes — but enrichment both costs credits AND writes to the database.
Required flow:
--phase search first (free) — review the search results and preview CSVThe agent must NEVER pass --yes on a first run. The --yes flag is only for pre-approved automated runs.
If the user hasn't approved the upsert: Export the CSV and show sample results. Let the user review. Only proceed to upsert after they confirm.
python3 skills/apollo-lead-finder/scripts/apollo_lead_finder.py \
--config skills/apollo-lead-finder/configs/{client}.json \
--phase enrich \
[--test] [--yes] [--limit N]
Step 1: Load search manifest — Read the manifest JSON saved by the search phase. Contains Apollo person IDs.
Step 2: Connect to Supabase — Fetch existing LinkedIn URLs for dedup.
Step 3: Confirm credits — Display lead count and credit cost estimate. Wait for confirmation.
Step 4: Bulk enrich — Call /people/bulk_match with Apollo person IDs in batches of 10. Each match costs 1 credit. Returns full data: email, phone, LinkedIn URL, full name, location, company details.
Step 5: Dedup against Supabase — Filter out leads whose LinkedIn URLs already exist in Supabase.
Step 6: Present results to user — Show enriched sample leads (names, titles, companies, email coverage) and ask for explicit approval before writing to the database.
Step 7: Upsert to Supabase — Only after user approval. Insert net-new people with source='apollo', enrichment_status='complete'.
Step 8: Export CSV — Write enriched leads to output/{client-name}-enriched-{timestamp}.csv. Update manifest to remove enriched people.
| Parameter | Test | Standard | Full |
|---|---|---|---|
| Max enrichments | 10 | 500 | 2,500 |
| Credits used | 10 | 500 | 2,500 |
Cost: 1 credit per contact enriched. Always run search first, review results, then selectively enrich.
Present results:
Common adjustments:
Trigger phrases:
Test search (free, no DB writes):
python3 skills/apollo-lead-finder/scripts/apollo_lead_finder.py \
--config skills/apollo-lead-finder/configs/example.json --phase search --test
Dry run (no API calls):
python3 skills/apollo-lead-finder/scripts/apollo_lead_finder.py \
--config skills/apollo-lead-finder/configs/example.json --phase search --dry-run
Enrich only (after reviewing search results and getting user approval):
python3 skills/apollo-lead-finder/scripts/apollo_lead_finder.py \
--config skills/apollo-lead-finder/configs/example.json --phase enrich --limit 100
Full search + enrich (only for pre-approved repeat runs):
python3 skills/apollo-lead-finder/scripts/apollo_lead_finder.py \
--config skills/apollo-lead-finder/configs/example.json --phase both
POST https://api.apollo.io/api/v1/mixed_people/api_search — FREE, returns Apollo IDs + preview data (first name, title, org name, boolean flags). No LinkedIn URLs or emails.POST https://api.apollo.io/api/v1/people/match — 1 credit, reveals email/phonePOST https://api.apollo.io/api/v1/people/bulk_match — up to 10 per request, 1 credit eachPOST https://api.apollo.io/api/v1/labels — create a named listPOST https://api.apollo.io/api/v1/contacts — add person to Apollo CRM + optional listx-api-key: {APOLLO_API_KEY} header on all requestspage param (1-indexed), per_page max 100