Book a demo

verify_domain

Verify an email domain

act entity tenant-private since 2026-10-01

Claims an email domain for the org and verifies it. The first call answers status pending with a DNS TXT record to publish (record_name, record_value); call again once it is published and the domain is verified. Other orgs may claim the same domain while it is pending; the first to publish its record verifies it, and a verified domain is that org's alone. Its join_policy starts as invite_only: set_domain_join_policy decides whether a person signing up at it may ask to join.

Contract

shape
entity
authority
act
evidence
none
subscription
false
permission
any one of: org.admin (carried by the caller's role template in the org `org_id`); a deactivated caller is refused first
idempotency
natural
emits
domain.verified
MCP tool
verify_domain
decision_set
approve, reject
REST
POST https://api.containertradehq.com/v1/cap/verify_domain

Through MCP this call returns an approval request first; see Approvals.

Idempotency: keyed by the contract's own inputs: the same inputs replay the first call's result

Inputs

nametyperequiredvalidation
org_idorg_idrequiredtradehq-org-id; 1 to 20 characters
The live org claiming the domain.
domaintextrequired3 to 253 characters
The email domain, such as example.com.

Response

  • org_id · string · The org claiming it.
  • domain · string · The domain, lower case.
  • status · string · pending until the TXT record is found, then verified.
  • record_name · string · Where to publish the TXT record.
  • record_value · string · What the TXT record carries.
  • verified_at · stringnull · When it was verified.
  • verified_by · stringnull · Who verified it.
  • join_policy · string · invite_only, or request: a person signing up at the domain is put to the org's admins as a join request.
  • created_by · string · Who claimed it.
Full JSON Schema 
{
  "type": "object",
  "properties": {
    "org_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 20,
      "pattern": "^[A-Za-z0-9_-]{1,20}$",
      "format": "tradehq-org-id",
      "description": "The org claiming it.",
      "x-data-class": "operational"
    },
    "domain": {
      "type": "string",
      "description": "The domain, lower case.",
      "x-data-class": "operational"
    },
    "status": {
      "type": "string",
      "enum": [
        "pending",
        "verified"
      ],
      "description": "pending until the TXT record is found, then verified.",
      "x-data-class": "operational"
    },
    "record_name": {
      "type": "string",
      "description": "Where to publish the TXT record.",
      "x-data-class": "operational"
    },
    "record_value": {
      "type": "string",
      "description": "What the TXT record carries.",
      "x-data-class": "operational"
    },
    "verified_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time",
      "description": "When it was verified.",
      "x-data-class": "operational"
    },
    "verified_by": {
      "type": [
        "string",
        "null"
      ],
      "minLength": 1,
      "maxLength": 20,
      "pattern": "^[A-Za-z0-9_-]{1,20}$",
      "format": "tradehq-user-id",
      "description": "Who verified it.",
      "x-data-class": "operational"
    },
    "join_policy": {
      "type": "string",
      "enum": [
        "invite_only",
        "request"
      ],
      "description": "invite_only, or request: a person signing up at the domain is put to the org's admins as a join request.",
      "x-data-class": "operational"
    },
    "created_by": {
      "type": "string",
      "minLength": 1,
      "maxLength": 20,
      "pattern": "^[A-Za-z0-9_-]{1,20}$",
      "format": "tradehq-user-id",
      "description": "Who claimed it.",
      "x-data-class": "operational"
    }
  },
  "required": [
    "org_id",
    "domain",
    "status",
    "record_name",
    "record_value",
    "verified_at",
    "verified_by",
    "join_policy",
    "created_by"
  ],
  "additionalProperties": false
}

Refusals

not yet declared

The platform refusals apply to every call: version, authentication, authority, validation and rate limits, each in the same envelope.

Surfaces

DesktopF
MobileF
APIF
MCPF*
VoiceD2
PushF
OneBoxN
OutboundN
  • MCP: approval required
  • Voice: degraded: confirmation
  • OneBox: no document originates a domain claim
  • Outbound: crosses to no counterparty

Events

Related

create_sso_connection, remove_domain, set_domain_join_policy