---
title: "Person language"
description: "POST /v1/person/language — email or LinkedIn URL in, whether you can engage the person in English, and if not, in what language."
canonical: "https://kingminos.com/docs/api/person-language/"
sourceKind: "source-mdx"
---

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

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

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

Can we engage this person in English — and if not, in what language? Outbound sequences, ad targeting and localized campaigns read the answer.

Send a person: `email`, `linkedin_url`, or both (top level or under `person`). You get back:
- **english:** whether English works (`yes`, `likely`, `unconfirmed` or `unknown`);
- **recommended_language:** the ISO 639-1 code to engage in;
- **local_language:** the strongest non-English language, for localized sequences and ads;
- **languages:** every candidate, ranked, with the evidence behind it.

`first_name` and `last_name` are **match-only**. They only reject a profile that belongs to someone else (`person_mismatch`). A name never infers, scores or steers a language.

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

```bash
curl 'https://api.kingminos.com/v1/person/language' \
  -H 'Authorization: Bearer <your-key>' \
  -H 'Content-Type: application/json' \
  -d '{
    "linkedin_url": "https://www.linkedin.com/in/example",
    "first_name": "Anna",
    "last_name": "Schmidt",
    "routing": { "path": "balance" }
  }'
```

## Paths and price

You pay for what the vendors return. Misses, vendor errors and unconfigured sources cost **0**. Only `routing.path` is read.

| `routing.path` | What it does | Max credits |
| --- | --- | --- |
| `speed` | One profile read, then one quick language judge (0 credits). No fallback. | 1 |
| `balance` (default) | LeadMagic, AI Ark and Findymail in order. Stops once listed languages land. | 3 |
| `accuracy` | Every structured source with no early stop, then the language judge. | 3 |

Typical spend on `balance`: 1 credit for LinkedIn input, 2 for email input. Any other `routing.path` (including `coverage` and legacy aliases such as `auto` and `value`) returns `400 invalid_routing`.

Every path is capped at 10 seconds from the start of the request. A call that was sent to a vendor and then timed out still bills.

**Your own keys:** vendor keys you store in [Vendor keys](/docs/api/credentials/) take precedence and bill the same credits.

## What comes back

| Field | Meaning |
| --- | --- |
| `result.detected` | `false` when no language evidence was found at all. |
| `result.english` | `yes`: English evidence at medium or high. `likely`: only low English evidence. `unconfirmed`: other languages found, no English. `unknown`: nothing detected. It is never "no". |
| `result.recommended_language` | ISO 639-1 code. English whenever `english` is `yes`, otherwise the strongest other language. Medium or high only. |
| `result.local_language` | Strongest non-English language. Medium or high only. |
| `result.languages` | Every candidate, ranked: `code`, `name`, `confidence`, `level`, `evidence[]`. Low guesses appear only here. |
| `result.flags` | See below. |
| `result.person` | The matched profile, or `null`. |

Confidence is a heuristic score, not a calibrated probability. Levels: `high` is 0.75 or more, `medium` is 0.5 or more, `low` is under 0.5.

`answer.summary` reads as the answer, for example `English: yes (high). Local language: German (high).`

**Outcomes:**

| Result | `answer.outcome` / reason | `es_decision` | Credits |
| --- | --- | --- | --- |
| A medium or high recommendation | `hit` / `exact_one` | `hit` | what ran |
| Only low evidence | `no_decision` / `ambiguous` | `ambiguous` | what ran |
| Nothing found | `no_decision` / `zero_hits` | `miss` | 0 |
| Profile belongs to someone else | `no_decision` / `person_mismatch` | `miss` | 0 |
| Every vendor errored or timed out | `no_decision` / `provider_error` | `error` | 0 |
| No vendor could run | `no_decision` / `compliance_blocked`, `status_down`, `max_credits_reached` or `not_configured` | `noop` | 0 |

**Stamp rule:** write `recommended_language` only on a billed `hit` when `answer.confidence` meets your acceptance floor (`balance` paths expect `medium`+) and neither `conflicting_signals` nor `unconfirmed_identity` is flagged. See [`GET /v1/recipes/guidance`](https://api.kingminos.com/v1/recipes/guidance).

## Signals

Strongest first:
1. **Language use:** prose the person wrote on their profile. Headlines and job titles count only for non-English.
2. **Listed languages:** the languages listed on the profile.
3. **LinkedIn locale settings.**
4. **Location country:** location alone never reaches `high`. Minority and regional languages are never candidates.
5. **Support-only:** company languages and the work-email country domain. They add weight to a language that already has evidence and never create one.

Agreement between independent sources adds weight. English prose may make `english` `yes`; it never erases `local_language`. Profile text is used in-process and never returned.

### Flags

| Flag | Meaning |
| --- | --- |
| `weak_signals` | Every candidate is low. |
| `multilingual_country` | The location has several official languages (CH, BE, CA, IN, LU, SG, ZA…). |
| `conflicting_signals` | Two equally strong languages from disjoint evidence. Do not stamp. |
| `unconfirmed_identity` | You sent a name but the profile carries none. Do not stamp. |

## Cache

Answers are cached for 30 days, per path. A repeat call replays with `usage.cached: true` at 0 credits and no vendor call. An answer is not cached when a source errored, timed out or was skipped, when `compliance` is set, or when your own vendor key answered.

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`. Business misses stay HTTP `200`.