---
title: "Person phone"
description: "POST /v1/person/phone — email or LinkedIn URL in, one verified dialable number plus the ranked rest, in the format you pick."
canonical: "https://kingminos.com/docs/api/person-phone/"
sourceKind: "source-mdx"
---

import TryItLink from '../../../../components/docs/TryItLink.astro';

`POST https://api.kingminos.com/v1/person/phone`

<TryItLink method="POST" path="/v1/person/phone" />

You need an API-tenant key (`osr_…`) for this endpoint. Send either `email` or `linkedin_url`. `first_name` and `last_name` are optional and only used to match: a profile that belongs to someone else is rejected with `person_mismatch`, and a name is never used to fill anything in.

```bash
curl 'https://api.kingminos.com/v1/person/phone' \
  -H 'Authorization: Bearer <your-key>' \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "anna@example.com",
    "phone_types": ["mobile"],
    "format": "national"
  }'
```

## Options

| Field | Values | Effect |
| --- | --- | --- |
| `phone_types` | `mobile`, `landline`, `other`, `unknown` | Filters the answer. Omit it for any type. If no vendor can return any of the types you ask for, no vendor is called: you're charged 0 credits and the outcome is `noop`. |
| `max_results` | 1–10 (default 3) | Caps `result.phones`. |
| `format` | `e164` (default), `international`, `national`, `digits`, `digits_national` | Sets which format fills `number`. Every phone also includes `e164` and all five formats under `formats`. Changing the format replays the cached answer at 0 credits. |

## What comes back

Each phone, in both `result.best_phone` and `result.phones[]`, looks like this:

```json
{
  "number": "(415) 555-2672",
  "e164": "+14155552672",
  "formats": {
    "e164": "+14155552672",
    "international": "+1 415 555 2672",
    "national": "(415) 555-2672",
    "digits": "14155552672",
    "digits_national": "4155552672"
  },
  "country_code": "US",
  "calling_code": "1",
  "type": "mobile",
  "line_type": "fixed_line_or_mobile",
  "source": "wiza",
  "sources": ["wiza"],
  "confidence": "high",
  "flags": []
}
```

Write `result.best_phone` only when `answer.confidence` meets your acceptance floor for the chosen `routing.path` (`speed` / `coverage`: `low`; `balance`: `medium`+; `accuracy`: `high`; override with `min_confidence`). Below-floor answers return a blank `best_phone` with candidates in evidence. A wrong number is worse than a missing one. See [`GET /v1/recipes/guidance`](https://api.kingminos.com/v1/recipes/guidance).

## Verification

Every number goes through these checks before you see it. None of them calls an extra vendor or costs extra credits:

- **Valid number.** The number is checked against libphonenumber's numbering plan. Invalid or impossible numbers are dropped.
- **Junk.** Repeated digits, straight runs like `1234567890`, and the NANP fictional 555-01xx range are dropped.
- **Line type.** `line_type` comes from the numbering plan. Toll-free, premium-rate, shared-cost and pager numbers aren't anyone's direct dial, so they're dropped. So is the company switchboard. If a vendor labels a number mobile and the plan says it's a fixed line, it gets `line_type_mismatch`.
- **Country.** If the number's country code doesn't match the person's or company's known location, it gets `country_mismatch` and its confidence drops one level. If only the email domain's country disagrees, it gets `email_country_mismatch`, which is informational.
- **Agreement.** When two vendors return the same number, it gets `multi_source` and high confidence.

If every number a vendor returned is dropped, the result is a miss and costs 0 credits.

US and Canadian numbers report `line_type: fixed_line_or_mobile`, because the numbering plan can't tell mobile from landline there. No carrier lookup is made.

## Cost

person.phone is an agent-managed router that answers in under 10 seconds. It asks every vendor that can use your input (email, LinkedIn URL, or first+last name with `domain`) in parallel: ZoomInfo, QuickEnrich and Blitz with your own keys, LeadMagic, AI Ark, Findymail (US contacts) and Wiza. A vendor that isn't back in time is dropped and costs nothing.

Pick a mode with `routing.path`:

- **`speed`**: LeadMagic goes first with a 3-second head start; then the cheapest other vendors race it and the first number back wins. Max 10 credits.
- **`balance`** (default): the best single number, picked by vendor track record, region and line type. It doesn't wait for vendors to agree.
- **`accuracy`**: vendors must agree, and you get exactly one number. A disagreement (`conflicting_numbers`) is a miss — do not stamp.
- **`coverage`**: up to 5 numbers, each with its source, line type, confidence and consensus.

Every number carries `consensus` (`unanimous`, `majority`, `single`, `conflict`) and `do_not_call` when a vendor reports it. Only the vendors behind the numbers you get back bill, capped at **38 credits** (up to **58** in coverage mode); a miss costs **0**. Answers are cached for 30 days and replay at 0 credits. Send `skip_cache` or `X-Router-Cache: bypass` to skip the cached answer.

`result.person` is always null on a miss. Business misses still return HTTP `200`.