Skip to main content

​
Waterfall Enrichment

Waterfall enrichment tries multiple data providers in sequence, cheapest first, and stops the moment one returns a valid result. Deepline ships 6 waterfall plays that orchestrate 30 production providers into cost-ordered chains. Single-provider lookups typically find 40-60% of emails. Waterfall enrichment pushes that to 70-85% by cross-referencing multiple sources in a single request. You pay only for the provider that delivers — misses cost $0.

​
Primitives

These are the hard numbers. Everything below is derived from them.
AttributeValue
Waterfall plays available6
Default email waterfall providers6 (Dropleads, Hunter, LeadMagic, Deepline Native, Crustdata, PeopleDataLabs)
Cost-aware waterfall steps8 (3 pattern-guess + 5 finder providers)
Production providers in platform30
Cost per email find0.2-0.6 credits (0.016−0.016-0.048)
Cost for misses0 credits (no charge when no provider returns a valid result)
Single-provider email coverage40-60% typical
Waterfall email coverage70-85% typical
Waterfall logicSequential, cost-ordered, stop-on-first-valid-hit
BYOK modeSupported — bring your own API keys, pay providers directly at their rates

​
What waterfall enrichment means for your GTM workflow

Not every workflow needs waterfall enrichment. Here is where it helps and where it does not.
  • Maximizes email coverage. A single email provider typically resolves 40-60% of lookups. B2B contact data decays at roughly 22.5% per year (HubSpot via Cognism), so any single source goes stale fast. The 6-provider waterfall cross-references Dropleads, Hunter, LeadMagic, Deepline Native, Crustdata, and PeopleDataLabs in real time, pushing coverage to 70-85%. That 15-25 percentage point gap translates directly to more contacts reached per campaign. Waterfall enrichment gets 20-40% higher email coverage than any single provider (Instantly).
  • Cheapest path to a valid result. Waterfall logic tries the cheapest provider first (Dropleads at 0.3 credits) and stops the moment a valid email is found. Most lookups resolve on the first or second provider at 0.2-0.6 credits (0.016−0.016-0.048). Providers that do not fire are not billed. The cost-aware variant goes further: it tries 3 deterministic email patterns via validation (near-zero cost) before calling any finder provider. On lists where common patterns like first.last@domain.com are prevalent, this saves 50-70% compared to starting with a paid finder.
  • Runs from a single prompt or CLI command. Every waterfall play is callable with a single CLI command or a natural language prompt in Claude Code or Codex. No spreadsheet UI, no column wiring, no template configuration. The agent reads your CSV headers, selects the right waterfall variant, and enriches every row. The entire loop — from input analysis to provider selection to result extraction — runs inside your IDE or terminal. This makes waterfall enrichment composable with other automation steps: scraping, scoring, CRM sync, outreach sequencing.
  • Skip it for single-provider queries. If you need data from one specific provider (for example, only Apollo people search results, or only Crustdata company data), use a direct tool call instead of a waterfall. Waterfalls are designed for outcome-based queries (“find this person’s email”) where the source does not matter — only the result. For provider-specific queries, Deepline exposes all 30 providers as individual tools with their own endpoints and schemas.

​
How it works

The waterfall execution model is the same across all 6 plays. Here is the step-by-step sequence for a typical email lookup.
  1. Analyze input data. Deepline inspects your payload fields or CSV column headers to determine which waterfall variant fits. If you provide first_name, last_name, company_name, and domain, it selects the name_and_company_to_email_waterfall. If you provide a linkedin_url, it selects a LinkedIn-optimized chain. The cost-aware variant activates when you have first_name, last_name, and domain but no company name.
  2. Compile the provider chain. The selected play compiles into an ordered list of provider steps. Each step specifies the tool ID, the payload template (with {{variable}} interpolation from your input), and an extraction function that pulls the target field from the provider response. The chain is ordered by cost: cheapest providers run first.
  3. Execute the first provider. Deepline sends the request to the lowest-cost provider in the chain (for example, Dropleads at 0.3 credits for the default email waterfall). The provider returns either a result or a miss. Execution time per provider is typically 1-3 seconds.
  4. Validate the result. If the provider returns data, Deepline runs the extraction function to pull the target field (such as email). For email waterfalls, this includes checking that the returned address is not a catch-all, not a bounce, and not syntactically invalid. The cost-aware variant uses leadmagic_email_validation to verify pattern-guessed addresses against the mail server before accepting them.
  5. Fall through or stop. If validation fails or the provider returned no data, Deepline moves to the next provider in the chain. If validation passes, the waterfall stops immediately. You are billed only for providers that actually executed — providers below the stopping point never fire. In the default 6-provider chain, most lookups stop at provider 1 or 2.
  6. Return structured output. The final result includes the found value (email, person context, or contact list depending on the play), the provider that resolved it, the number of providers attempted, and the total credits consumed. This output feeds directly into downstream enrichment steps, CSV columns, or CRM updates.

​
Waterfall plays available

Deepline ships 6 waterfall plays. Each play is optimized for a different input shape and output goal.

​
1. Name + Company to Email (name_and_company_to_email_waterfall)

The most common waterfall. Input: first_name, last_name, company_name, domain. Optional: linkedin_url for LinkedIn-dependent fallback providers. Provider chain: Dropleads, Hunter, LeadMagic, Deepline Native, Crustdata, PeopleDataLabs (6 providers). Typical cost: 0.3-0.4 credits. Use when you have a standard lead list with company information.

​
2. LinkedIn + Name + Domain to Email (person_linkedin_to_email_waterfall)

