remove_account_member

Remove a person from an account

act entity tenant-private since 2026-10-01

Takes a person's account role away. Their roles in each entity they belong to are kept, and so are their records. The account's only owner cannot be removed, and someone who holds no role in the account is not found.

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); 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: natural
emits: account_role.removed
MCP tool: remove_account_member
decision_set: approve, reject, escalate
REST: POST https://api.containertradehq.com/v1/cap/remove_account_member

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

name	type	required	validation
account_id	account_id	required	tradehq-account-id The account.
user_id	user_id	required	tradehq-user-id; 1 to 20 characters The person whose account role to take away.

Response

account_id · string · The account.
user_id · string · The person.
previous_role · string · The role they held.

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 account.",
      "x-data-class": "operational"
    },
    "user_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 20,
      "pattern": "^[A-Za-z0-9_-]{1,20}$",
      "format": "tradehq-user-id",
      "description": "The person.",
      "x-data-class": "operational"
    },
    "previous_role": {
      "type": "string",
      "enum": [
        "owner",
        "member"
      ],
      "description": "The role they held.",
      "x-data-class": "operational"
    }
  },
  "required": [
    "account_id",
    "user_id",
    "previous_role"
  ],
  "additionalProperties": false
}

Refusals

last_account_owner · 422 · the person is the account's only owner

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 an account role change
Outbound: crosses to no counterparty

Events

account_role.removed audit_only

None.

get a test key

curl https://api.containertradehq.com/v1/cap/remove_account_member \
  -H "Authorization: Bearer $TRADEHQ_API_KEY" \
  -H "Trade-HQ-Version: 2026-10-01" \
  -H "Content-Type: application/json" \
  -d '{"account_id":"00000000-0000-4000-8000-000000000000","user_id":"<user_id>"}'

import { TradeHQ } from '@containertradehq/sdk';

const tradehq = new TradeHQ({ apiKey: process.env.TRADEHQ_API_KEY! });
const result = await tradehq.removeAccountMember({
  "account_id": "00000000-0000-4000-8000-000000000000",
  "user_id": "<user_id>"
});

import os
from containertradehq import TradeHQ

tradehq = TradeHQ(os.environ["TRADEHQ_API_KEY"])
result = tradehq.remove_account_member({
    "account_id": "00000000-0000-4000-8000-000000000000",
    "user_id": "<user_id>",
})

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "remove_account_member",
    "arguments": {
      "account_id": "00000000-0000-4000-8000-000000000000",
      "user_id": "<user_id>"
    }
  }
}

MCP

remove_account_member · readOnlyHint false · approval required

“Call remove_account_member”