Data catalog · Enrichment
Send a LinkedIn profile URL, or a name plus a company domain, and get back a mobile number in E.164 format with a status label. Runs a provider waterfall, cheapest-first. When no provider has the number, the call bills zero credits.
Last updated September 22, 2026
Give the endpoint a LinkedIn profile URL, or a name and a company domain, and it returns a mobile number in E.164 format. `POST /phone_finder` runs the lookup across a provider waterfall and shows you every provider it asked. **[Get 25 free credits — no card](https://app.richapi.ai)**
Phone data is the least complete category in B2B enrichment, and it is the one where vendors are vaguest about where a number came from. When a number turns out to be a switchboard or a five-year-old carrier record, you can see which source produced it. The `execution_log` on the response names the providers that ran, the order, and what each one returned. ```json { "success": true, "result": {}, "provider": "provider", "providers_tried": 2, "execution_log": [ {"provider": "provider", "status": "no_data"}, {"provider": "provider", "status": "success"} ] } ``` Provider names are redacted. The only statuses shown here are `success` and `no_data`. A miss uses the same envelope with `"success": false`, `"result": null`, `"provider": null`, and `"billed": false`. That miss bills zero credits. `execution_log` is the waterfall receipt; it is not listed on the public OpenAPI schema, so treat this as the envelope shape, not a contract you code against. `phone_finder` is a waterfall endpoint. Billing is on 2xx, and a waterfall response carrying `success: false` bills zero credits with `billed: false` in the body. When every provider ran and none had the number, that call is free.
Two input shapes. `linkedin_url` on its own is the preferred one, because a profile URL is an unambiguous identity and the providers key off it directly. The fallback is `first_name` plus `last_name` plus `domain`, which works but resolves less often, since the provider has to match a person to an employer before it can look for a number. Note the field is `domain`, not `company_domain`. The email finder uses the longer name. They are different endpoints with different request schemas, and mixing them up is the most common integration bug on these two. The response is two fields. `phone` comes back in E.164 (`+14155552671`), so it is ready for a dialer, a CRM field, or Twilio without any parsing on your side. `status` tells you what standing the number has, and it is the field to gate an auto-dial behind.
**1. Get a key.** Sign up at [app.richapi.ai](https://app.richapi.ai). 25 free credits, no card. **2. Call it with a LinkedIn URL.** This is the higher-hit-rate path, so use it whenever you have the profile: ```bash curl -X POST 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/example/"}' ``` **3. Fall back to name and domain when you have no profile URL.** ```bash curl -X POST https://api.richapi.ai/api/v1/phone_finder \ -H "x-api-key: $RICHAPI_KEY" \ -H "Content-Type: application/json" \ -d '{ "first_name": "Jane", "last_name": "Okafor", "domain": "acme.com" }' ``` **4. Read the response.** ```json { "phone": "+14155552671", "status": "verified" } ``` **5. Or run it from your agent.** The [hosted MCP server](/integrations/claude) exposes `phone_finder` as a tool in Claude, Cursor, Windsurf and VS Code, no install: ``` Get the mobile for this LinkedIn profile, and if there's no number, find the work email instead. ``` The agent calls `phone_finder`, sees the miss, and falls through to [the email finder](/api/email-finder) on its own. The miss costs nothing, which is what makes that fallback pattern affordable to run on every record.
Phone finding misses more than any other lookup in this catalog. Mobile numbers are not published anywhere, coverage varies enormously by country and seniority, and no provider has anything close to a complete picture. A list that returns emails for most rows will return phones for far fewer. It is also the most expensive call of these three, several times the cost of an email lookup, because the underlying data costs several times as much to buy. Under per-request pricing those two facts combine into the worst deal in enrichment: the highest unit price, applied to the lowest hit rate, charged on every attempt. Zero on a miss inverts that. You pay the full price for the rows that produced a number and nothing for the rows that did not, which means your effective cost per contactable prospect is set by your hit rate rather than by your list size. If the miss rate is what stopped you running a phone enrichment job before, run it here and check the bill afterwards.
| Field | Type | What it is | |---|---|---| | `phone` | string | The mobile number, E.164 format | | `status` | string | The standing of the number | | `execution_log` | array | Every provider tried and what each returned | | `billed` | boolean | Present on a miss, always `false` |
`phone_finder` bills a flat `25 credits` per successful call. A miss bills zero. It is the most expensive single call of these three by a wide margin, and the zero-on-miss rule is doing most of the work in that trade. Credits are prepaid, with no seats and no contract, and the per-credit rate depends on package tier, so take yours from [the pricing page](/pricing).
**Multi-channel sequences that need a real mobile.** A call step only works with a personal number; a switchboard wastes the rep's time and the prospect's patience. Gate the call step on `status` and let the rest of the sequence run on email for everyone else. **Warming up an inbound demo request.** Someone books a meeting and leaves the phone field empty. One lookup on their LinkedIn URL before the call gives the rep a number for the no-show follow-up, which is the single highest-yield use of one enrichment call anywhere in the funnel. **Agent-driven research with a fallback chain.** An agent that tries phone, then email, then moves on is a normal pattern that is usually too expensive to run at volume, because you pay for both attempts on every record. Here the failed leg costs nothing, so the chain costs what the successes cost.
Proxycurl shut down, and the replacement question for phone data is mostly about coverage and billing shape. See [the migration notes](/alternatives/proxycurl).
- [Email finder API](/api/email-finder) — the natural fallback when there is no number - [Email verification API](/api/email-verifier) — check that address before you send - [All endpoints](/api) — the full catalog - [Pricing](/pricing) — credit packages and tier rates - [Cost the chain before you run it](/tools/waterfall-cost-calculator)
**What am I charged for?** Numbers. `phone_finder` is a waterfall endpoint, so a 2xx that found nothing carries `billed: false` and costs zero credits. A 4xx or 5xx also costs zero. **Why did this return nothing for a real person?** Mobile numbers are not public records, so coverage is genuinely partial and varies by country, seniority and industry. The `execution_log` shows you that every provider was asked and what each one said, and the call bills zero. **Which input works better, LinkedIn URL or name and domain?** The LinkedIn URL. It identifies the person exactly. Name plus domain requires the provider to resolve a person-to-employer match first, and that step fails on common names and on anyone who changed jobs recently. **Is the number a mobile or a switchboard?** `status` is the field that tells you, and it is what you should gate an auto-dialer on. Do not dial on the presence of `phone` alone. **Can I call this from Claude or Cursor (MCP)?** Yes. The hosted MCP server exposes `phone_finder` as a tool with a copy-paste config and no install. **Do I need a credit card?** No. 25 free credits on signup, no card.
Pull your first mobile number in two minutes. **[Get 25 free credits](https://app.richapi.ai)**