The expensive version of a waterfall is just a loop
Take every row, call Apollo, call Prospeo, call Hunter, keep whichever email looks best, and export the CSV. That is easy to code. It is also how teams create duplicate spend, conflicting identities, and a list nobody can explain.
A real enrichment waterfall is a decision system. It asks whether the row is eligible, whether the person is already resolved, which required fields are missing, whether an existing value is fresh enough, which provider is authorized for the next lookup, and what result should stop the chain.
Codex or Claude Code is useful as the orchestrator because it can manage files, scripts, schemas, tests, API clients, and review artifacts. The data calls themselves should remain deterministic code with explicit budgets and logs.
Give each provider a narrow job
Apollo: broad prospect discovery
Apollo's People API Search supports title, seniority, location, company size, revenue, technologies, domains, job postings, and other filters. The search endpoint does not return email addresses or phone numbers. Treat search and enrichment as separate cost and state transitions.
Prospeo: an alternate search and reveal lane
Prospeo's current Search Person API documents more than 20 filters, 25 results per page, a 25,000-result ceiling, and separate person enrichment for revealed email or mobile values. Its search response can say whether a repeated result page was free because of its deduplication window. Preserve that signal in the cost log.
Hunter: finder and verifier
Hunter's V2 API separates Domain Search, Email Finder, and Email Verifier. Its documentation says Email Finder uses a domain plus first and last name to find the most likely address, while Email Verifier evaluates deliverability and returns evidence available to Hunter. A verifier result is a provider assessment, not permission to send and not a guarantee of inbox placement.
Define stop conditions before provider order
- Stop discovery when one approved source has resolved the intended person and company.
- Stop email finding when a permitted work address meets the required confidence and freshness rule.
- Stop enrichment when every campaign-required field is present. Optional fields should not trigger paid calls by default.
- Stop and review when providers disagree on employer, role, domain, or person identity.
- Reject before enrichment when the domain is suppressed, the account is an existing customer, or a hard ICP rule fails.
Provider order can change by geography, field, plan, and observed hit rate. Keep it in configuration rather than embedding it across scripts.
required_fields: [first_name, last_name, title, company, domain, work_email] search_order: [apollo, prospeo] email_order: [prospeo, hunter] verify_with: hunter stop_when: identity_match: exact email_status: [valid] review_when: email_status: [accept_all, unknown] employer_conflict: true budgets: max_paid_calls_per_row: 2 max_retries_per_provider: 2
Normalize before you merge
Do not let provider-specific field names become your database. Create one canonical schema and retain the raw response separately. Normalize domains to a bare lowercase domain. Preserve provider person and company IDs. Store the exact source, retrieval time, lookup type, and status beside every selected value.
A person should not be deduplicated by name alone. Use the strongest available combination of normalized work email, provider person ID, LinkedIn URL, person plus company domain, and carefully reviewed fallbacks. Company identity should center on normalized domain, with a separate process for subsidiaries and regional entities.
Separate enrichment from verification
An address appearing in a source record is not the same thing as an address passing a current verifier. Run verification after the waterfall selects its candidate address. Preserve the original address, verification provider, status, checked time, and any reason code. Never overwrite history when a later check changes the status.
Then apply campaign-specific controls. For example, the recipient infrastructure screening workflow can route high-friction domains away from the primary send lane. The pre-send QA checklist provides the final launch gate.
Let workers enrich, but let code enforce the contract
Use one orchestrator to partition rows and track budgets. Workers can research public websites or handle provider calls for independent slices. A deterministic merge process should validate schemas, enforce unique keys, total paid calls, and block incomplete rows. A separate QA pass should inspect sampled evidence and every conflict.
This extends the Codex or Claude Code Clay replacement. The coding agent replaces the workflow layer. Apollo, Prospeo, and Hunter remain data services with their own limits, pricing, policies, and evidence quality.
Why this article does not claim a performance case study
No suitable first-party case study was found that publishes comparable provider-by-provider calls, accepted fields, verification states, conflicts, and cost per send-ready lead for this exact waterfall. Vendor success stories without those stage logs cannot prove that one provider order is best. The product capabilities in this article come from current official documentation; performance should be established with a representative sample and the stage metrics below.
Measure the waterfall by stage
- Eligible rows entering each provider.
- Resolved identity rate and conflict rate.
- New required fields added per paid call.
- Email finder hit rate and verifier status mix.
- Cost per accepted, verified, ICP-qualified row.
- Review queue size, rejection reasons, retries, and provider errors.
Do not report a blended "enrichment rate" alone. It can hide a cheap provider producing many low-value fields while the expensive calls still fail to produce sendable records.
Build rule: no provider call without an eligibility test, no selected field without provenance, no retry without a cap, and no send-ready row without a separate verification and campaign QA gate.
FAQ
What is waterfall email enrichment?
Waterfall email enrichment queries providers in a controlled sequence and stops when a result meets defined acceptance and verification rules. The workflow should preserve provenance, prevent duplicate spend, and route conflicts for review.
What are the best waterfall enrichment tools?
The best stack depends on the required fields, target market, provider coverage, acceptable evidence, and budget. Apollo, Prospeo, and Hunter can play different roles, while Codex or Claude Code can orchestrate schemas, routing, logs, and QA.
Which provider should run first?
The one that best fits the required field, market, contract, and measured hit rate. Test on a representative sample and keep the order configurable.
Does this eliminate Clay completely?
It can replace the workflow and table logic for teams able to maintain code. It does not replace the underlying data providers, sequencer, or operating judgment.
Can a cheaper model run the workers?
Yes for bounded extraction and classification tasks. Use deterministic code for budgets, schemas, deduplication, and final merge checks, with a stronger orchestrator reviewing exceptions.
