Skip to main content
Waterfall enrichment tries multiple data providers in sequence, cheapest first, and stops the moment one returns a valid result. Deepline ships prebuilt plays that orchestrate providers into cost-ordered chains. Single-provider enrichment commonly leaves coverage gaps. Waterfall enrichment improves match rates by cross-referencing multiple sources in a single request. You pay only for the provider that delivers. BYOK mode: misses cost nothing through Deepline. Managed mode: misses pass through provider per-call costs (typically 0.3-1.2 credits).

​
Primitives

These are the hard numbers. Everything below is derived from them.

​
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. 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. Single-provider enrichment commonly leaves coverage gaps. Waterfall enrichment improves match rates by querying multiple providers in sequence. Specific lift varies by ICP and region.
  • 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.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 can reduce spend 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 29 providers as individual tools with their own endpoints and schemas.

​
How it works

The waterfall execution model is the same across the email-focused 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, and domain, it selects the name_and_domain_to_email_waterfall. If you provide a linkedin_url, it selects the LinkedIn-optimized person-linkedin-to-email play.
  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.

​
Dashboard-visible prebuilt plays

This catalog is generated from the prebuilt registry. It contains every non-batch prebuilt play that is visible in the dashboard and callable as prebuilt/<name>. Batch counterparts, hidden support plays, and legacy tool aliases are intentionally excluded. Some older CLI examples use native tool IDs such as name_to_linkedin_url_waterfall. Those are compatibility aliases, not dashboard catalog names. Use the canonical prebuilt/<name> reference when selecting a prebuilt play directly.

​
Example CLI commands

​
Single email lookup

​
Bulk CSV enrichment

​
LinkedIn URL to email

​
Find decision makers at a company

​
Personal email lookup

​
Natural language (Claude Code or Codex)

You do not need to memorize tool IDs. Ask in plain language:

​
Pilot mode (test before full run)

Always test on a small subset before running a full list:
Or with the CLI: add --rows 0:1 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.048). The name_and_domain_to_email_waterfall tries 3 free email pattern guesses first and can resolve for as little as 0.1 credits ($0.008). Worst case if all providers fire: up to ~5.9 credits for name_and_domain_to_email_waterfall or ~7.2 credits for person-linkedin-to-email, 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.
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, and domain, it uses name_and_domain_to_email_waterfall (which tries free patterns first). If you have linkedin_url, it prefers person-linkedin-to-email. 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. BYOK mode: misses cost nothing through Deepline. Managed mode: misses pass through provider per-call costs (typically 0.3-1.2 credits across the chain). Deepline does not fabricate results. A null result means the contact could not be resolved from any of the 29 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