Skip to content

Company hierarchy

POST https://api.kingminos.com/v1/company/hierarchy

Try it in the console

One decision: who owns this company, and who sits under it. Send a company subject: domain, website, email, or name. Optional country scopes registry reads.

Terminal window
curl 'https://api.kingminos.com/v1/company/hierarchy' \
-H 'Authorization: Bearer <your-key>' \
-H 'Content-Type: application/json' \
-d '{
"domain": "lidl.com",
"name": "Lidl US",
"external_ref": "account-demo-1"
}'

The envelope is schema version 2. Automations branch on these layers:

Layer Fields Use
Control answer.outcome, es_decision, answer.confidence Whether to trust the family.
Parents result.immediate_parent_*, result.ultimate_parent_* Roll-up targets.
Tree result.subsidiaries, result.hierarchy_depth, result.truncated Subsidiary list (capped).
Identifiers result.zoominfo_company_id, result.wikidata_id, result.lei, result.identifiers CRM and enrichment keys.
Audit result.sources, trace when X-Router-Explain: full Humans and logs.

answer.outcome on this capability is subsidiary, ultimate_parent, or no_decision. There is no standalone outcome — a clean subject with no parent and no subsidiaries is no_decision.

Result answer.outcome Meaning
The subject has a known parent subsidiary Immediate and/or ultimate parent fields are populated.
The subject is the top of the tree ultimate_parent No parent above the matched unit.
Not enough hierarchy data no_decision Miss, timeout, or empty tree.

result.subsidiaries[] entries carry name, domain, zoominfo_company_id, and wikidata_id when the source supplies them. result.family_tree_size is the raw node count before truncation (null on speed). result.truncated is true when the subsidiary list was capped.

You are only charged when a parent answer is delivered. A miss, timeout, or error bills 0. Business misses stay HTTP 200.

Omit routing.path to use balance. A top-level path / preset is the same as routing.path / routing.preset; nested wins when both are sent.

pathWhat it doesCredit capCredits on a delivered answer
speedPublic registry data only.00
balance (default)speed plus a corporate-hierarchy lookup on a full match.10–1
accuracySame billing as balance with a higher-confidence ladder.10–1

coverage is not supported — 400 invalid_routing.

Aliases: value, fast and auto mean balance.

Default paths run on KingMinos keys. Vendor fields such as result.zoominfo_company_id appear on the answer when the source returns them — connect Vendor keys when you rely on BYOK for stampable company ids.

The body accepts nullable name, domain, website, email, and country, plus:

  • external_ref — client correlation key, echoed on the run.
  • routing — path, optional only, ignore, max_provider_credits.
  • schema_version — pin "2" or omit.
  • dry_run — accepted; writers stay skipped.

Prefer X-Router-Explain: minimal on CRM callouts — it is an alias of the clean envelope. Use full when you need trace.attempts.

Idempotency-Key replays a completed run. Rotating that header is what forces a new decision; explain flags do not.

Not in openapi.es.yaml — Salesforce External Services does not import this capability.

400 with one of:

  • validation_failed
  • domain_website_mismatch
  • invalid_routing (including coverage on this capability)
  • invalid_compliance
  • invalid_explain
  • invalid_schema / unsupported_schema

401 unauthorized. 403 scope denied. 429 rate or budget limits — the run was not started.