Wrong Number? Ask the API for a Different One
Every sales team has the same column in its CRM: a mobile number nobody trusts.
It came from an import three years ago, or a tool you no longer pay for, or a rep who typed it in from a signature. The dialer says "wrong number" or it rings out for the fifth time. You don't want to look the person up again and get the same digits back. You want to know one thing: is there a better number than this one?
That's now a question you can ask the MillionPhones API directly.
What we shipped
The phone lookup takes one new optional parameter, existing_phone. Send it the number you already hold, and the lookup changes its goal: instead of returning the first number it finds, it looks for one that is different from yours.
curl "https://millionphones.com/v1/phone?social_url=https://www.linkedin.com/in/janedoe&existing_phone=%2B14255551234" -H "x-api-key: YOUR_KEY"
Three things can come back, and the response says which in existing_phone_status.
A different number. This is the one you were hoping for.
{
"phone_numbers": ["+14255559999"],
"tier": "verified",
"existing_phone_status": "alternative",
"confirmations": 0
}
Your number holds up. We saw the number you sent and found nothing that disagrees with it.
{
"phone_numbers": [],
"existing_phone_status": "confirmed",
"confirmations": 3
}
Nothing either way. We have no number for this person, yours or any other.
{
"phone_numbers": [],
"existing_phone_status": "not_found",
"confirmations": 0
}
You pay only for a different number
| Status | What it means | Credits |
|---|---|---|
alternative |
A different number was found and returned | 10 — a normal lookup |
confirmed |
Your number was seen; nothing different turned up | 0 |
not_found |
No number found at all | 0 |
We never sell you the number you already have. phone_numbers will not contain the number you sent, in any formatting, so there is no way to be charged for getting your own data back.
That makes it safe to run across an entire CRM. Send every contact along with the number on file. The ones that come back confirmed or not_found cost nothing. You pay for exactly the rows where we had something new to tell you.
A confirmation is not the end of the search
An ordinary lookup stops as soon as it has a number. That's the right behavior when you have nothing — and the wrong one when you already hold a number you doubt, because the first answer may simply be the same digits again.
So when you send existing_phone, the lookup keeps going. An answer that only repeats your number is counted and set aside, and the search continues until a different number appears or there is nowhere left to look.
That count is the confirmations field, and it is worth reading alongside the status:
confirmedwith a high count — your number was seen several times and nothing contradicted it. That is good evidence the number is right, and the problem is probably that the person doesn't pick up.confirmedwith a count of 1 — we know the number, but only just. Treat it as unproven.alternativewith a count of 0 — we never saw your number at all, and we have a different one. Strong signal to switch.alternativeafter several confirmations — we found a different number, but yours was well supported too. Keep both and try the new one before you overwrite anything.
We give you the count rather than a verdict because you know things we don't — what the dialer reported, when the number was last answered, where it came from.
The details
- Any formatting works.
+1 (425) 555-1234,14255551234and+14255551234are the same number to us. We compare digits. - At least 7 digits. Anything shorter is rejected with a 400 before any lookup runs.
tieronly appears with numbers. When a different number comes back it is labeled Verified or Community, as always.- It works from your AI agent, too. The MillionPhones connector for Claude and other MCP clients accepts the same
existing_phoneon a phone lookup, so an agent cleaning a contact list can ask "is there a better number than this?" in one step. Here's how to connect it.
Who this is for
- RevOps teams with an old database. Run the mobile column through once. Pay for the replacements, get the confirmations for free.
- Teams with dialer dispositions. Every "wrong number" outcome is a ready-made request: the profile, plus the number that just failed.
- Anyone switching data vendors. You don't have to choose between trusting the old numbers and re-buying all of them. Ask only for what's different.
- Agent builders. A workflow that verifies before it dials can now do something useful with the answer.
What hasn't changed
Leave the parameter out and the phone lookup behaves exactly as before. Credits work the same way they always have: you pay for results, never for attempts, and credits never expire.
The only new thing is the question you're allowed to ask. Not "what's this person's number?" but "do you have a better one than mine?"