---
title: "Company X account"
description: "POST /v1/company/x-account — domain or name in, the company's X account URL out (or null)."
canonical: "https://kingminos.com/docs/api/company-x-account/"
sourceKind: "source-mdx"
---

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

`POST https://api.kingminos.com/v1/company/x-account`

<TryItLink method="POST" path="/v1/company/x-account" />

One decision: the company's own X account URL, or `null`. Send a company subject: `domain`, `website`, `email`, or `name`. When all four are blank, the API returns `400 missing_subject`. Name-only is allowed — it is not `name_only_unsupported`. On `speed` and `balance`, name-only misses rather than guesses when no domain-like subject is present; `accuracy` and `coverage` can resolve name→domain.

Optional `x_url` is an agree-check hint only — it must already normalize to `https://x.com/{handle}`.

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

## What comes back

The envelope is schema version `2`. There is no `safe_to_write` field — `answer.confidence` is the only write signal.

| Layer | Fields | Use |
| --- | --- | --- |
| Control | `answer.outcome`, `es_decision`, `answer.confidence` | Whether to stamp. |
| Stamp | `result.x_url`, `result.x_handle` | `https://x.com/{handle}` (lowercase, no `@`), or `null`. Never `twitter.com`. |
| Quality | `result.verification` | `status` (`confirmed` \| `unverified` \| `rejected`), `reason`, normalized `url`. |
| Evidence | `result.evidence` | Withheld candidates when below the confidence floor. |
| Follow-up | `next_steps` | Includes `verify_x_account` on a below-floor withhold. |
| Billing | `usage.credits`, `usage.hops` | What ran and what was billed. |

`answer.outcome` is `hit` or `no_decision`. Business misses stay HTTP `200`.

**Stamp rule:** write `result.x_url` when `answer.confidence` meets your floor. Path defaults: `speed` and `coverage` accept `low` and up; `balance` accepts `medium` and up; `accuracy` accepts `high` only. Send `min_confidence` (`high` | `medium` | `low`) to override. Below the floor the field is blank (`es_decision=miss`), confidence is withheld, candidates stay in `result.evidence`, and `next_steps.verify_x_account` points at a follow-up.

`high` confidence includes a unique first-party handle at placement 1–4 (structured data, follow widget, site chrome, or `twitter:site` on the company's own site).

## Paths and price

Omit `routing.path` to use `balance`. You pay for the outcome, not the call. Only a delivered floor-passing hit bills the path price. Below-floor withholds and true misses bill **0**. When the deciding hop ran on a key you stored, a delivered hit bills a flat **0.1** instead of the path price.

| `path` | Credit cap | Credits on a delivered answer |
| --- | --- | --- |
| `speed` | 1 | 1 |
| `balance` (default) | 2 | 1.3 |
| `accuracy` | 3 | 1.6 |
| `coverage` | 4 | 1.7 |

**Aliases:** `value`, `fast` and `name_only` mean `speed`; `auto` means `balance`.

Hard server budget: 10 s.

**Vendor isolation:** `routing.only` and `routing.ignore` limit which providers a path may use. An unknown provider returns `400 unknown_provider`. Forced hops without a stored BYOK key return `400` with the matching `*_credentials_required` code — see [Vendor keys](/docs/api/credentials/).

## Input

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

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

## Explain and cache

Prefer `X-Router-Explain: minimal` on CRM callouts. Use `full` when you need `trace.attempts`.

`Idempotency-Key` replays a completed run. Rotating that header forces a new decision.

Not in `openapi.es.yaml`.

## Errors

`400` with one of:

- `validation_failed`
- `domain_website_mismatch`
- `missing_subject`
- `invalid_routing`
- `invalid_compliance` / `invalid_explain` / `invalid_schema` / `unsupported_schema`
- `zi_credentials_required` when ZoomInfo was required and no key is stored

`401` unauthorized. `403` scope denied. `409` idempotency conflict states. `429` rate or budget limits. `503` store unavailable — retryable with the same `Idempotency-Key`.
