Company hierarchy
POST https://api.kingminos.com/v1/company/hierarchy
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.
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" }'What comes back
Section titled “What comes back”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.
Paths and price
Section titled “Paths and price”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.
path | What it does | Credit cap | Credits on a delivered answer |
|---|---|---|---|
speed | Public registry data only. | 0 | 0 |
balance (default) | speed plus a corporate-hierarchy lookup on a full match. | 1 | 0–1 |
accuracy | Same billing as balance with a higher-confidence ladder. | 1 | 0–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, optionalonly,ignore,max_provider_credits.schema_version— pin"2"or omit.dry_run— accepted; writers stay skipped.
Explain and cache
Section titled “Explain and cache”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.
Errors
Section titled “Errors”400 with one of:
validation_faileddomain_website_mismatchinvalid_routing(includingcoverageon this capability)invalid_complianceinvalid_explaininvalid_schema/unsupported_schema
401 unauthorized. 403 scope denied. 429 rate or budget limits — the run was not started.