POST /phone_finder • Credits: 25 credits per successful call. A call that finds no phone number costs 0 credits.

Phone Finder returns a mobile phone number for one person. Send a LinkedIn profile URL, or send a first name, a last name and a company domain. A call that finds a mobile phone number costs 25 credits, that is $0.50 at $0.02 per credit. A call that finds no mobile phone number costs 0 credits.

What does Phone Finder do?

Sales teams hold LinkedIn profiles and company records without a direct mobile number. Phone Finder closes that gap. Phone Finder is a waterfall endpoint. RichAPI calls mobile phone data providers one after another in priority order. The waterfall stops at the first provider that returns a mobile phone number. The whole call has a total time budget of 25 seconds. RichAPI charges one flat fee for the whole call and never bills the individual provider calls inside the waterfall.

Which endpoint does Phone Finder use?

Method: POST
URL: https://api.richapi.ai/api/v1/phone_finder
Authentication: x-api-key header
Response: synchronous JSON
Cost: 25 credits on a hit. 0 credits on a miss.

How to send a Phone Finder request

Create an API key in the RichAPI dashboard.
Set the x-api-key header to your API key.
Set the Content-Type header to application/json.
Put a linkedin_url in the request body.
If you have no LinkedIn URL, put first_name, last_name and domain in the request body instead.
Send the request to https://api.richapi.ai/api/v1/phone_finder.
Read the success field in the response.
If success is true, read the mobile phone number in result.phone.

cURL

curl -X POST https://api.richapi.ai/api/v1/phone_finder   
  -H "x-api-key: YOUR_API_KEY"   
  -H "Content-Type: application/json"   
  -d '{
    "linkedin_url": "https://www.linkedin.com/in/satyanadella",
    "first_name": "Satya",
    "last_name": "Nadella",
    "domain": "microsoft.com"
  }'

Python

import requests

response = requests.post(
    "https://api.richapi.ai/api/v1/phone_finder",
    headers={"x-api-key": "YOUR_API_KEY"},
    json={
        "linkedin_url": "https://www.linkedin.com/in/satyanadella",
        "first_name": "Satya",
        "last_name": "Nadella",
        "domain": "microsoft.com",
    },
    timeout=60,
)
response.raise_for_status()
print(response.json())

Node.js

const response = await fetch("https://api.richapi.ai/api/v1/phone_finder", {
  method: "POST",
  headers: {
    "x-api-key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    linkedin_url: "https://www.linkedin.com/in/satyanadella",
    first_name: "Satya",
    last_name: "Nadella",
    domain: "microsoft.com",
  }),
});

const data = await response.json();
console.log(data);

Request parameters

Parameter	Type	Required	Default	Description
`linkedin_url`	string	No	`""`	LinkedIn profile URL. This is the preferred input.
`first_name`	string	No	`""`	First name. Part of the name and company input shape.
`last_name`	string	No	`""`	Last name. Part of the name and company input shape.
`domain`	string	No	`""`	Company domain, for example `microsoft.com`. Part of the name and company input shape.

Every Phone Finder parameter is optional on its own. The request body must still match one of the two accepted input shapes below. If the request body matches neither shape, Phone Finder returns 400 and charges 0 credits.

Input shape	Fields to send
LinkedIn URL	`linkedin_url`
Name and company	`first_name`, `last_name`, `domain`

Phone Finder normalizes the request body before it calls a provider. It trims the domain value and converts it to lower case. It strips a leading https:// from the domain value. It joins first_name and last_name into a full name for the providers that need one.

What does Phone Finder return?

{
  "success": true,
  "result": {
    "phone": "+14155552671",
    "phone_status": "verified"
  },
  "provider": "source_1",
  "providers_tried": 1,
  "execution_log": [
    {"provider": "source_1", "status": "success", "latency_ms": 523}
  ]
}

Phone Finder returns HTTP 200 for a hit and for a miss. On a miss, success is false, result is null and the response holds "billed": false.

Response fields

