Skip to main content
Waterfall enrichment tries multiple data providers in a configured sequence and stops the moment one returns a valid result. Deepline ships prebuilt plays whose routes balance price and result quality. Single-provider enrichment commonly leaves coverage gaps. Waterfall enrichment improves match rates by cross-referencing multiple sources in a single request. Providers below the successful step do not run. BYOK mode: Deepline does not charge for provider calls. Managed mode: executed calls follow each provider’s Deepline rate.

​
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 configured waterfall cross-references multiple providers 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.
  • Stops once a valid result is found. Waterfall logic tries the configured route, which balances price and result quality, and stops the moment a valid email is found. A successful standalone DropLeads Email Finder result, for example, costs 0.26 managed credits. That is a tool-rate example, not a claim about where DropLeads appears in the active play. Providers that do not fire are not billed. The cost-aware variant goes further: it tries deterministic email patterns via validation before calling finder providers. A first-pattern match uses one 0.09-credit LeadMagic validation. On lists where common patterns like first.last@domain.com are prevalent, this can reduce spend compared to starting with a 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.
A contact moves through configured enrichment providers. Pattern validation and Provider A miss, Provider B returns a valid email, and later providers are skipped.

Example of the shared waterfall routing pattern: providers run in the configured order, misses fall through, and later providers are skipped after the stopping condition is met.

  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 play’s routing policy determines the configured order.
  3. Execute the first provider. Deepline sends the request to the first configured provider in the chain. 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.
  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

For example, a successful standalone DropLeads Email Finder result costs 0.26 managed credits. The name_and_domain_to_email_waterfall first tries likely email patterns; a first-pattern match uses one 0.09-credit LeadMagic validation. These are standalone tool prices, not total-run quotes or claims about provider order. 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 email 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: executed calls follow each provider’s Deepline rate. Deepline does not fabricate results. A null result means the contact could not be resolved from any provider in the selected chain.
The built-in waterfall plays use a fixed configured provider chain that balances price and result quality. 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