How waterfall enrichment works, and what each usable result costs

In a three-provider email waterfall, the provider with the lowest price per email can end up with the highest cost per usable email. It depends on what each provider bills for. Some charge for every attempt, some charge for any email they return, and some charge only for an email that passes verification. The way you’re billed can actually matter more than the price per email.

Waterfall enrichment means asking providers for a value one at a time, in a fixed order, and stopping once one of them returns a value you accept. Building one means deciding which responses send a record on to the next provider, which result is good enough to stop on, and when to verify the value you got. It also means checking what each provider charges for, since that sets the total cost.

This guide covers those decisions, works through a cost example, and shows where an Enrich Layer call can sit in a sequence you build yourself.

How a waterfall runs, one record at a time

Suppose a work email waterfall with three providers. The input is a first name, a last name, and a company domain. Each provider below is described by how it bills, because that’s what matters for the design.

Every record starts at stage A. Records that get a deliverable email stop there and never reach B or C. Each later stage only sees the records the earlier stages missed, which is why later stages often find less and cost more per result.

Two rules sit around the sequence:

• The first is a stop rule. In this example, only a deliverable email ends the waterfall, and catch-all addresses keep going. Accepting catch-alls is also a valid choice, and it lowers cost while raising bounce risk.
• The second is a write rule, which is a result from the waterfall shouldn’t overwrite a value already in your CRM unless you decide it should. HubSpot's enrichment, for example, keeps existing data unless you turn on overwriting (HubSpot knowledge base).

Run a separate waterfall for each field

Most waterfall tools run one waterfall per field. Work email has its own provider order, phone has another, and company data may have a third. That makes sense, because providers differ by field. A provider that’s reliable on work emails may have few mobile numbers.

Field-level waterfalls have a side effect. One record can end up with values from different providers that disagree with each other. A phone number from one provider can belong to the person's previous job while the email from another provider reflects the current one. If you run separate waterfalls, check that the fields on a record still describe the same person at the same company.

What counts as a miss

"No result" covers several different situations. Each one should be handled differently, and providers bill them differently.

The same API can signal a miss in more than one way. Convert every kind of miss into one internal state before your waterfall logic sees it.

Check each provider’s documentation for what it charges on a miss. “Pay only when found” usually means you pay when the provider finds something, whether or not that value turns out to be usable.

Decide what counts as done

The stop rule decides when a record leaves the waterfall. There are three common choices.

1. Stop on any value. The first provider that returns an email wins. This is the cheapest rule and the least strict.
2. Stop on a verified value. The waterfall continues until a value passes verification or every provider has been tried. This lets fewer bad emails through and costs more, because records that would have stopped early keep going.
3. Make it a setting. Some tools let you choose between the first two.

Two more decisions can be associated with the stop rule. The first is your catch-all policy. Decide once whether catch-all addresses end the waterfall, and apply that to every provider. The second is a limit on repeated failures.

If three providers return the same email and your validator rejects it each time, a fourth provider may return it again. Stopping after a set number of identical rejected results saves the cost of the remaining stages. Some tools offer this as a setting.

Where verification happens

You can verify in three places, and each costs something different.

• After each provider. Your validator checks every returned email before the waterfall decides whether to continue. This gives you one consistent definition of "valid," but you pay for a validation on every returned email, including ones that fail.
• Once at the end. The waterfall stops on any value, and your validator checks the final result. Validation costs less, but an email that fails has already ended the waterfall, so you would need a second pass to find a replacement.
• Inside the provider. Some providers verify before returning and charge only for verified results. You save the validation step, but each provider's "verified" may mean something slightly different.

If you use more than one provider that verifies internally, consider running your own validator on their results anyway, so every email in your CRM meets the same standard.

What a usable email costs

This example uses the three-stage sequence from earlier. Every number here is invented to show the arithmetic. They are not measurements of any provider, including ours.

Assumptions for 1,000 input records:

• Provider A costs $0.01 per attempt. It returns an email for 50% of the records it sees, and 70% of those pass validation.
• Provider B costs $0.04 per returned email and nothing on a miss. It returns an email for 40% of the records it sees, and 50% of those pass validation.
• Provider C costs $0.08 per verified email and nothing otherwise. It returns a verified email for 25% of the records it sees.
• Your validator costs $0.005 per check and runs on results from A and B.

Provider B charges half as much per email as provider C, yet each usable email from B costs more. B is paid for every email it returns, half of those fail validation, and every one of them also costs a validation check. C is paid only for emails that are already verified.

The overall figure of $0.057 hides how different the stages are. Stage A produced 350 usable emails for $12.50. Stage B produced 130 for $11.70. The cost per usable email at each stage is the number to look at when deciding whether a stage is worth keeping.

It’s tempting to recalculate the example with C moved ahead of B, but the rates above would no longer hold. A provider's hit rate depends on which records reach it, and that depends on its position in the order. Moving C earlier means C sees easier records, so its hit rate would go up and B's would go down. The only reliable way to compare two orders is to run both on the same sample.

