---
title: "Company domain"
description: "POST /v1/company/domain — domain or email in, a write-safe company domain and ownership-proven aliases out."
canonical: "https://kingminos.com/docs/api/company-domain/"
sourceKind: "source-mdx"
---

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

`POST https://api.kingminos.com/v1/company/domain`

<TryItLink method="POST" path="/v1/company/domain" />

One decision: what the CRM domain field should say, and whether it is safe to write. Send a company subject: `domain`, `website`, or `email`. Optional `name` (alias `company_name`) checks that the name and host are the same company. Name-only input does not discover on `speed`.

```bash
curl 'https://api.kingminos.com/v1/company/domain' \
  -H 'Authorization: Bearer <your-key>' \
  -H 'Content-Type: application/json' \
  -d '{
    "domain": "example.com",
    "name": "Example",
    "external_ref": "account-demo-1"
  }'
```

## What comes back

The envelope is schema version `2`. Automations that write to a CRM should branch on these layers:

| Layer | Fields | Use |
| --- | --- | --- |
| Control | `answer.outcome`, `es_decision`, `answer.confidence` | Whether to stamp. |
| Stamp | `result.company_domain`, `result.account_primary_domain` | The write-safe host. |
| Aliases | `result.additional_domains`, `result.additional_domains_csv` | Ownership-proven extras. Never the input host. |
| Hold | `result.review_domains`, `result.discovered_domain` | Humans. Do not auto-merge. |
| Audit | `trace` when `X-Router-Explain: full` | Debug only. |

`answer.outcome` on this capability is `verified`, `corrected`, `discovered`, `rejected`, `unverified`, or `no_decision`.

| Result | `answer.outcome` | `es_decision` | Write? |
| --- | --- | --- | --- |
| Input host is the company domain | `verified` | `hit` | Yes |
| A better host is proven | `corrected` | `hit` | Write the corrected stamp |
| No usable input host; a unique name→domain hit | `discovered` | `hit` | Yes |
| Input is junk (mailbox, social, directory, unparseable) | `rejected` | `reject` | Do not write the input |
| Clean enough to look at, not safe to stamp | `unverified` | `miss` | Hold |
| Not enough to answer | `no_decision` | `noop` / `miss` | Do not invent a domain |

`result.company_domain` is null unless the outcome is trusted (`verified` / `corrected` / `discovered`). Map HubSpot `domain` from `result.account_primary_domain` when that field is present — it can differ from `company_domain` under `family_policy: collapse_brand`.

**Stamp rule:** write when `answer.outcome` is `verified`, `corrected`, or `discovered`, `result.company_domain` is non-null, and `answer.confidence` meets your floor (`speed` / `coverage`: `low`; `balance`: `medium`; `accuracy`: `high`; `min_confidence` overrides). You are only charged when a domain answer is delivered. A miss, reject, unverified, below-floor withhold, error, or timeout bills 0.

Business misses stay HTTP `200`.

### Additional domains

`additional_domains` is ownership-proven write-safe aliases only. It is never “all domains found.” Brand-tied and live without ownership stays in `review_domains`. Subsidiaries and parents stay in `related_domains`.

Join for HubSpot: `hs_additional_domains` ← `additional_domains.join(";")`. `additional_domains_csv` is the same hosts as a comma-separated string (lowercase, deduped, at most six, truncated at 255 characters on whole-domain boundaries) for Salesforce `Secondary_Domains__c`. Use `""` when `additional_domains_status` is `skipped` or there are no proven extras — never omitted, never null.

The input host is **never** included (nor its www/apex twins). The stamped `company_domain`, `canonical_domain`, `account_primary_domain`, and their www/apex twins are omitted **except** when the input host HTTP-redirects to a different registrable domain that passed identity. Then that redirect target (in practice `company_domain` when it differs from the input) is included with proof `redirect`. Same-site redirects (www, http→https) and identity-mismatch redirects add nothing.

`additional_domain_proofs[]` tags each host (`redirect`, `hreflang`, `canonical`, `og_url`, and others). Proofs are not a write gate. Completeness is `additional_domains_status`: `complete`, `partial`, or `skipped`. Write what was proven; `partial` means the list is not exhaustive.

## 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` | Hygiene. Can correct a moved host. No miss-only discovery. | 0 | 0 |
| `balance` (default) | Speed plus a 0-credit company lookup. | 0 | 0 |
| `accuracy` | Adds miss-only discovery plus an optional enrichment step, billed only when a domain is delivered. | 3 | 0–3 |
| `coverage` | Accuracy plus related-domain recall: highest fill of ownership-proven additional domains; lists are often `partial`. Billed only when a domain is delivered. | 4 | 0–4 |

**Aliases:** `value`, `fast` and `name_only` mean `speed`; `auto` means `balance`. Env/tenant `coverage` is ignored on this capability so a shared `company.resolve` routing blob cannot leak onto this route.

## House key vs vendor keys

The default paths run on KingMinos keys. Connect your own ZoomInfo key for stampable company ids — see [Vendor keys](/docs/api/credentials/). BuiltWith and Company URL Finder are Your Keys (BYOK); without a stored key those hops are skipped or return `400 builtwith_credentials_required` / `400 companyurlfinder_credentials_required`.

## Input

The body accepts nullable `name` (`company_name` alias), `domain`, `website`, `email`, `city`, `state`, `country`, `postal_code`, `phone`, and `linkedin_url` (a LinkedIn company page; person `/in/` URLs are rejected), plus:

- `family_policy` — `collapse_brand` (default) or `separate_regional`.
- `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.
- `skip_cache` — boolean; non-boolean → `400 invalid_cache`.

## 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`.

Short-TTL isolate cache (default 300s). To skip the cache read and re-run (the fresh answer is still written), send `X-Router-Cache: bypass`, `Cache-Control: no-cache` / `no-store`, or body `skip_cache: true`. Reusing an `Idempotency-Key` still returns the stored response even with bypass flags.
