{"ok":true,"guide":"/v1/recipes/guidance","summary":"How to read a KingMinos answer. KingMinos strives to return usable, system-of-record-grade data and holds a high bar. Fetch this document once. Per-call responses only point here.","ask_user":"Ask your user once what confidence they will accept for CRM writes. Apply that floor to the list — do not ask per record.","confidence":{"levels":{"low":{"id":"low","means":"Usable, and close to production-grade compared with a raw vendor field. Less independent corroboration than medium or high — sources did not independently agree, or only a weaker aligning signal landed.","accept":"Often fine to write. The user decides. Honor the acceptance level they already set."},"medium":{"id":"medium","means":"A single vendor-returned value. One independent source. The same checks still ran.","accept":"Write when the user accepts medium or lower."},"high":{"id":"high","means":"Independently corroborated by more than one source.","accept":"Write when the user accepts high or any lower floor."}},"ask_user":"Ask your user once what confidence they will accept for CRM writes. Apply that floor to the list — do not ask per record.","how":"Every delivered answer already ran multiple checks: vendor hops, identity and domain alignment, judges where the path uses them, and compliance gates, plus KingMinos verification. Confidence is how much independent corroboration we found. It is not a hedge on quality."},"min_confidence":{"what":"The lowest confidence this call will return as an answer. Each path supplies a default. min_confidence on the request overrides that default.","defaults":{"speed":"low","balance":"medium","accuracy":"high","coverage":"low"},"below_floor":"Answers below the floor come back blank. Candidates stay in evidence. The withheld confidence is still on the answer so you can decide."},"tiers":{"speed":{"id":"speed","label":"Speed","when":"Fastest and cheapest. A miss is acceptable.","optimizes":"Latency and spend. Fewest hops.","tradeoff":"More misses than the other tiers.","pick":"Large lists, or when a miss is acceptable.","aliases":["value","fast","name_only"],"default_floor":"low","relative_cost":"cheapest","deprecated_aliases":["value","fast","name_only"]},"balance":{"id":"balance","label":"Balance","when":"Default. Better recall than speed, still bounded spend.","optimizes":"Recall at a bounded spend. Default when path is omitted.","tradeoff":"Costs at least as much as speed.","pick":"Typical lists. Ask before a bulk run.","aliases":["auto"],"default_floor":"medium","relative_cost":"next","deprecated_aliases":["auto"]},"accuracy":{"id":"accuracy","label":"Accuracy","when":"Prefer a verified answer over a fill.","optimizes":"A verified answer over a fill.","tradeoff":"Costs at least as much as balance. More hops, slower.","pick":"Quality over fill rate. CRM writes the user will trust.","aliases":[],"default_floor":"high","relative_cost":"higher","deprecated_aliases":[]},"coverage":{"id":"coverage","label":"Coverage","when":"Max yield — fill as many rows as possible.","optimizes":"Max yield — fill as many rows as possible.","tradeoff":"Highest spend. Never cheaper than accuracy.","pick":"When the user said max yield. Start here; do not climb.","aliases":[],"default_floor":"low","relative_cost":"highest","deprecated_aliases":[]},"relative_cost":"speed is always cheapest; then balance; then accuracy; coverage costs at least as much as accuracy. Read exact credits on GET /v1/recipes — do not invent a number.","legacy_aliases":{"value":"speed","fast":"speed","name_only":"speed","auto":"balance","status":"deprecated"}},"next_steps":{"below_floor":"Result fields are blank; candidates stay in evidence. Rerun on accuracy or coverage, or lower min_confidence if the user accepts that floor.","low":"Usable, and often fine to write. The user decides. If you have not asked their acceptance level yet, ask once and apply it to the rest of the list — not per record.","not_found":"Do not invent a value. Read next_steps and candidates. Climb one tier or ask the user.","subject_suppressed":"451 subject_suppressed. Do not retry. Remove or suppress this person in your own systems."},"billing":{"hit":"A delivered answer bills the path price. No tier is a free unlimited path.","miss":"A hop or run that delivers nothing bills 0.","below_floor":"A blank below the confidence floor bills 0.","timeout":"A timeout bills 0. Hop telemetry may still record a spend estimate.","subject_suppressed":"451 subject_suppressed bills 0 — no hop runs.","relative_cost":"speed is always cheapest; then balance; then accuracy; coverage costs at least as much as accuracy. Read exact credits on GET /v1/recipes — do not invent a number."},"capabilities":{"company.x_account":{"note":"Applies the path floor today. Confidence is the only write signal. Below-floor withholds blank x_url / x_handle and keep candidates in evidence."},"company.icon":{"note":"No path tiers. One locked stack. routing.path / preset / order are ignored."},"person.phone":{"note":"Hop billing only on a delivered best_phone after the path or min_confidence floor; below-floor withhold and miss bill 0 (like company.x_account). routing.path selects router mode (speed/balance/accuracy/coverage); routing.only / ignore are honored."},"company.hierarchy":{"note":"coverage is 400 invalid_routing. speed is Wikidata immediate claims (0 credits)."},"person.language":{"note":"coverage is 400 invalid_routing. Not in openapi.es.yaml. Headline fields are medium+ only."},"person.verify_employment":{"note":"coverage / value / auto / fast / name_only are 400 invalid_routing. speed is a mailbox-domain check at low confidence."},"person.title":{"note":"A hit bills the path price once (speed / balance / accuracy / coverage). Partials and misses bill 0."},"person.name":{"note":"Applies the path floor today. Confidence is the only write signal (high requires independent confirmation). Below-floor withholds blank name fields and keeps candidates in evidence; only a delivered floor-passing hit bills the path price. Best results: connect your own ZoomInfo credentials (highly recommended; PUT /v1/credentials/zoominfo, see docs/byok-zoominfo.md; accuracy high essentially needs it) and send both email and linkedin_url when you have them, which improves fill. There is no company, domain, or name-hint input. Paths: speed is the fastest and accepts vendor answers at a lower bar with some checks, never high. Balance blends speed with more error fixing and more coverage, default floor medium, never high. Accuracy strives for no wrong answers: high only with independent confirmation, withheld answers bill 0, fill is lower. Coverage fills the most rows from any evidence and flags low confidence. min_confidence decides which names you get. Outbound that needs few wrong names: balance at medium, or accuracy at high. List fill: coverage, or balance at low; write medium and high, send low to review. first_name_confidence and last_name_confidence are optional; when absent use confidence. A first_name_only answer has no surname (use last_name_fallback for a CRM that needs one). A surname can be stale: require high when it must be right. role_address is a shared mailbox, not a person (0 credits). conflict returns no name; do not pick a candidate. In our small evaluations, roughly (wide uncertainty, samples were small, results depend on a connected ZoomInfo key, which is highly recommended): balance at medium fills about 80-90% of rows with roughly 1-8% of delivered answers wrong; accuracy at high fills roughly 30-55% with email only and up to about 75% when a linkedin_url is also sent, with wrong answers rare but not zero; coverage fills the most rows, flags low confidence, and expect noticeably more wrong answers; speed is the lowest bar and never high. Details and limits: docs/person-name.md, section Getting the best results."},"person.b2b_social":{"note":"Email → LinkedIn profile URL. Paths speed / balance / accuracy / coverage (omit = balance). Balance and accuracy still run the second email source after a first-hop timeout or error. Accuracy withholds rather than guesses (URL only when independently confirmed; otherwise blank, 0 credits). Applies the path floor; confidence is the only write signal (high requires independent confirmation; identity-equivalent slugs agree on speed/balance/coverage; a websearch-only hit stays medium). Below-floor withholds blank linkedin_url and keep candidates; only a delivered floor-passing hit bills the path price. Explain=full adds rejected-gate tokens; default omits them."},"email.verify":{"note":"Is this mailbox deliverable? status valid | invalid | catch_all | unknown. Paths speed / balance / accuracy / coverage (omit = balance). Local syntax / DNS checks run first; an address with no mail host is invalid at 0 credits. Only a delivered valid or invalid at or above the path floor bills the path price; catch_all, unknown and below-floor answers bill 0. Flags (role_based, free_mailbox, disposable, relay, security_gateway) never change the status."},"company.domain":{"note":"speed and balance are hygiene — they can bill 0. coverage is a real recall path, not a balance alias."},"company.resolve":{"note":"speed is the one-step name + ZoomInfo id lookup. It does not decide LinkedIn or X — follow next_steps."},"company.b2b_social":{"note":"Confidence is the only write signal; unique first-party LinkedIn placement is high. Name-only name→domain runs on accuracy/coverage."},"company.description":{"note":"Winner-only billing. coverage is a real high-spend fourth path at balance quality, not a catch-all."}},"sections":{"confidence":"What low, medium, and high mean. Confidence is corroboration, not a quality hedge.","low":"Usable, and close to production-grade compared with a raw vendor field. Less independent corroboration than medium or high — sources did not independently agree, or only a weaker aligning signal landed.","medium":"A single vendor-returned value. One independent source. The same checks still ran.","high":"Independently corroborated by more than one source.","min_confidence":"Path default floor, and how min_confidence overrides it.","below_floor":"Result fields are blank; candidates stay in evidence. Rerun on accuracy or coverage, or lower min_confidence if the user accepts that floor.","tiers":"speed, balance, accuracy, coverage — optimize, floor, relative cost.","speed":"Fastest and cheapest. A miss is acceptable.","balance":"Default. Better recall than speed, still bounded spend.","accuracy":"Prefer a verified answer over a fill.","coverage":"Max yield — fill as many rows as possible.","next_steps":"What to do after a blank, low, miss, or 451.","not_found":"Do not invent a value. Read next_steps and candidates. Climb one tier or ask the user.","subject_suppressed":"451 subject_suppressed. Do not retry. Remove or suppress this person in your own systems.","billing":"A delivered answer bills the path price. No tier is a free unlimited path."}}