Field	Type	Description
`success`	boolean	`true` for a call where a provider returned a mobile phone number. `false` on a miss.
`result`	object or null	The phone data. `null` on a miss.
`result.phone`	string	The mobile phone number. The format is E.164 for a provider that supplies E.164.
`result.phone_status`	string	The verification status that the source reported for the number. Not every source reports one.
`provider`	string or null	A label for the source that returned the number, for example `source_1`. The labels number the sources in the order this response tried them, so they hold within one response only. `null` on a miss.
`providers_tried`	integer	The number of providers that the waterfall attempted.
`execution_log`	array of objects	One entry per attempted provider. Each entry holds `provider`, `status` and `latency_ms`.
`billed`	boolean	Present and `false` only on a miss. A miss costs 0 credits.
`error`	string	A readable explanation. RichAPI adds this field only for a total provider outage.

How much does Phone Finder cost?

Phone Finder costs 25 credits for each call that returns a mobile phone number. At $0.02 per credit, the rate on the 1,000 and 5,000 credit packs, that is $0.50 per successful call. Larger packs cost less per credit. Phone Finder has the highest per-call price in the RichAPI catalog. A call that returns no mobile phone number costs 0 credits.

Calls	Credits	Cost
1	25	$0.50
10	250	$5.00
100	2,500	$50.00
1,000	25,000	$500.00

The table above shows the maximum cost. It assumes that every call finds a mobile phone number. Calls that find nothing reduce the total, because RichAPI charges 0 credits for them.

How to run a bulk Phone Finder job safely

CAUTION: Check your credit balance before you start a bulk loop over Phone Finder. 1,000 successful calls cost 25,000 credits, that is $500.00 at $0.02 per credit. Phone Finder has the highest per-call price in the RichAPI catalog.

Count the records in your list.
Multiply that count by 25 to get the maximum credit cost.
Open the dashboard and compare that number against your credit balance.
Send Phone Finder requests for 10 records first.
Read the success field for each of the 10 responses.
If the results match your expectation, run the rest of the list.
If a call returns success: false, do not send the same request body again.

Errors

Status	Meaning	What to do
`200`	The call succeeded. The response can still be a miss.	Read the `success` field before you read `result.phone`.
`400`	The request body is empty, is not valid JSON, or matches no accepted input shape.	Send `linkedin_url`, or send `first_name`, `last_name` and `domain`.
`401`	The API key is missing, wrong or revoked.	Send a valid key in the `x-api-key` header.
`402`	`Insufficient credits`: the organization has fewer than the 25 credits that RichAPI holds at the start of each call. Or `Monthly spend limit reached`: the team hit its monthly spend limit.	Buy credits in the RichAPI dashboard, or ask the organization owner to raise the spend limit, then send the request again.
`403`	`Endpoint not available on your plan`: this API key has no access to this endpoint.	Call `GET /api/v1/my-endpoints` to list the endpoints this key can use. Contact support for access.
`429`	Rate limit exceeded (too many requests per second).	Wait for the `Retry-After` seconds, then retry the request.
`500`	The API failed.	Send the request again. If the failure repeats, contact support.

A 400, a 401, a 402, a 403, a 429 and a 500 response all cost 0 credits.

Frequently asked questions

Does a Phone Finder call that finds no phone number cost credits?

No. A Phone Finder call that finds no mobile phone number costs 0 credits. RichAPI bills the 25 credits only for a call where a provider returns a mobile phone number. The response marks a miss with "billed": false.

Which inputs does Phone Finder accept?

Phone Finder accepts two input shapes. The first shape is a linkedin_url on its own. The second shape is first_name, last_name and domain together.

What format is the phone number that Phone Finder returns?

Phone Finder returns the mobile phone number in the result.phone field. The format is E.164 for a provider that supplies E.164, for example +14155552671.

What does Phone Finder return during a total provider outage?

Phone Finder returns HTTP 200 with success: false and "billed": false. The response also holds an error field that explains that every provider was temporarily unavailable, and RichAPI refunds the quota slot. Send the request again after a short wait.

Can I send the same Phone Finder request again after a miss?

Do not send the same request body again after a miss. A miss means that every provider in the waterfall reported no mobile phone number for that person. A repeat request with the same inputs returns the same miss.

How much do 1,000 Phone Finder calls cost?

1,000 successful Phone Finder calls cost 25,000 credits. At $0.02 per credit that is $500.00. Calls that find no mobile phone number cost 0 credits, so a real list costs less than $500.00.

How long does one Phone Finder call take?

Phone Finder has a total time budget of 25 seconds for one call. Each provider inside the waterfall has its own timeout of 10 seconds. Set a client timeout of 60 seconds, as the code samples above do.

Phone Finder API