Playbooks · Recipe
Find the email first, then append a phone number only to the rows that resolved. Both legs are waterfall endpoints, so both return `billed: false` and cost zero when providers find nothing. At 25 credits, the phone call is the most expensive in the catalog, which is exactly why the miss-free rule carries most of the value here.
Last updated September 22, 2026
Pattern: email_finder on the row → if success, phone_finder on the same person → store both with a date. Gating phone on the email hit is not a rule, it is a cheap proxy: a person your providers can find an address for is a person they are more likely to have a number for.
Credit math: 1,000 people. email_finder at 5 credits bills on the 600 that resolve at a 60% hit rate: 3,000 credits, 400 misses free. phone_finder at 25 credits runs on those 600 and, at a 30% phone hit rate, bills on 180: 4,500 credits. The 420 phone misses cost zero. Total 7,500 credits for 180 phone numbers and 600 addresses. Bill-on-attempt pricing for the same run would be 5,000 + 15,000 = 20,000 credits, and you would have paid 10,500 of that for 420 people nobody has a number for. Both hit rates are illustrations; measure yours.
ROI math: The whole trade is the miss rate on the 25-credit leg. At a 30% phone hit rate you pay for roughly one call in three, so your effective cost per number is around 83 credits, not 25. Under attempt-based pricing it would still be 83, you would just be paying it in a way that looks like 25. Compute your real cost per number, not per call. Credit tiers on /pricing.
Owned internally by: Whoever writes the loop. Two calls and a conditional.
Best for: Teams where a call connects and an email doesn't, and anyone who has been burned by a mobile-number vendor charging per attempt against a list with a 30% hit rate.
# Leg 1 — email. Waterfall: a miss is 200, success:false, billed:false, 0 credits.
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"
}'
# Leg 2 — phone, only on rows where leg 1 returned an address.
# Same billing shape. 25 credits on a hit, 0 on a soft fail.
curl -s https://api.richapi.ai/api/v1/phone_finder \
-H "x-api-key: $RICHAPI_KEY" \
-H "content-type: application/json" \
-d '{"linkedin_url": "https://www.linkedin.com/in/dana-weiss"}'
# phone_finder also accepts first_name + last_name + domain if you have
# no LinkedIn URL. Same price. The LinkedIn URL resolves better.
`/phone_finder` costs 25 credits on a hit. That is the most expensive single call in the catalog by a wide margin: five times `/email_finder`, twenty-five times `/enrich_company`. If you only read one number on this page, read that one. Now read the second one: on a miss it costs **zero**, and on a mobile-number list the miss rate is where all the money is.
`email_finder`, `email_verifier` and `phone_finder` are the **waterfall endpoints**. Multiple providers run cheapest-first. Three outcomes: - A provider returns data: 2xx, `success: true`, billed. - Every provider ran, none returned data: 2xx, `success: false`, **`billed: false`**, zero credits. We paid those providers. You didn't. - The request failed: non-2xx. Never bills, anywhere in the catalog. Chain `email_finder` into `phone_finder` and every leg is covered. That's unusual. Most two-step chains in this catalog have at least one leg that bills on any 2xx, `enrich_profile` and `enrich_company` and every scraper included. [waterfall email then verify](/use-cases/waterfall-email-then-verify) is the other clean one.
1,000 people. 60% email hit rate, 30% phone hit rate on the people you found an address for. Both illustrative, both things you should measure on 200 rows of your own list instead of believing ours. | Leg | Attempts | Billed | Credits | |---|---|---|---| | `email_finder` @ 5 | 1,000 | 600 | 3,000 | | `phone_finder` @ 25 | 600 | 180 | 4,500 | | **Total** | | | **7,500** | You end up with 600 addresses and 180 mobile numbers. Now price the same run under bill-on-attempt: 1,000 × 5 plus 600 × 25 = 20,000 credits. The difference is 12,500 credits, and **10,500 of that difference sits on the phone leg alone**, 420 attempts against people nobody has a number for. That's the page in one paragraph. The miss-free rule is worth roughly five times more on the phone leg than on the email leg, because the price is five times higher and the hit rate is half as good. Everything else here is detail.
Here's the number people get wrong in the other direction, and we'd rather say it than have you feel misled later. 180 numbers for 4,500 credits is **25 credits per billed call and about 83 credits per number you actually got**. The miss-free model doesn't make the phone leg cheap. It makes the sticker price honest: you pay 25 when there's a number, and the arithmetic that turns 25 into 83 is your list's hit rate, which is a property of your list. Under attempt pricing the effective cost would be 15,000 ÷ 180 = 83 too, plus you'd have paid it on 420 dead rows. Same effective rate, very different invoice. Budget against cost per number.
It isn't a rule, and mechanically nothing stops you calling `phone_finder` on every row, because the misses are free. It's a proxy. A person whose work address multiple providers could resolve is a person who exists in those providers' data, with a current employer and a current title. A person nobody could find an address for is often stale, private, or wrong in your source, and the phone leg will usually miss too. Gating costs you a handful of numbers and saves you a lot of wall-clock time on a list you'd rather finish today. If your use case is different, say you have verified emails already and only need numbers, skip leg one entirely and call `phone_finder` directly.
The phone leg hands back an `execution_log` showing who ran and what each returned. On a 5-credit call, nobody reads this. On a 25-credit call, read it. Retry with a `linkedin_url` instead of name-plus-domain rather than firing the same body twice. We don't publish the provider roster, because it changes. The log is the substitute, and it's per-request rather than per-marketing-page.
The bug is one line, and on this chain it's the expensive one. ``` if (res.ok) { callPhoneFinder(row) } // wrong if (body.success) { callPhoneFinder(row) } // right ``` A soft fail is a 200. `res.ok` is `true`. So the gate never gates, and `phone_finder` fires on all 1,000 rows instead of 600. You won't get billed for the extra misses, which is the point of the model, but you'll spend a long time getting nothing, and if the phone hit rate on unfindable people is anything above zero you'll pay 25 credits a pop for numbers attached to stale records. Cheaper but more common is leaving out a `resolved_at` column, so next month's run re-resolves everyone. At 25 credits a row that's the most expensive duplicate in the catalog.
No dialer, no sending, no sequencing, no compliance checking. You get a number in your store. Whether you're allowed to call it in your jurisdiction is a question this API does not answer and does not pretend to. Nothing here validates that the number is current beyond what the providers returned. There's no phone equivalent of `email_verifier`.
**Is phone_finder really free on a miss?** Yes, and it's the case where that matters most. 2xx, `success: false`, `billed: false`, zero credits. **Why is it 25 credits when email is 5?** Mobile numbers are expensive upstream and scarcer. The price reflects what the providers charge, and the miss-free rule is how we keep the scarcity from landing on you twice. **Can I run phone_finder without the email leg?** Yes. Send `linkedin_url`, or name plus domain. Same price. **Does a wrong number count as a hit?** If a provider returned a number, it bills. There's no verification leg for phone. That's a real limitation. **What's the cheapest way to test this?** 25 free credits is exactly one successful `phone_finder` call. Run it on someone you already have a number for.
[phone finder](/api/phone-finder) for the endpoint detail, [waterfall email then verify](/use-cases/waterfall-email-then-verify) for the other fully miss-free chain, [people search to email waterfall](/use-cases/people-search-to-email-waterfall) for building the list that feeds this one, [bulk enrich without seats](/use-cases/bulk-enrich-without-seats) for running it at volume, and [use cases](/use-cases) for the rest. Tiers on [pricing](/pricing). **25 free credits, no card.** One phone lookup, or several misses that cost you nothing, which is the more instructive test.