To run the same numbers for your own waterfall:

1. For each stage, multiply the records that reach it by what you pay per record there: attempt charge + hit rate x charge for a returned value and its validation. Add the stages together for total spend.
2. For each stage, multiply the records that reach it by the hit rate and by the share that pass validation. Add the stages together for usable results.
3. Divide total spend by usable results.

Choosing the provider order

Keep in mind the four things that decide the order.

• Billing model. A provider that charges only for verified results costs nothing for the records it can't help with. A provider that charges per attempt costs the same for every record that reaches it.
• Usable-result rate. Measure how many results pass your validator. A count of returned results overstates a provider's value when many of them fail. A provider that returns an email for most records but fails validation on half of them is weaker than its find rate suggests.
• Latency. Each stage adds at least one round trip. If the waterfall runs while a person waits, a slow provider early in the order delays every record.
• Rate limits. Each provider has its own limit, and your throughput is capped by the slowest stage that most records reach.

Cheapest-first keeps spend low on easy records, because the expensive providers only see the records the cheap ones missed. Strictest-first puts the provider with the best validation results at the front, so fewer weak emails reach your CRM. In general, neither order is right. A small test on your own records will show which one gives you the lower cost per usable email at the quality you need.

Waterfall vs multi-source enrichment

A waterfall and multi-source enrichment are easy to confuse, because both use more than one source. They solve different problems.

The two approaches work well together. A common setup is to get the person's profile from a provider that already combines several sources, run a separate waterfall for each contact field, and pass every contact value through one validator.

We wrote about how merged records get built, and where they go wrong, in the case for multi-source public web data. Neither approach guarantees a correct value. Both reduce the number of records with no value at all.

Running a waterfall in production

Most production problems with waterfalls come from timing, retries, and cost tracking.

• Results arrive later. Many waterfall tools and some individual endpoints return results through a webhook or require polling. Design for a record to be "in progress" for a while, and check the result status in the response body as well as the HTTP status code.
• Retries can charge twice. If a request times out on your side but finished on the provider's side, a retry is a second billed request. Keep a record of what you've already sent, and assume a repeated request is billed again unless the provider documents otherwise.
• Avoid paying for the same record twice. Some tools skip a provider that already returned data for the same contact within a set number of days. If you build your own waterfall, keep your own cache keyed on the input, with a refresh interval that matches how often the field changes.
• Track spend per stage. If you connect providers with your own API keys inside a workflow tool, the tool may only show its own usage. Record the cost of each call so you can compute cost per usable result by stage.
• Respect each provider's rate limit. Throttle per provider and back off on 429 responses.

Where Enrich Layer fits in a waterfall

Enrich Layer is an API you call as one stage in a sequence you design. It returns its own result, and you decide how the providers work together. It fits in two places.

Before the contact stages, as the identity step. Contact lookups work best when they start from the right person. Person Lookup takes a first name and a company domain and returns that person's profile URL. Role Lookup does the same from a job title and a company, and Reverse Email Lookup starts from an email address. Later stages can then key off the profile URL.

Person Lookup also returns similarity scores between 0 and 1 for the inputs you sent, such as the name and company. You can use them as a confidence threshold. A low score sends the record down the "below threshold" path in the table above.

As a contact stage. Work Email Lookup takes a profile URL and returns a work email. The request is accepted right away, and the result is sent to your callback URL. If no work email is found, the credits for that request are refunded. Personal Email Lookup and Personal Contact Number Lookup are charged per item returned, so an empty result costs nothing.

1. Identity   GET /api/v2/profile/resolve?first_name=Jane&company_domain=example.com
              →  profile URL, or a null result

2. Contact    GET /api/v2/profile/email?profile_url=<profile URL>&callback_url=<your callback URL>
              →  request accepted; your callback URL later receives email_found or email_not_found

How a miss looks, and whether it is charged, depends on the endpoint. Normalize these into one "no result" state, as described in Search API vs enrichment API.

Errors such as 400, 401, 429, 500, and 503 are not charged (errors guide). For throughput, see the rate limits guide. If you build your waterfall in Clay, you can call Enrich Layer through Clay's HTTP API column (Clay setup guide).

Test the order on a sample before you commit

Before running a waterfall across your whole list, run it on a fixed sample of a few hundred records that look like the rest of the list.

1. Write down your stop rule, your catch-all policy, and your write rule.
2. Run the sample through the order you plan to use. For each stage, record how many records reached it, how many results came back, how many passed validation, and what the stage cost.
3. Run the same sample through one alternative order.
4. Compare the cost per usable email at each stage and overall.
5. Drop any stage whose cost per usable email is higher than a usable email is worth to you.

Repeat the test when you add a provider, change the stop rule, or start enriching a different kind of record.