> ## Documentation Index > Fetch the complete documentation index at: https://deepline.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Waterfall Enrichment > Waterfall enrichment queries up to 6 providers in cost order and stops at the first valid hit. Use it to understand tradeoffs and operating boundaries. 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. | Attribute | Value | | --------------------------------- | ---------------------------------------------------------------------------------------------- | | Dashboard-visible prebuilt plays | See generated catalog below | | Default email waterfall providers | 6 (Dropleads, Hunter, LeadMagic, Deepline Native, Crustdata, PeopleDataLabs) | | Cost-aware waterfall steps | 8 (3 pattern-guess + 5 finder providers) | | Production providers in platform | 29 | | Cost per email find | 0.2-0.6 credits (\$0.016-\$0.048) | | Cost for misses | BYOK: 0 credits. Managed: provider per-call costs (typically 0.3-1.2 credits across the chain) | | Single-provider email coverage | Varies by ICP and region | | Waterfall email coverage | Varies by ICP and region | | Waterfall logic | Sequential, cost-ordered, stop-on-first-valid-hit | | BYOK mode | Supported -- 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.** B2B contact data decays at roughly 22.5% per year ([HubSpot via Cognism](https://www.cognism.com/blog/data-decay)), 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/`. Batch counterparts, hidden support plays, and legacy tool aliases are intentionally excluded. | Play | Canonical reference | Required input | | -------------------------------------- | ----------------------------------------------- | -------------------------------------------------------- | | Work Email from Name and Domain | `prebuilt/name-and-domain-to-email-waterfall` | `first_name`, `last_name`, `domain` | | Work Email from LinkedIn Profile | `prebuilt/person-linkedin-to-email` | `linkedin_url` | | Personal Email Finder | `prebuilt/personal-email` | `first_name`, `last_name` | | Mobile Phone from Person | `prebuilt/person-to-phone` | `first_name`, `last_name` | | Job Change Detection | `prebuilt/job-change-check` | None | | LinkedIn Profile from Personal Email | `prebuilt/personal-email-to-linkedin` | `personal_email` | | LinkedIn Profile from Name and Company | `prebuilt/person-to-linkedin` | `first_name`, `last_name` | | LinkedIn Post Engagers | `prebuilt/linkedin-post-to-engagers` | `post_url` | | LinkedIn Employees from Company Domain | `prebuilt/company-domain-to-linkedin-employees` | `domain` | | ICP Qualification for Engagers | `prebuilt/engagers-to-icp-qualification` | `first_name`, `last_name`, `position`, `icp_description` | 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/` reference when selecting a prebuilt play directly. ## Example CLI commands ### Single email lookup ```bash theme={null} deepline enrich --with '{"alias":"email","tool":"name_and_domain_to_email_waterfall","payload":{"first_name":"Sarah","last_name":"Chen","domain":"stripe.com"}}' ``` ### Bulk CSV enrichment ```bash theme={null} deepline enrich --input leads.csv --output enriched.csv \ --with '{"alias":"email","tool":"name_and_domain_to_email_waterfall","payload":{"first_name":"{{first_name}}","last_name":"{{last_name}}","domain":"{{domain}}"}}' ``` ### LinkedIn URL to email ```bash theme={null} deepline enrich --with '{"alias":"email","tool":"person-linkedin-to-email","payload":{"linkedin_url":"https://linkedin.com/in/sarahchen"}}' ``` ### Find decision makers at a company ```bash theme={null} deepline enrich --with '{"alias":"contacts","tool":"company_to_contact_by_role_waterfall","payload":{"company_name":"Stripe","domain":"stripe.com","roles":["VP Engineering","CTO"],"seniority":["VP","C-Level"]}}' ``` ### Personal email lookup ```bash theme={null} deepline enrich --with '{"alias":"personal","tool":"personal_email_waterfall","payload":{"first_name":"Sarah","last_name":"Chen","linkedin_url":"https://linkedin.com/in/sarahchen"}}' ``` ### 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 Ramp (ramp.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: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](/docs/plays/email-waterfall) | [Find Work Email](/docs/plays/task-find-work-email) | [Plays Overview](/docs/plays/plays-overview) | [Find Decision Makers](/docs/plays/task-find-decision-makers) | [Quick Start](/docs/quickstart)