Book a demo

suspend_org

Suspend an org

act entity tenant-private since 2026-10-01

Suspends an org: its users, and its test twin's, are refused on every call until it is live again. Nothing of the org's is deleted. On an org whose deletion is scheduled, the suspension is what cancelling the deletion returns it to. Calling it again changes nothing. It records who suspended the org and, when given, why; staff see both, the org's own account sees who and never why. A test twin, an org the repository declares and a purged org are refused.

Contract

shape
entity
authority
act
evidence
none
subscription
false
permission
any one of: account.owner (account role owner or higher in the account of the org `org_id`); staff.ops (the staff role staff_ops held in the Internal org, tradehq_role.staff_role); a deactivated caller is refused first
idempotency
natural
emits
org.suspended
MCP tool
suspend_org
decision_set
approve, reject, escalate
REST
POST https://api.containertradehq.com/v1/cap/suspend_org

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 org to suspend.
reasontextoptional1 to 500 characters
Why it is suspended, trimmed. Trade HQ staff see it with who suspended the org and when; the org's own account does not.

Response

  • org_id · string · The org.
  • state · string · suspended, or deletion_scheduled when its deletion is counting down.
  • purge_after · stringnull · When a scheduled deletion may be purged; null when none is scheduled.
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.",
      "x-data-class": "operational"
    },
    "state": {
      "type": "string",
      "enum": [
        "active",
        "suspended",
        "deletion_scheduled",
        "purged"
      ],
      "description": "suspended, or deletion_scheduled when its deletion is counting down.",
      "x-data-class": "operational"
    },
    "purge_after": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time",
      "description": "When a scheduled deletion may be purged; null when none is scheduled.",
      "x-data-class": "operational"
    }
  },
  "required": [
    "org_id",
    "state",
    "purge_after"
  ],
  "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 suspension
  • Outbound: crosses to no counterparty

Events

Related

break_glass_access, impersonate_user, request_staff_grant