---
title: "Person title"
description: "POST /v1/person/title — email or LinkedIn URL in, the person's current job title plus seniority and function out."
canonical: "https://kingminos.com/docs/api/person-title/"
sourceKind: "source-mdx"
---

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

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

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

Send a person: `email`, `linkedin_url`, or both (top level or under `person`). You get back the cleaned current job title, plus the persona behind it:
- **seniority:** how senior the role is;
- **function:** the department the role belongs to.

Use them for persona routing, sequence selection and CRM title stamps.

Three inputs are **match-only**. They only reject a wrong answer and never infer anything:
- `first_name` / `last_name` reject a profile that belongs to someone else (`person_mismatch`).
- `company_domain` rejects a title held at a different employer (`employer_mismatch`).

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

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

## Pick the fields you need

`fields` is any of `title`, `seniority` and `function`. Omit it to get all three.
- **The request drives the ladder:** KingMinos keeps trying sources until every requested field is answered.
- **Only requested fields come back:** a persona-routing call with `["seniority", "function"]` returns no title.

Today every source returns a title, and seniority and function are derived from it. `result.field_sources` shows how each field was produced:

| `method` | Meaning |
| --- | --- |
| `vendor` | The vendor's own title. |
| `derived` | Keyword rules applied to that title. |
| `jev` | The KingMinos judge, on `balance` and above. |

**Seniority values:** `founder`, `c_suite`, `partner`, `vp`, `head`, `director`, `manager`, `senior`, `ic`, `entry`, `intern`.

**Function values:** `sales`, `marketing`, `revenue_operations`, `customer_success`, `engineering`, `product`, `design`, `data`, `it`, `security`, `finance`, `people`, `legal`, `operations`, `executive`, `other`.

## Paths and price

You pay for the outcome, not the call. A hit bills the path's price **once**. A miss, a partial answer and a timeout cost **0**.

| `routing.path` | What it does | Credits on a hit |
| --- | --- | --- |
| `speed` | One LinkedIn or email profile read with keyword classification. Never `high` confidence. | 1 |
| `balance` (default) | ZoomInfo (only with your own key), then LeadMagic, AI Ark and Findymail. Stops at the first usable title. | 2 |
| `accuracy` | Two independent sources plus one judge call, with a 10 s cap. Agreement gives `high` confidence. A disagreement keeps the newer role and flags `conflicting_titles`. | 3 |
| `coverage` | Accuracy, plus AI Ark people search and Findymail whenever a second source is still wanted. | 5 |

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

**Vendor isolation:** `routing.only` and `routing.ignore` limit which vendors a path may use. An unknown provider returns `400 unknown_provider`.

**Your own keys:** vendor keys you store in [Vendor keys](/docs/api/credentials/) are used automatically and bill the same price. ZoomInfo is never called on the house key.

## What comes back

| Layer | Fields | Use |
| --- | --- | --- |
| Control | `es_decision`, `answer.confidence` | Whether to stamp each field. |
| Answer | `result.title`, `result.seniority`, `result.function`, `result.field_sources` | The values. |
| Evidence | `result.sources` (accuracy / coverage), `result.flags`, `answer.confidence` | Humans and logs. |
| Billing | `usage.credits`, `usage.hops` | What ran and what was billed. |

**Outcomes:**

| Result | `answer.outcome` / reason | `es_decision` | Credits |
| --- | --- | --- | --- |
| Every requested field answered | `hit` / `exact_one` | `hit` | path price |
| Some fields answered, not all | `no_decision` / `fields_incomplete` | `ambiguous` | 0 |
| Only a headline, or a title at another employer | `no_decision` / `ambiguous` | `ambiguous` | 0 |
| Nothing found, or someone else's profile | `no_decision` / `zero_hits`, `person_mismatch` | `miss` | 0 |

On a partial answer, `result.answered_fields` names what was found, but the values are withheld because the call was not billed. `result.person` is `null` on every non-hit.

**Stamp rule:** write a field only on a billed `hit` when `answer.confidence` meets your acceptance floor, the field was requested, and none of `conflicting_titles`, `unconfirmed_identity`, or `employer_mismatch` is flagged. Path defaults and `min_confidence` match other person capabilities — see [`GET /v1/recipes/guidance`](https://api.kingminos.com/v1/recipes/guidance).

### Flags

| Flag | Meaning |
| --- | --- |
| `conflicting_titles` | Sources disagree and the judge did not confirm the same role. Do not stamp. |
| `employer_mismatch` | The title belongs to a company other than `company_domain`. Never a hit. |
| `headline_derived` | Only a profile headline was found. Never a hit. |
| `stale_title` | The vendor record is more than a year old. Confidence is at most `medium`. |
| `unconfirmed_identity` | You sent a name but the profile carries none. Do not stamp. |
| `single_source` | One source answered. |
| `unclassified` | A requested seniority or function stayed unknown. |

## Cache

Answers are cached for 30 days. The cache key includes the path, `fields`, `company_domain` 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`
- `invalid_domain`
- `invalid_title_field`

Also `400 invalid_routing` and `400 unknown_provider`. Business misses stay HTTP `200`.