Person name

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

Try it in the console→

Send a person: email, linkedin_url, or both (top level or under person). One is required. You get back a cleaned, proper-cased first_name, last_name and full_name for CRM name stamps and personalization.

Salutations, titles, honorifics, suffixes, pronouns, emoji and URLs are stripped from every candidate before it is compared, at no cost. phone and x_handle are accepted but never looked up: a phone-only or X-only request returns unsupported_input at 0 credits.

person.name answers for API tenant keys (osr_…). It does not stamp Salesforce Contacts or Leads.

curl 'https://api.kingminos.com/v1/person/name' \
  -H 'Authorization: Bearer <your-key>' \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "anna@example.com",
    "linkedin_url": "https://www.linkedin.com/in/example",
    "routing": { "path": "accuracy" }
  }'

Paths and price

You pay for the outcome, not the call. A hit bills the path’s price once. A miss, a conflict, an answer below your confidence floor and a timeout cost 0.

routing.path	What it does	Credits on a hit
speed	One LinkedIn- or email-keyed profile read. Never high confidence.	1
balance (default)	Profile sources in turn. Stops at the first usable name.	2
accuracy	The balance ladder, plus the KingMinos judge on an ambiguous split. Two agreeing sources give high confidence. A disagreement is conflict.	3
coverage	The balance ladder, plus a second independent source.	5

Aliases: value, fast and name_only mean speed; auto means balance.

The judge only decides how to split an ambiguous name (for example three words, or two words with no clear surname), on balance and above. It never invents a name. It only classifies words the cleaner already kept.

Vendor isolation: routing.only and routing.ignore limit which vendors a path may use. An unknown provider returns 400 unknown_provider. A routing.max_provider_credits below the path price returns max_credits_reached before anything runs (0 credits).

What comes back

Layer	Fields	Use
Control	es_decision, answer.outcome, answer.confidence	Whether to stamp.
Answer	result.first_name, result.last_name, result.full_name	The values.
Evidence	result.name_source, result.matched_on, result.email_type, result.flags, result.evidence	Humans and logs.
Billing	usage.credits, usage.hops	What ran and what was billed.

result.matched_on says which request identifier the name came from (email, linkedin_url). result.email_type is work, freemail or role. result.person is the matched profile on a hit and null otherwise: a miss is never a free lookup.

Outcomes:

Result	answer.outcome	Credits
A name for the matched person	resolved	path price
Only a guess from the email address (low confidence, email_local_parse)	parsed_only	0
Sources disagree on the name	conflict	0
A shared mailbox (admin@, info@, …) is never a person	role_address	0
Phone-only or X-only request	unsupported_input	0
Nothing found, or someone else’s profile	not_found	0

An email-address guess is a last resort. It only comes back when no source found the person and your floor allows low confidence.

Stamp rule: confidence is the only write signal. Write the name on a billed resolved answer when answer.confidence meets your floor and conflicting_names is not flagged.

Confidence floors: speed and coverage default to low, balance to medium, accuracy to high. Send min_confidence (high, medium or low) to override. Below the floor the name fields come back blank, the candidates stay in result.evidence, and the call costs 0.

Flags

Flag	Meaning
conflicting_names	Sources disagree on the name. Do not stamp.
email_local_parse	The name is a guess from the email address.
first_name_only	No surname was found.
freemail	The email is on a free mail provider.
role_address	The email is a shared mailbox, not a person.
unconfirmed_identity	A profile could not be confirmed as this person.
single_source	One source answered.

Cache

Answers are cached for 30 days. The cache key includes the path, min_confidence and routing.only / ignore. A repeat call replays with usage.cached: true at 0 credits.

To force a fresh run, send one of:

• skip_cache: true;
• X-Router-Cache: bypass;
• Cache-Control: no-cache.

DELETE /v1/subjects/email:<address> or li:<slug> erases cached answers.

Errors

400 validation_failed with one of these reasons:

• email_or_linkedin_required
• invalid_linkedin_url

Also 400 invalid_routing and 400 unknown_provider. A person who asked not to be looked up returns 451 subject_suppressed at 0 credits; do not retry. Business misses stay HTTP 200.