Book a demo

create_account

Create an account

act entity tenant-private since 2026-10-01

Creates an account: the commercial relationship a customer's orgs belong to. It holds no business data. Optionally names its first owner, who may then create orgs and portfolios in it. Send an Idempotency-Key header: a retry with the same key and inputs returns the same account 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); a deactivated caller is refused first
idempotency
keyed
emits
account.created
MCP tool
create_account
decision_set
approve, reject, edit, request_info
REST
POST https://api.containertradehq.com/v1/cap/create_account

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 200 characters
The account's name: the commercial relationship's, as staff know it.
owner_user_iduser_idoptionaltradehq-user-id; 1 to 20 characters
The account's first owner: an existing user who is not deactivated.

Response

  • account_id · string · The new account's id.
  • name · string · The account's name.
  • owner_user_id · stringnull · Its first owner, or null.
  • created_by · string · Who created it.
Full JSON Schema 
{
  "type": "object",
  "properties": {
    "account_id": {
      "type": "string",
      "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": "The new account's id.",
      "x-data-class": "operational"
    },
    "name": {
      "type": "string",
      "description": "The account's name.",
      "x-data-class": "operational"
    },
    "owner_user_id": {
      "type": [
        "string",
        "null"
      ],
      "minLength": 1,
      "maxLength": 20,
      "pattern": "^[A-Za-z0-9_-]{1,20}$",
      "format": "tradehq-user-id",
      "description": "Its first owner, or null.",
      "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"
    }
  },
  "required": [
    "account_id",
    "name",
    "owner_user_id",
    "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
MobileD5
APIF
MCPF*
VoiceD5
PushF
OneBoxN
OutboundN
  • Mobile: degraded: composition
  • MCP: approval required
  • Voice: degraded: composition
  • OneBox: no document originates an account
  • Outbound: crosses to no counterparty

Events

Related

None.