Waterfall enrichment
Updated October 21, 2026
Waterfall enrichment is a lookup pattern that sends the same request to several data sources in a fixed order and stops at the first one that returns a usable result. It fills more records than any single source in the sequence can fill alone. The cost depends on how each step is billed, because a miss can be free or charged.
In short: Waterfall enrichment queries data sources one after another for the same record, such as a work email, and stops at the first source that returns a result, which fills more records than one source.
How waterfall enrichment works
A waterfall asks the same question of several sources until one answers. You may also see it called a provider cascade or multi-provider enrichment. In this glossary those names mean the same thing.
The run has four parts. You send one input, for example a first name, a last name and a company domain for an email search. The first source in the order tries to answer. If it returns a usable value, the run stops and returns that value. If it returns nothing, or a value that fails a check, the next source tries. The run ends at the first hit or when the list of sources runs out.
Order sets cost and speed. A cheap or fast source in first place lowers the average cost per record. The source with the best data for your segment in first place raises the chance that step one answers. Each extra step adds time, because the steps run one after another. Teams tune the order against their own match rate.
Billing decides whether a waterfall saves money. It only beats a single lookup on cost when a miss costs less than a hit. At RichAPI the waterfall endpoints are Email finder, Email verifier and Phone finder, and a call where no source returns data costs zero credits 1. Every other endpoint, including Profile enrichment and Company enrichment, bills on any 2xx response, even an empty one 1.
A waterfall is one way to run data enrichment. It often pairs with email verification, because an address that a source found still needs a deliverability check before you send to it.
Waterfall enrichment cost formula
The cost of a batch follows from three numbers. On a waterfall endpoint that bills only on hits, cost equals the number of records, times the hit rate, times the credits per hit 2. On a source that bills every lookup, cost equals the number of records times the credits per call, whatever comes back 2.
A worked case with sample numbers shows the gap. Take 1,000 records and Email finder at 5 credits per call 1. If 60 percent of the records return an email, the batch costs 1,000 times 0.6 times 5, which is 3,000 credits 2. The 400 records that return nothing cost zero, because Email finder is a waterfall endpoint 1. The 60 percent figure is the calculator's sample value, and your own hit rate depends on your list 2.
The two models cost the same when the per-lookup price equals the hit rate times the per-hit price 2. When the per-lookup price is lower than that, the per-lookup source is cheaper. When it is higher, the waterfall is cheaper 2. Run a sample of your own list first, measure the hit rate, and then price the full batch.
Example of waterfall enrichment
The RichAPI Email verifier reference documents what a waterfall miss looks like in a response 4. The endpoint runs several sources in turn. When none of them reaches a verdict, the response keeps the same envelope with success set to false, result set to null, provider set to null and billed set to false, and that call bills zero credits 4.
A trimmed miss response has this shape. The field names come from the reference, and the values are samples.
{
"success": false,
"result": null,
"provider": null,
"billed": false,
"execution_log": [
{"provider": "provider", "status": "no_data"},
{"provider": "provider", "status": "no_data"}
]
}The execution_log holds one entry per source attempt, and the public reference redacts the source names 4. The reference also notes that execution_log is not listed on the public OpenAPI schema, so treat it as an envelope shape and not as a contract to code against 4.
When you audit a bill, note what counts as a hit. A verdict counts as a delivered result even when the verdict is bad. The RichAPI catalog states that an address that verifies as invalid, risky or catch-all bills normally, and that the zero-cost case covers only a call where no verdict was reached 1. Check a sample of real responses before you build reports on them, so that your audit counts billed and unbilled calls the same way the bill does.
Waterfall enrichment vs single-source enrichment
Single-source enrichment sends each record to one source. It is faster and easier to debug, and it returns nothing for any record that source does not cover. A waterfall adds time for each extra step, in exchange for more records filled. The choice depends on coverage and on billing. If one source already returns a value for nearly every record in your segment, extra steps add time and little else. If coverage is patchy, each extra step can fill records that the first source missed. Billing changes the result. When misses are free, extra steps cost credits only on the records they fill. When every lookup bills, each extra step adds cost to every record that reaches it, filled or not.
| Waterfall enrichment | Single-source enrichment | |
|---|---|---|
| What it answers | Which of several sources can fill this field? | What does this one source know? |
| Input | One input, passed down the source order | One input, sent once |
| Output | The first usable value, plus a per-step log when the API returns one | Whatever the source returns, which may be empty |
| Cost driver | Hits, when misses are free | Every call |
| Main risk | Paying for empty steps when misses are billed | A low match rate on segments the source covers poorly |
| Use it when | Coverage matters more than speed, such as finding emails for a cold list | You need speed and the source covers your segment |
Frequently asked questions
What is waterfall enrichment in Clay?
Clay describes waterfall enrichment as searching sequentially across multiple tools until you find a valid match 3. The idea is the same in any tool or API. What changes between tools is which sources run, in what order, and how each step is billed.
Do I pay for misses in a waterfall?
It depends on the tool. At RichAPI, a call to Email finder, Email verifier or Phone finder where no source returns data costs zero credits 1. Other RichAPI endpoints bill on any 2xx response, including an empty one 1.
How many sources should a waterfall use?
Use as many as raise your hit rate on a test sample, and stop adding sources when the next one fills almost no new records. Measure on your own list, because the hit rate is a property of that list and a vendor cannot supply it for you 2.
Is waterfall enrichment the same as data enrichment?
No. Data enrichment is the goal, adding fields to records you hold. Waterfall enrichment is one way to reach it, by asking several sources in a fixed order and stopping at the first answer. A call to a single source is another way.
The bottom line
Waterfall enrichment asks several sources in a fixed order and stops at the first usable answer. It fills more records than one source, and its cost depends on whether misses are billed. Before you run a batch, check the billing rule for misses, run a sample to measure your own hit rate, and confirm the response shows which step answered.