Playbooks · Recipe
Find the address, then verify it. Both legs are waterfall endpoints, so a call where the providers 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.
Last updated September 22, 2026
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.
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.
# Leg 1 — find. Waterfall: providers 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. Providers 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"}'
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.
Pass company_name alongside the domain when you know it.
It is optional and it improves accuracy at no extra cost.
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.
Only call email_verifier when leg 1 produced an address.
There is nothing to verify otherwise and the call has no input.
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.
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.
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.
`email_finder` and `email_verifier` are both **waterfall endpoints**. A waterfall call runs multiple providers, cheapest-first, until one returns data. Three outcomes: - **A provider returns data.** 2xx, `success: true`, billed. You pay 5 credits per call for the finder, 2 credits per call for the verifier. - **Every provider ran and none returned data.** This is a soft fail: 2xx, `success: false`, `billed: false`. **Zero credits.** Every provider 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.
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](/tools/waterfall-cost-calculator) does the arithmetic once you have your own number.
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 provider roster, because it changes as we add and drop providers. 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.
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.
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.
**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 provider 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](/api/phone-finder). **Does this work through MCP?** Yes, same endpoints, same key, same credit pool. See [Claude](/integrations/claude), and [agent driven account research](/use-cases/agent-driven-account-research) for the pattern. **Do I need a card?** No. 25 free credits, which runs this chain on roughly three people end to end, enough to see a real `billed: false` response with your own eyes.
[email finder](/api/email-finder) and [email verifier](/api/email-verifier) for the endpoint detail, [use cases](/use-cases) for the other plays, [list build and verify](/use-cases/list-build-and-verify) for the search leg that feeds this chain, and [Hunter](/alternatives/hunter) for how this differs from a per-lookup credit model. Tiers on [pricing](/pricing). **25 free credits, no card.** Run one name you expect to miss and watch it cost nothing.