Playbooks / Recipe
Waterfall Email Then Verify: The One Chain Where Every Leg Is Miss-Free
Find the address, then verify it. Both legs are waterfall endpoints, so a call where the sources run and return nothing comes back 2xx with `success: false` and `billed: false`, costing zero credits. This is the only two-step chain in the catalog where that holds end to end.
Pattern: email_finder (name + domain, or a LinkedIn URL) → if it returns an address, email_verifier on that address → store the verdict with a timestamp. Two calls, two receipts, no charge for either leg coming back empty-handed.
In short: The RichAPI chain email_finder followed by email_verifier is a two-call sequence in which both endpoints are waterfall endpoints. On a waterfall endpoint, a soft fail, meaning every source ran and none returned data, comes back as a 2xx response with success:false and billed:false and costs zero credits. This makes it the only two-step chain in the RichAPI catalog where neither leg bills on a miss. email_finder accepts first_name plus last_name plus company_domain, or a linkedin_url, with optional company_name; email_verifier accepts a single email address. The verifier's zero-cost case is specifically a failure to reach a verdict, not a verdict of invalid: an address that verifies as invalid, risky or catch-all is a delivered result and bills normally. Non-2xx responses never bill on any endpoint. Every other RichAPI endpoint, including enrich_company, enrich_profile, the search endpoints and the scrapers, bills on any 2xx response, including an empty one. Each leg of this chain returns its own `execution_log`, one entry per attempt with a status, so you can see which of the two legs actually spent anything. Base URL https://api.richapi.ai/api/v1/, auth via an x-api-key header. New accounts get 100 free credits with no credit card.
Last updated November 4, 2026
Credit math
1,000 people through the chain at a 60% finder hit rate: email_finder at 5 credits per call bills on 600, not 1,000, for 3,000 credits, and the 400 misses are free. email_verifier at 2 credits per call runs on the 600 found addresses only, for 1,200 credits. Total 4,200 for 1,000 attempts. Swap your own hit rate in at /tools/waterfall-cost-calculator; the one above is an illustration, not a measured rate.
ROI math
Against a per-lookup credit model, the difference is not the sticker price, it is what a failed lookup costs. Work out what fraction of your list is unfindable, because that fraction is the whole comparison. Credit tiers on /pricing.
Owned internally by
Whoever writes the loop. This is two HTTP calls and a conditional.
Best for
Anyone whose current email tool charges for attempts, and anyone who needs a cost-per-verified-address number they can put in a spreadsheet.
- 01
Send the best input you have.
email_finder takes either first_name + last_name + company_domain, or a linkedin_url. The LinkedIn URL is the stronger input when you have it, at the same price.
- 02
Pass company_name alongside the domain when you know it.
It is optional and it improves accuracy at no extra cost.
- 03
Branch on the response, not on the HTTP status.
A miss is a 200. Read success and billed rather than assuming a 200 means an address arrived.
- 04
Only call email_verifier when leg 1 produced an address.
There is nothing to verify otherwise and the call has no input.
- 05
Store the verifier verdict with the date it was produced.
Re-running the chain on rows you already resolved is the most common way to spend credits twice.
- 06
Log the execution_log on both legs.
It is the only record of which providers ran on that request, and it cannot be reconstructed afterwards.
# Leg 1 — find. Waterfall: sources run cheapest-first.
curl -s https://api.richapi.ai/api/v1/email_finder \
-H "x-api-key: $RICHAPI_KEY" \
-H "content-type: application/json" \
-d '{
"first_name": "Dana",
"last_name": "Weiss",
"company_domain": "acme.com",
"company_name": "Acme"
}'
# A soft fail returns 200 with success:false and billed:false.
# Zero credits. sources ran; you did not pay for them.
# Leg 2 — verify, only if leg 1 returned an address.
curl -s https://api.richapi.ai/api/v1/email_verifier \
-H "x-api-key: $RICHAPI_KEY" \
-H "content-type: application/json" \
-d '{"email": "dana.weiss@acme.com"}'
Waterfall email then verify: the one chain where every leg is miss-free
Two calls. Find the address, then check it's real. It's the shortest useful chain in the catalog and the only one where both halves refuse to charge you for coming up empty.
That claim gets thrown around loosely in this market, so here is the precise version before anything else.
What "miss-free" means here, exactly
email_finder and email_verifier are both waterfall endpoints. A waterfall call runs multiple sources, cheapest-first, until one returns data. Three outcomes:
- A source returns data. 2xx,
success: true, billed. You pay 5 credits per call for the finder, 2 credits per call for the verifier. - Every source ran and none returned data. This is a soft fail: 2xx,
success: false,billed: false. Zero credits. Every source in that chain was paid by us. You were not. - The request failed. Non-2xx. Never bills, on any endpoint in the catalog.
Now the part that matters on the verifier leg, and that most pages in this space blur. The verifier's free case is a failure to reach a verdict, not a verdict you dislike. An address that comes back invalid, risky or catch-all is a result, and the endpoint did exactly the job you paid for, and it bills. You are not being charged for finding out an address is dead; you are being charged for finding out, full stop. A verifier that only billed for "valid" would be a verifier with an incentive to say valid.
The scope is narrow, so be clear about it. This applies to email_finder, email_verifier and phone_finder. Everywhere else in the catalog (enrich_company, enrich_profile, find_personal_email, people_search, every scraper) a 2xx bills, including a 2xx that comes back empty. We would rather write that here than have you discover it on an invoice.
Why this changes the arithmetic, not the price
Per-lookup pricing hides its real cost in your hit rate. Take 1,000 people. At 5 credits per call, a model that charges for attempts charges for 1,000. This one charges for however many produced an address.
So the comparison isn't sticker price, it's price × hit rate, and the hit rate is a property of your list, not of the vendor. A list of VPs at 2,000-person software companies finds well. A list of tradespeople scraped off a directory does not, and that's the list where the billing model earns its keep. Run 200 rows and measure, don't take anyone's published rate, including ours. waterfall cost calculator does the arithmetic once you have your own number.
The receipt on find then verify
Both legs return an execution_log showing who ran and what each returned. The billed field comes back alongside it.
We don't publish the source roster, because it changes as we add and drop sources. The log is the honest substitute: rather than a list on a marketing page, you get the per-call record of who ran on your request. It's also the only diagnostic you'll get: the log is how you tell a person who isn't findable from a call worth retrying.
The failure mode: treating a 200 as a success
This is the bug we see most, and it's a one-line bug. Code checks response.ok, gets true on a soft fail, and writes undefined into the email column. A week later there's a list of rows that look enriched and aren't, and nobody knows which calls missed because the execution_log was never logged.
Branch on success and billed, not on the status code. A miss is a 200 by design, because it's a valid answer to a valid question, and the answer is "no such address was found".
The smaller bug is verifying rows the finder missed. There's no address to send, so the call has no input. Gate leg two on leg one producing something.
Where find then verify goes wrong
Two calls, one address. No enrichment, no personal emails, no phone. find_personal_email at 5 credits per call is a different endpoint and it is not a waterfall. It bills on a 2xx. Don't assume the billing model travels with the word "email".
Nothing here sends. The chain ends with a verified address in your store; the sequencer is yours.
Find then verify FAQ
If the verifier says catch-all, was I charged? Yes. Catch-all is a verdict, and reaching a verdict is the service. The free case is when no source could produce one at all.
Can I retry a miss for free? Mechanically, yes: a second soft fail also costs zero. Practically, retry with a better input (a LinkedIn URL instead of name-plus-domain) rather than firing the same body twice.
Is phone_finder the same deal? Yes, and at 25 credits per call the miss-free part matters more there than anywhere else in the catalog. See phone finder.
Does this work through MCP? Yes, same endpoints, same key, same credit pool. See Claude, and agent driven account research for the pattern.
Do I need a card? No. 100 free credits, which runs this chain on roughly twelve people end to end, enough to see a real billed: false response with your own eyes.
Where to go after find then verify
email finder and email verifier for the endpoint detail, use cases for the other plays, list build and verify for the search leg that feeds this chain, and Hunter for how this differs from a per-lookup credit model. Tiers on pricing.
100 free credits, no card. Run one name you expect to miss and watch it cost nothing.
FAQ