Book a demo

provision_account

Provision an account

act entity tenant-private since 2026-10-01

Creates an account, its first org, the org's Clerk Organization, the first admin's invite, the plan's entitlements and a welcome mail, and reports each step. Idempotent on account_name plus admin_email, ignoring case and extra whitespace: calling again with the same inputs creates nothing new and resumes any step that did not finish. The same name and email with different other inputs is refused. Staff only. The admin invite and the entitlements are reported as stubbed until invite_user (TRA-319) and entitlements (TRA-238) exist.

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
natural
emits
account.created, account.provisioned, org.created
MCP tool
provision_account
decision_set
approve, reject, edit, request_info
REST
POST https://api.containertradehq.com/v1/cap/provision_account

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
account_nametextrequired1 to 200 characters
The account's name: the commercial relationship, as the customer knows it. Half of the idempotency key.
admin_emailtextrequired3 to 254 characters
The first admin's email address. They sign in with it, by magic link or passkey. The other half of the idempotency key. A string checked by the server; it becomes a typed email input when the shared input types can take one.
admin_nametextoptional1 to 200 characters
The first admin's name, for the welcome mail.
org_nametextoptional1 to 120 characters
The first org's name: the legal entity's. The account's name when absent.
org_typeone_ofoptionalone of internal, demo, customer
The first org's type: internal, demo or customer (the default).
planone_ofoptionalone of base
The plan whose entitlements the account gets: base (the one tier today, and the default).

Response

  • provisioning_id · string · The ledger row: derived from the normalised account name and admin email.
  • account_name · string · The account's name as the first call spelled it.
  • account_id · stringnull · The account, once the account step is done.
  • org_id · stringnull · The first org, once the org step is done.
  • account · string · The account step.
  • org · string · The org step (create_org).
  • clerk_org · string · The Clerk Organization: waiting until the provision-account job has made it.
  • admin_invite · string · The first admin's invite (invite_user).
  • entitlements · string · The plan's entitlements.
  • welcome_mail · string · The welcome mail: held, queued, sent or refused.
  • complete · boolean · Every step is done and the welcome is sent.
  • waiting_on · stringnull · The first step that is not done, and what it waits for; null when complete.
Full JSON Schema 
{
  "type": "object",
  "properties": {
    "provisioning_id": {
      "type": "string",
      "description": "The ledger row: derived from the normalised account name and admin email.",
      "x-data-class": "operational"
    },
    "account_name": {
      "type": "string",
      "description": "The account's name as the first call spelled it.",
      "x-data-class": "operational"
    },
    "account_id": {
      "type": [
        "string",
        "null"
      ],
      "description": "The account, once the account step is done.",
      "x-data-class": "operational"
    },
    "org_id": {
      "type": [
        "string",
        "null"
      ],
      "minLength": 1,
      "maxLength": 20,
      "pattern": "^[A-Za-z0-9_-]{1,20}$",
      "format": "tradehq-org-id",
      "description": "The first org, once the org step is done.",
      "x-data-class": "operational"
    },
    "account": {
      "type": "string",
      "enum": [
        "pending",
        "done",
        "waiting",
        "stubbed",
        "held",
        "queued",
        "sent",
        "refused",
        "failed"
      ],
      "description": "The account step.",
      "x-data-class": "operational"
    },
    "org": {
      "type": "string",
      "enum": [
        "pending",
        "done",
        "waiting",
        "stubbed",
        "held",
        "queued",
        "sent",
        "refused",
        "failed"
      ],
      "description": "The org step (create_org).",
      "x-data-class": "operational"
    },
    "clerk_org": {
      "type": "string",
      "enum": [
        "pending",
        "done",
        "waiting",
        "stubbed",
        "held",
        "queued",
        "sent",
        "refused",
        "failed"
      ],
      "description": "The Clerk Organization: waiting until the provision-account job has made it.",
      "x-data-class": "operational"
    },
    "admin_invite": {
      "type": "string",
      "enum": [
        "pending",
        "done",
        "waiting",
        "stubbed",
        "held",
        "queued",
        "sent",
        "refused",
        "failed"
      ],
      "description": "The first admin's invite (invite_user).",
      "x-data-class": "operational"
    },
    "entitlements": {
      "type": "string",
      "enum": [
        "pending",
        "done",
        "waiting",
        "stubbed",
        "held",
        "queued",
        "sent",
        "refused",
        "failed"
      ],
      "description": "The plan's entitlements.",
      "x-data-class": "operational"
    },
    "welcome_mail": {
      "type": "string",
      "enum": [
        "pending",
        "done",
        "waiting",
        "stubbed",
        "held",
        "queued",
        "sent",
        "refused",
        "failed"
      ],
      "description": "The welcome mail: held, queued, sent or refused.",
      "x-data-class": "operational"
    },
    "complete": {
      "type": "boolean",
      "description": "Every step is done and the welcome is sent.",
      "x-data-class": "operational"
    },
    "waiting_on": {
      "type": [
        "string",
        "null"
      ],
      "description": "The first step that is not done, and what it waits for; null when complete.",
      "x-data-class": "operational"
    }
  },
  "required": [
    "provisioning_id",
    "account_name",
    "account_id",
    "org_id",
    "account",
    "org",
    "clerk_org",
    "admin_invite",
    "entitlements",
    "welcome_mail",
    "complete",
    "waiting_on"
  ],
  "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
OutboundF
  • Mobile: degraded: composition
  • MCP: approval required
  • Voice: degraded: composition
  • OneBox: no document originates an account

Events

Related

None.