Skip to content

Person email

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

Try it in the console

Send what you have, top level or under person:

  • Name route: first_name + last_name + company_domain (domain is an alias). A full name packed into first_name with last_name blank is split.
  • LinkedIn route: linkedin_url. A LinkedIn company page is 400 invalid_linkedin_url.

Send one route or both. A name without a domain, or a domain without a name and no linkedin_url, is 400 validation_failed (insufficient_input). KingMinos never guesses an address from a naming pattern.

You get back the person’s work email, for outbound sequencing and CRM email fill. Only verified addresses are delivered.

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

Terminal window
curl 'https://api.kingminos.com/v1/person/email' \
  -H 'Authorization: Bearer <your-key>' \
  -H 'Content-Type: application/json' \
  -d '{
    "first_name": "Anna",
    "last_name": "Example",
    "company_domain": "example.com",
    "routing": { "path": "balance" }
  }'

Paths and price

Section titled “Paths and price”

You pay for the outcome, not the call. A delivered email (found) bills the path’s price once. Everything else costs 0: not found, conflict, catch_all, a person or domain mismatch, an answer below your confidence floor, and a timeout.

routing.path What it does Credits on a delivered email
speed One email finder. A second runs when the first found nothing, or alongside a slow first finder so it still answers in time. 2
balance (default) speed, then an independent mailbox check on the found address. 2.5
accuracy Two finders. The independent check runs when only one found the address. 3.5
coverage accuracy, plus the LinkedIn route when you sent linkedin_url. When the finders return two different addresses, each is checked independently, and the one that passes is delivered (see Confidence). 5

Lookups stop 8 s after the request starts on speed and balance, and 10 s after on accuracy and coverage.

Your own vendor key (BYOK): when the finder that decided the answer ran on a key you stored under Vendor keys, a delivered email bills a flat 0.1 credit instead of the path price. You pay your vendor directly.

Legacy aliases (value, auto, fast, name_only) are 400 invalid_routing. Send one of the four paths.

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

Section titled “What comes back”
Layer Fields Use
Control es_decision, answer.outcome, answer.confidence Whether to stamp.
Answer result.email, result.email_status The address. email_status is valid on found.
Evidence result.status, result.route, result.confidence, result.flags, result.candidates, result.person Humans and logs.
Billing usage.credits, usage.hops What ran and what was billed.

result.route is name or linkedin: the identifier that found the address. On found, result.candidates has one row per source with email and agrees, and result.person echoes the identity you sent. On anything else result.email is null, result.person is null, and result.candidates carries no address.

Outcomes:

answer.outcome / reason What happened Credits
found A verified work email at or above your floor. path price
conflict Sources returned two different addresses and nothing settled it. No address. 0
catch_all The domain accepts every address, so the mailbox cannot be proven. Withheld. 0
not_found / sources_disagree The independent mailbox check said the found address is invalid. 0
not_found / person_mismatch Sources only returned someone else. 0
not_found / below_min_confidence Below your confidence floor. The confidence is kept. 0
not_found / zero_hits Nothing found. 0
not_found / compliance_blocked The found address belongs to someone who asked not to be looked up. Withheld. 0
not_found / provider_error A source failed or timed out. Retry later. 0

Stamp rule: write result.email on a billed found answer when answer.confidence meets your floor.

Confidence: two independent sources agreeing on the address give high: two finders returning it, or one finder plus a valid independent mailbox check. One source gives medium. On coverage, two different addresses are each checked by the other finder’s independent mailbox check: when exactly one passes and the other fails, the passing address is delivered at low with the conflict_settled_by_check flag. Otherwise it stays a conflict. The other paths never settle a conflict.

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 address comes back blank, the confidence stays, and the call costs 0.

Identity checks. A wrong person’s email is worse than none, so these are dropped before anything is delivered:

  • a source person whose first or last name conflicts with yours (person_mismatch);
  • an address on a different company’s domain (domain_mismatch);
  • a personal mailbox such as a free consumer address (personal_mailbox). This endpoint returns work emails.

next_steps suggests a retry only when it adds a step, for example coverage after a below-floor answer, or after a miss when you sent both a name + domain and a linkedin_url.

Flags

Section titled “Flags”
Flag Meaning
finders_agree Two finders returned the same address.
verified_by_second_vendor An independent mailbox check confirmed the address.
single_source One source answered.
person_mismatch A source returned someone else, which was dropped.
domain_mismatch A source returned an address on another domain, which was dropped.
personal_mailbox A source returned a personal mailbox, which was dropped.
conflict_settled_by_check coverage only: two different addresses came back, and independent checks passed this one and failed the other. Delivered at low.

Cache

Section titled “Cache”

Delivered emails are cached for 30 days. Misses are not cached. The cache key includes the names, company_domain, the LinkedIn slug, the path, min_confidence and routing.only / ignore. A repeat call replays with usage.cached: true at 0 credits.

To skip the cache read, send one of:

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

DELETE /v1/subjects/email:<address> (the found email) or li:<slug> erases cached answers and the runs behind them.

dry_run: true is offline and instant: no lookups, not cached, 0 credits.

Errors

Section titled “Errors”

400 validation_failed with one of these reasons:

  • insufficient_input
  • invalid_linkedin_url
  • invalid_domain
  • min_confidence

Also 400 invalid_routing, 400 unknown_provider and 400 invalid_compliance. A linkedin_url whose owner asked not to be looked up returns 451 subject_suppressed at 0 credits; do not retry. Business misses stay HTTP 200.