Person title

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

Try it in the console→

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.

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

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.