---
title: "Person name"
description: "POST /v1/person/name — email or LinkedIn URL in, the person's proper-cased first, last and full name out."
canonical: "https://kingminos.com/docs/api/person-name/"
sourceKind: "source-mdx"
---

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

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

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

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.

```bash
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`.