Playbooks / Recipe
Phone Append After an Email Hit: The 25-Credit Call That's Free When It Misses
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 sources 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.
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.
In short: RichAPI appends a mobile phone number after a work email is found, in two calls: /email_finder first, then /phone_finder only on rows where the email call returned an address. Both endpoints are waterfall endpoints, meaning several sources are tried cheapest-first and a soft fail, where all sources ran and none returned data, comes back as a 2xx response with success:false and billed:false and costs zero credits. This makes both legs of the chain miss-free end to end, which is true of only a small number of RichAPI chains. email_finder costs 5 credits per successful call and phone_finder costs 25 credits per successful call, the highest per-call price in the RichAPI catalog. phone_finder accepts either a linkedin_url, or first_name plus last_name plus domain, at the same price. Because the phone hit rate on a typical list is well below 100 percent, the effective cost per phone number obtained is substantially higher than 25 credits, and callers should compute cost per number rather than cost per call. All other RichAPI endpoints bill on any 2xx response including an empty one; non-2xx responses never bill on any endpoint. New accounts get 100 free credits with no credit card.
Last updated November 4, 2026
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.
- 01
Send a linkedin_url to phone_finder when the row has one.
It takes either linkedin_url, or first_name plus last_name plus domain, at the same 25 credits. On a call this expensive, use the input most likely to resolve.
- 02
Gate leg two on leg one's success field, not on the HTTP status.
A miss is a 200. Code that checks response.ok will fire the 25-credit call on every row including the 400 nobody can find.
- 03
Read billed on every phone_finder response and store it.
Summing that column is the only way to know what the run actually cost, and on a 25-credit endpoint the gap between attempts and charges is the number your finance team will ask about.
- 04
Log the execution_log on the phone leg specifically.
On a 25-credit call, the log is how you tell a person with no number from a call worth retrying.
- 05
Store a resolved_at date and never re-run a row you already resolved.
At 25 credits, a duplicate run is the single most expensive mistake available in this chain.
- 06
Do not fire phone_finder speculatively across a whole list to see what sticks.
It costs nothing on the misses and it will take a while, and the rate limits are real even though we do not publish numbers for them.
# 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 append after an email hit: the 25-credit call that's free when it misses
/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.
Both legs are miss-free, which is rare
email_finder, email_verifier and phone_finder are the waterfall endpoints. Multiple sources run cheapest-first. Three outcomes:
- A source returns data: 2xx,
success: true, billed. - Every source ran, none returned data: 2xx,
success: false,billed: false, zero credits. We paid those sources. 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 is the other clean one.
Make the arithmetic the argument
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.
Cost per number, not cost per call
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.
Why gate phone on the email hit
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 receipt, which matters more here
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 source roster, because it changes. The log is the substitute, and it's per-request rather than per-marketing-page.
The failure mode: firing the expensive leg on a 200
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.
Where phone append goes wrong
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.
Phone append FAQ
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 sources 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 source 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? 100 free credits cover four successful phone_finder calls. Run it on someone you already have a number for.
Where to go after phone append
phone finder for the endpoint detail, waterfall email then verify for the other fully miss-free chain, people search to email waterfall for building the list that feeds this one, bulk enrich without seats for running it at volume, and use cases for the rest. Tiers on pricing.
100 free credits, no card. One phone lookup, or several misses that cost you nothing, which is the more instructive test.
FAQ