> ## 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

> How Deepline uses a configured sequence of data actions to resolve one bounded result without assuming a fixed provider order or price.

A waterfall is a sequence of data actions aimed at one bounded result.
The sequence continues while the current candidate does not satisfy its
acceptance rule, then stops when the rule is met. For a work-email route, the
result might be an address accepted by the Play's configured validation logic.

The mechanism trades extra attempts against coverage, time, and usage. It does
not make a returned value correct simply because several providers were
available, and it does not require consulting every provider on every row.

![An illustrative email route validates candidates and stops after an accepted result.](https://mintcdn.com/deepline2/kWeIWxXOtxzX0DVg/images/waterfall-enrichment-flow.png?fit=max\&auto=format\&n=kWeIWxXOtxzX0DVg\&q=85\&s=e7df65262d547d302bcdb8b6d9fe200e)

A miss advances to the next configured step. A result that meets the acceptance rule skips later steps.

## A response and an accepted result are different

A finder can complete its request yet return no address. It can also return a
candidate whose identity or validation status is unsuitable. The Play's rule
must distinguish those conditions from a provider error.

In the maintained name-and-domain email route, the logic tracks candidates,
validation outcomes, source information, and attempts. It stops according to
that route's acceptance logic. A different Play may have different input,
identity requirements, or result rules.

`email_validated` describes the current Play's validation gate. It is not a
promise that a message will arrive, that the person still works at the company,
or that contacting them is appropriate.

## Provider order changes the work actually performed

Suppose a route uses three sources. If the first produces an accepted result,
later source calls can be skipped. If it returns no usable candidate, the next
source has an opportunity to resolve the gap.

This means the route's effective cost and latency depend on the input mix.
A list of known profiles can follow a different path from ambiguous names.
The sum of all published source prices is not automatically the cost of every
waterfall row.

Provider order can also be a quality choice. A source with high raw coverage
might be a poor first choice when many candidates fail the required identity
check. The acceptance rule and the evaluation segment belong in the comparison.

## A miss is useful information

No result is a valid outcome for a bounded lookup. It tells the downstream
process that the current route did not establish the required fact. Inventing a
value or silently treating a conflict as accepted would hide that boundary.

An error carries a different meaning: the source or execution did not complete
under its contract. Some routes can continue after specific recoverable errors;
others must stop. Authentication, billing, or invalid-input failures should not
be described as ordinary lack of coverage.

## A maintained route and a custom workflow solve different needs

A prebuilt route is useful when its identity inputs and output contract fit the
request. Custom code is justified when the team needs a different acceptance
rule, provider sequence, review policy, or destination action.

Direct tool access can be preferable when a particular provider's result is
itself the requirement. A waterfall optimizes for its accepted outcome; it does
not guarantee that every provider's data will be returned for comparison.

Provider availability, schemas, and supported billing modes can change. The
live contract explains what a route currently supports. A diagram is a mental
model, not an immutable provider list.

## Usage follows the applicable call contracts

A successful request may still yield no usable result, and some actions charge
for requests rather than returned matches. Validation or fallback attempts can
also contribute usage. Managed and BYOK access have different billing terms.

Completed runtime work can be reused when its cache contract applies.
Independent cache misses and intentional refreshes can execute again. A
waterfall's stop rule is not a guarantee that a later run has no charges.

## Continue learning

* [Evaluating an enrichment waterfall](https://deepline.com/docs/guides/b2b-data-enrichment-waterfall.md): coverage, acceptance rules, and source overlap.
* [Understanding enrichment cost](https://deepline.com/docs/guides/enrichment-cost-optimization.md): marginal attempts and accepted-output economics.
* [Email waterfall guide](https://deepline.com/docs/plays/email-waterfall.md): run and inspect a maintained route.
* [Prebuilt catalog](https://deepline.com/docs/plays/catalog.md): exact identifiers and required inputs.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.