Skip to content

Company X account

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

Try it in the console

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}.

Terminal window
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"
}'

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).

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.

pathCredit capCredits on a delivered answer
speed11
balance (default)21.3
accuracy31.6
coverage41.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.

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.

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.

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.