Book a demo

purge_org

Approve an org's purge

act entity tenant-private since 2026-10-01

Approves purging an org whose 30 day deletion countdown has ended, on one dry run: dry_run_id names the org's current dry run, which must have counted. The purge runs as a backend job once two different staff, or one principal, have approved the same dry run; the job counts again, stops and deletes nothing if any count differs, and otherwise deletes the org's data and its test twin's and keeps a tombstone. Refused while the countdown runs, when no deletion is scheduled, without a finished dry run, for a dry run a newer one superseded, and for one the purge stopped on. The same person approving again changes nothing.

Contract

shape
entity
authority
act
evidence
none
subscription
false
permission
any one of: 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.purge_approved, org.purged
MCP tool
purge_org
decision_set
approve, reject, escalate
REST
POST https://api.containertradehq.com/v1/cap/purge_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 purge.
dry_run_idtextrequired1 to 20 characters
The dry run approved: the org's current one, as get_purge_readiness names it, once it has counted.

Response

  • org_id · string · The org.
  • state · string · deletion_scheduled: the purge is the job's, and a purged org is no target.
  • purge_after · stringnull · When the countdown ended.
  • dry_run_id · string · The dry run approved.
  • approvals · integer · How many staff have approved this dry run.
  • queued · boolean · The approvals are a quorum and the purge job may run.
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": [
        "deletion_scheduled"
      ],
      "description": "deletion_scheduled: the purge is the job's, and a purged org is no target.",
      "x-data-class": "operational"
    },
    "purge_after": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time",
      "description": "When the countdown ended.",
      "x-data-class": "operational"
    },
    "dry_run_id": {
      "type": "string",
      "description": "The dry run approved.",
      "x-data-class": "operational"
    },
    "approvals": {
      "type": "integer",
      "description": "How many staff have approved this dry run.",
      "x-data-class": "operational"
    },
    "queued": {
      "type": "boolean",
      "description": "The approvals are a quorum and the purge job may run.",
      "x-data-class": "operational"
    }
  },
  "required": [
    "org_id",
    "state",
    "purge_after",
    "dry_run_id",
    "approvals",
    "queued"
  ],
  "additionalProperties": false
}

Refusals

  • countdown_running · 422 · the 30 day deletion countdown has not ended
  • org_not_scheduled · 422 · the org has no deletion scheduled
  • purge_dry_run_required · 422 · no finished dry run by that id for the org's current deletion; run one and approve it once it has counted
  • purge_dry_run_superseded · 409 · a newer dry run replaced the one named; its approvals no longer count, so approve the current one
  • purge_counts_changed · 409 · the purge stopped on the dry run named because the counts changed, and deleted nothing; run a new dry run and approve again
  • org_has_no_lifecycle · 422 · the org has no lifecycle row: a ported org nothing has typed yet
  • org_has_no_type · 422 · the org has a lifecycle row and no type row; a person repairs it
  • org_is_twin · 422 · a test twin follows its live org
  • org_declared · 422 · the org is declared in db/tradehq/orgs.json and leaves by a reviewed change
  • org_purged · 422 · the org is purged; only its tombstone is left

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

Surfaces

DesktopF
MobileD6
APIF
MCPF*
VoiceD6
PushF
OneBoxN
OutboundN
  • Mobile: degraded: authority
  • MCP: approval required
  • Voice: degraded: authority
  • OneBox: no document originates a purge
  • Outbound: crosses to no counterparty

Events

Related

None.