Book a demo

create_org

Create an org

act entity tenant-private since 2026-10-01

Creates an org with a name and a type (internal, demo or customer), optionally in an account, and returns its id. An account owner creates only into an account they own. The org starts with no members. Send an Idempotency-Key header: a retry with the same key and inputs returns the same org and creates nothing.

Contract

shape
entity
authority
act
evidence
none
subscription
false
permission
any one of: staff.provision (the staff role staff_provision held in the Internal org, tradehq_role.staff_role); account.owner (account role owner or higher in at least one account; the call is scoped to those accounts); a deactivated caller is refused first
idempotency
keyed
emits
org.created
MCP tool
create_org
decision_set
approve, reject, edit, request_info
REST
POST https://api.containertradehq.com/v1/cap/create_org

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

Idempotency: keyed by the caller's Idempotency-Key, which is required: the same key and inputs replay the first result, the same key with other inputs is 409 idempotency_key_reused

Inputs

nametyperequiredvalidation
nametextrequired1 to 120 characters
The org's name: the legal entity's, as customers know it.
org_typeone_ofrequiredone of internal, demo, customer
internal (staff dogfood and QA), demo (a sales demo) or customer (a tenant).
account_idaccount_idoptionaltradehq-account-id
The account the org belongs to. Required of an account owner, and one they own.

Response

  • org_id · string · The new org's id.
  • name · string · The org's name.
  • org_type · string · The org's type.
  • created_by · string · Who created it.
  • account_id · stringnull · Its account, or null.
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 new org's id.",
      "x-data-class": "operational"
    },
    "name": {
      "type": "string",
      "description": "The org's name.",
      "x-data-class": "operational"
    },
    "org_type": {
      "type": "string",
      "enum": [
        "internal",
        "demo",
        "customer"
      ],
      "description": "The org's type.",
      "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 created it.",
      "x-data-class": "operational"
    },
    "account_id": {
      "type": [
        "string",
        "null"
      ],
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$",
      "format": "tradehq-account-id",
      "description": "Its account, or null.",
      "x-data-class": "operational"
    }
  },
  "required": [
    "org_id",
    "name",
    "org_type",
    "created_by",
    "account_id"
  ],
  "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
MobileD5
APIF
MCPF*
VoiceD5
PushF
OneBoxN
OutboundN
  • Mobile: degraded: composition
  • MCP: approval required
  • Voice: degraded: composition
  • OneBox: no document originates an org
  • Outbound: crosses to no counterparty

Events

Related

None.