Skip to content

Person phone

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

Try it in the console

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.

Terminal window
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

Section titled “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

Section titled “What comes back”

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

{
  "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.

Verification

Section titled “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

Section titled “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.