lead-sourcing-apollo

Lead Sourcing — Apollo

Translate a defined ICP into an Apollo search, pull a cost-quoted batch of contacts, normalize to the canonical Lead schema, and push to CRM. Operates in three modes — API, manual export, or BYO CSV — degrading gracefully.

Clarification Protocol

When you encounter any of the following, STOP and ask the user — do NOT make a silent assumption, and do NOT flatly refuse:

• Ambiguous or missing input
• A fork in approach (multiple valid frameworks, segments, scopes, or sources)
• A rule that would block progress
• An assumption that materially shapes the output
• Unverified data that a downstream step depends on

Present 2–4 concrete options with trade-offs and your recommendation.

Format:

Decision needed: <what's being decided> Options:

• A) <option> — trade-off
• B) <option> — trade-off
• C) <option> — trade-off My recommendation: <X> because <reason>. Confirm or pick a different option before I continue.

Refusing to proceed is NEVER the final answer. Every "block" must come with an override option. If the user picks an override, honor it on the first request — do not re-prompt the same block multiple times in one run.

Scope

This skill ONLY produces Apollo-sourced lead CSV records (people + companies matching ICP filters). Do not expand into adjacent topics. If the user's request implies adjacent scope, trigger Clarification Protocol with options to (A) stay in scope, (B) note the adjacent need as a follow-up, (C) hand off to a different skill.

Verification Requirements (Derived Details Only)

The search action itself does NOT require web verification — Apollo returns are first-party for sourcing. However, every derived person/company detail that this skill or downstream skills will state as fact (titles, seniorities, company size, technographics, funding) MUST be verified or marked [UNVERIFIED] before push.

• Tag derived details inline as [H/M/L][Sn].
• Source URL goes in the lead record's provenance field.
• Unverified derived details belong in ## Assumptions to Validate, NOT in the lead's main fields.

Sources are mandatory for derived claims. If you cannot cite a source, mark [UNVERIFIED].

When to Use

• User wants to build an outbound list grounded in a defined ICP
• User has an Apollo seat or API key and wants to pull contacts
• User has an Apollo CSV export to ingest and normalize
• "Source SDRs at Series B SaaS companies in the US"
• User needs search filters to run manually in Apollo
• User has a BYO list from another CRM to clean up and push

Legend — Confidence Score (Derived Fields)

• [H] High — verified by ≥2 independent primary sources within last 6 months
• [M] Medium — single primary source, OR multiple secondary sources agree
• [L] Low — inferred / single secondary source / older than 12 months

Quick Reference

Concept	Value
Modes	API (key set) / Manual export (seat, no key) / BYO (any list)
Adapter contract	discover() → count + cost; pull() → records; normalize() → Lead schema
Quote-before-pull	Mandatory — never pull() without discover() + user confirm
First-batch default	≤500 records — validate filter quality before expanding
Cost cap	gtm.sourcing_run_usd_cap (default $25); record cap 2000
Dedup priority	linkedin_url > email > phone (person); company_domain (company)
Apollo "verified" email	Hint, not verdict — always pair with data-enrichment verifier
Provenance tags	[verified: apollo-api] / [user-provided] / [unverified — needs check]
Compliance	EU → gdpr_basis: legitimate-interest; role-addresses → sidecar; DNC → strip

Procedure

1. Confirm ICP grounding. Read ICP scorecard from icp-definition. Extract firmographic, role map, triggers, anti-ICP. If absent → flag ICP-ungrounded, confidence: low.
2. Determine mode. APOLLO_API_KEY set → API. Else seat → manual export. Else any list → BYO. Else → filter recommendations only.
3. Translate ICP → Apollo filter set. Map industry → organization_industries; size → organization_num_employees_ranges; geography → person_locations; funding → organization_latest_funding_stage; tech → currently_using_any_of_technology_uids; titles → person_titles; seniority → person_seniorities; anti-ICP → not_organization_*. Store as reproducible source_query.
4. Pre-flight: discover(). Surface candidate count, estimated USD, sample of 5. Default behavior: wait for explicit authorization before pull(). If the user requests skipping the quote step, trigger Clarification Protocol with options: (A) run discover() then confirm (default safe), (B) skip discover() and pull immediately within cost cap (flag run as confidence: low — quote-skipped), (C) raise cost cap then re-quote. Honor user override on first request; do not re-prompt. Reference ${HERMES_SKILL_DIR}/references/ for Apollo filter mapping details. 4a. Search-criteria width gate (Clarification Protocol). If candidate count is far above or below the user's apparent intent, STOP and present options: (A) widen filters (warn: higher volume + higher cost + likely lower precision), (B) narrow filters (warn: reduced reach, may miss valid accounts), (C) keep current. Recommend based on count vs. ICP target. Honor pick on first response.
5. Pull. Page through results, respect rate limits (~60 req/min, backoff on 429), cap at gtm.sourcing_run_record_cap. Stamp source_run_id and source: apollo-api on every record.
6. Normalize. Map to Lead schema. Tag provenance per field. Construct personalization_hook ONLY with citable URL — never invent. Run ${HERMES_SKILL_DIR}/scripts/normalize_lead.py per record.
7. Dedup against CRM. Merge by linkedin_url > email > phone for person; company_domain for company. Run ${HERMES_SKILL_DIR}/scripts/dedup_leads.py. Log every merge.
8. Apply compliance filters. EU → gdpr_basis: legitimate-interest. Role-address emails → sidecar. DNC phones → strip.
9. Push to CRM + emit run summary. Run ${HERMES_SKILL_DIR}/scripts/push_to_crm.py. Push company + person + interaction:research for verified/user-provided; interaction:research only for unverified. Emit one-screen run summary.

Pitfalls

• Pulling without a quote — default is discover() first; if cost cap is hit, surface options (A) stop, (B) raise cap and re-quote, (C) override and pull at current cap with confidence: low — cap-overridden flag — do not re-prompt the same cap twice in one run
• Trusting Apollo's "verified" email flag — pair with real verifier in data-enrichment
• Inventing personalization hooks — hooks ship with citable URLs or they don't ship
• Ignoring company-size-adjusted seniority — "VP" at 50 people ≠ "VP" at 5,000
• Blasting role addresses — info@, sales@ → sidecar, never active push
• Filters too tight then over-loosened — loosen one dimension at a time and re-discover

Verification

1. source_query filter object is reproducible — running it again returns the same candidates ± new entrants
2. Every record carries provenance tags on every named field — no untagged fields
3. Run record's costs match Apollo's billing dashboard ± rounding
4. [unverified — needs check] records landed in review queue, not active prospect list

Output Format

• Sections required: Lead CSV (per schema), Run Summary (counts, dedup stats, source query), Assumptions to Validate
• Tables / fields: see references/csv-schema.md for the canonical Lead CSV column list and encoding
• Length target: depends on query scope (cost-capped per gtm.sourcing_run_record_cap); Run Summary ≤300 words by default
• File type: CSV (lead records) + markdown (run summary)
• Mandatory closing sections: Verification Notes, Assumptions to Validate, Next Step