Input: linkedin_url, first_name, last_name, domain. Optional: company_name. Provider chain: Dropleads, Hunter, LeadMagic, Deepline Native, Crustdata, PeopleDataLabs (6 providers). Same cost-ordered sequence as the name+company waterfall but all providers receive the LinkedIn URL, improving match rates for LinkedIn-sourced leads. Typical cost: 0.3-0.4 credits.

​
3. LinkedIn-Only to Email (person_linkedin_only_to_email_waterfall)

Input: linkedin_url, first_name, last_name. No domain required. Provider chain: Dropleads (single person enrichment), Deepline Native, Crustdata, PeopleDataLabs (4 providers). Use when you have LinkedIn URLs and names but no company domain. Typical cost: 0.3-0.5 credits.

​
4. Email to Person Context (person_enrichment_from_email_waterfall)

Reverse enrichment. Input: email. Provider chain: Hunter, Crustdata, Prospeo, Apollo, Deepline Native (5 providers). Returns full person context: name, LinkedIn URL, company, title. Use when you have email addresses and need to hydrate person and company data. Typical cost: 0.2-0.3 credits.

​
5. Cost-Aware Name + Domain to Email (cost_aware_first_name_and_domain_to_email_waterfall)

The cheapest waterfall. Input: first_name, last_name, domain. 8 steps: 3 deterministic pattern guesses validated via leadmagic_email_validation (patterns: first.last@domain, firstlast@domain, first_last@domain) followed by 5 finder providers (Dropleads, Hunter, LeadMagic, Deepline Native, PeopleDataLabs). The pattern-guess phase costs near-zero credits because validation is cheaper than a full finder call. If the correct pattern matches, the lookup resolves for 0.1-0.2 credits. Typical cost: 0.1-0.4 credits.

​
6. Company + Role to Contacts (company_to_contact_by_role_waterfall)

Prospecting waterfall. Input: company_name, domain, roles (job titles), seniority (level filter). Provider chain: Dropleads, Apollo, Icypeas, Prospeo, Crustdata (5 providers). Returns a list of matching contacts (not a single email). Use when you need to find decision makers at target accounts by title and seniority. Typical cost: 0.2-0.6 credits per provider step. Supports a limit parameter (1-100) to control how many contacts each provider returns.

​
Example CLI commands

​
Single email lookup

deepline tools execute name_and_company_to_email_waterfall \
  --payload '{"first_name":"Sarah","last_name":"Chen","company_name":"Stripe","domain":"stripe.com"}'

​
Bulk CSV enrichment

deepline enrich --input leads.csv --output enriched.csv \
  --with '{"alias":"email","tool":"name_and_company_to_email_waterfall","payload":{"first_name":"{{first_name}}","last_name":"{{last_name}}","company_name":"{{company_name}}","domain":"{{domain}}"}}'

​
Cost-aware waterfall (name + domain only)

deepline tools execute cost_aware_first_name_and_domain_to_email_waterfall \
  --payload '{"first_name":"Sarah","last_name":"Chen","domain":"stripe.com"}'

​
LinkedIn URL to email

deepline tools execute person_linkedin_to_email_waterfall \
  --payload '{"linkedin_url":"https://linkedin.com/in/sarahchen","first_name":"Sarah","last_name":"Chen","domain":"stripe.com"}'

​
Find decision makers at a company

deepline tools execute company_to_contact_by_role_waterfall \
  --payload '{"company_name":"Stripe","domain":"stripe.com","roles":["VP Engineering","CTO"],"seniority":["VP","C-Level"]}'

​
Reverse enrichment from email

deepline tools execute person_enrichment_from_email_waterfall \
  --payload '{"email":"sarah@stripe.com"}'

​
Natural language (Claude Code or Codex)

You do not need to memorize tool IDs. Ask in plain language: 
Find work emails for everyone in leads.csv

I have LinkedIn URLs in contacts.csv -- find their work emails using waterfall enrichment

Find the VP of Engineering at Acme Corp (acme.com) and get their email

​
Pilot mode (test before full run)

Always test on a small subset before running a full list: 
Run waterfall email enrichment on leads.csv -- just the first 3 rows
Or with the CLI: add --rows 0:2 to the deepline enrich command.

​
Frequently Asked Questions

Most lookups resolve on the first or second provider at 0.2-0.6 credits (0.016−0.016-0.048). The cost-aware variant tries 3 free email pattern guesses first and can resolve for as little as 0.1 credits ($0.008). Worst case if all 6 providers fire in the default chain: up to 7.2 credits, but this is rare — it means every provider missed or returned invalid data. In BYOK mode (bring your own API keys), waterfall lookups are free through Deepline; you pay providers directly at their rates. You are never charged for providers that did not execute.
Deepline inspects your input fields (payload keys or CSV column headers) and selects the variant that matches your available data. If you have first_name, last_name, company_name, and domain, it uses name_and_company_to_email_waterfall. If you have linkedin_url, it prefers the LinkedIn-optimized chain. If you have name and domain but no company, it uses the cost-aware variant with pattern guessing. You can also specify the exact waterfall by tool ID in the CLI if you want to override automatic selection.
The waterfall tries every provider in the chain. If none returns a valid result, the output is null for that row. You are charged only for providers that executed and returned data — if all providers miss, the total cost is the sum of their per-call rates (typically 0.3-1.2 credits depending on the chain length). Deepline does not fabricate results. A null result means the contact could not be resolved from any of the 30 production providers in the platform.
The built-in waterfall plays use a fixed cost-ordered provider chain that is optimized for price-performance. If you need a custom chain, you can break the waterfall into individual tool calls and orchestrate them yourself using deepline tools execute or deepline enrich with multiple --with steps. You can also use the plays API (/api/v2/plays/compile) to inspect the compiled provider chain for any play and modify it programmatically.
Related pages: Email Waterfall | Find Work Email | Plays Overview | Find Decision Makers | Quick Start