Key takeaways
- A waterfall queries sources in a deliberate sequence with explicit stopping rules.
- Evaluate each additional source by incremental accepted coverage and cost.
- Multiple agreeing providers may still share the same underlying source or stale error.
Overview
The waterfall can operate by record or by field. A company domain may be accepted from one source while a contact address requires another. Source order should reflect coverage, quality, latency and cost. “Found” should mean the result passed your criteria, not merely that an API returned text. Stop rules prevent unnecessary calls and spending.
How it works
Choose the required fields, source order and acceptance thresholds.
Query the next source only for unresolved or unacceptable fields.
Validate the combined record and retain the source for each accepted value.
Design the stopping rule first
A waterfall is useful when one source does not cover the entire target population. The first source handles eligible lookups; unresolved fields or records move to another source. Define what counts as resolved before starting. A returned value should meet the entity-match and field-quality criteria, not merely be nonempty.
The sequence can differ by field or segment. One provider may be useful for company identity while another supplies a particular contact attribute. Passing a record onward should include the accepted context and the unresolved question. Repeating a broad lookup at every stage wastes work and can create conflicting values without a policy for choosing among them.
| Result | Next step | Reason |
|---|---|---|
| Accepted required field | Stop that field’s lookup | The stated requirement has been met |
| Valid no-match | Try an eligible next source | Coverage may differ |
| Ambiguous entity | Resolve identity before continuing | More attributes could reinforce the wrong match |
| Service failure | Use a bounded recovery policy | An outage is different from absent data |
Measure marginal coverage, not provider count
In an illustrative 100-record run, source A supplies 60 accepted results and source B adds 20 among the unresolved records. Combined accepted coverage is 80%, not the sum of each provider’s headline coverage claim. If source B costs $10 for its incremental work, its added lookup cost is $0.50 per newly accepted result before review.
A third source that returns 15 values but adds only two accepted records may have poor marginal value. Investigate whether it overlaps with earlier sources, targets the wrong segment or produces conflicts. More providers can improve coverage, but provider count alone does not establish correctness, freshness or cost effectiveness.
Preserve lineage across the sequence
Keep the source, date and acceptance reason for each chosen field. If two providers disagree, a later result should not automatically win merely because it arrived later in the waterfall. Their observation dates, methods and entity matches may differ. A reviewer needs those facts to resolve the conflict.
Also account for shared upstream data. Agreement between providers is less persuasive when both repeat the same original directory. Sample the final results against independent evidence and inspect the unresolved population. A high overall yield can hide a persistent gap in one geography or company type that matters disproportionately to the user’s objective.
What this looks like in practice
Source A supplies a company domain but no verified contact. The workflow keeps the domain, checks source B for the contact and stops after verification succeeds, avoiding a third lookup.
Examples explain the concept; they are not reported customer results.What to check
Compare incremental accepted coverage and marginal cost at each stage. Check correlated sources: multiple providers may repeat the same underlying record.
Common mistake
Calling every provider for every row, then describing the process as an efficient waterfall without measuring what each additional source contributes.
Waterfall enrichment vs. Data enrichment
Data enrichment is the broader activity of adding context. A waterfall is one strategy for selecting and sequencing the sources used to do that work.
Read the Data enrichment definition →Questions answered
What is Waterfall enrichment?
Waterfall enrichment queries an ordered sequence of data sources, moving to another source when required information is missing or fails an acceptance rule, until the workflow reaches its stopping condition.
Does a waterfall guarantee complete data?
No. Sources can share the same gaps or return uncertain results. Report unresolved fields honestly and define a budget or source limit.
Should the cheapest source always go first?
Not necessarily. A cheap source with poor matching can create correction costs. Evaluate accepted quality, coverage and latency alongside the request price.
Is waterfall enrichment always sequential?
The core idea is ordered fallback based on unresolved needs. Independent fields or records may be processed concurrently, but the system still needs rules for acceptance, conflicts and stopping. Calling every provider at once without those rules is multi-source collection rather than a carefully controlled fallback strategy.
Does a waterfall guarantee a verified email?
No. A source can return an address without establishing current deliverability, and verification itself has uncertainty. Keep discovery and email-verification status distinct. A waterfall should preserve unknown or catch-all results rather than relabel them as verified simply because several sources returned the same address.
References and further reading
Primary documentation and source material for this topic. Sources checked September 14, 2026; provider requirements can change.
Continue reading on the blog
Explore all articles and guides →Put the concept to work.
Explore the relevant AstroFabric workflow and see how the pieces connect.
Help keep this guide useful. Suggest a correction or browse the full glossary.