Contract
- shape
- collection
- authority
- read
- evidence
- none
- subscription
- false
- permission
- any one of: staff.read (the staff role staff_read held in the Internal org, tradehq_role.staff_role); account.member (account role member or higher in at least one account; the call is scoped to those accounts); a deactivated caller is refused first
- idempotency
- safe
- emits
- none
- MCP tool
- list_account_members
- REST
- POST https://api.containertradehq.com/v1/cap/list_account_members
Idempotency: a read: calling again changes nothing
Inputs
| name | type | required | validation |
|---|---|---|---|
| account_id | account_id | required | tradehq-account-id The account whose role holders to list. |
| candidates | boolean | optional | List the people who may be added instead: members of one of the account's entities holding no account role. An owner or staff only. |
| query | text | optional | 1 to 100 characters A case-insensitive substring of the name or email address. |
| limit | integer | optional | 1 to 200; default 50 The page size. |
| after | text | optional | 3 to 22 characters The previous page's next_after. |
Paginated: next next_after · page_max 200 · walk_max 10000 · ceiling declared
Response
items· object[]next_after· stringnull · Pass as `after` for the next page; null on the last one.
Full JSON Schema
{
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"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"
},
"name": {
"type": [
"string",
"null"
],
"description": "Their name.",
"x-data-class": "operational"
},
"email": {
"anyOf": [
{
"type": [
"string",
"null"
]
},
{
"const": "•••",
"description": "Masked by the caller's data policy."
},
{
"type": "null",
"description": "Denied by the caller's data policy."
}
],
"description": "Their address; null once anonymized.",
"x-data-class": "personal"
},
"role": {
"type": [
"string",
"null"
],
"enum": [
"owner",
"member",
null
],
"description": "Their account role; null for a candidate.",
"x-data-class": "operational"
},
"entity_count": {
"type": "integer",
"description": "How many of the account's entities they are a member of.",
"x-data-class": "operational"
},
"entity_total": {
"type": "integer",
"description": "How many entities the account has.",
"x-data-class": "operational"
},
"added_by": {
"type": [
"string",
"null"
],
"description": "Who gave them the role: a user id, or declaration:<ticket>. Null for a candidate.",
"x-data-class": "operational"
},
"added_at": {
"type": [
"string",
"null"
],
"format": "date-time",
"description": "When they were given it. Null for a candidate.",
"x-data-class": "operational"
}
},
"required": [
"user_id",
"name",
"email",
"role",
"entity_count",
"entity_total",
"added_by",
"added_at"
],
"additionalProperties": false
},
"maxItems": 200
},
"next_after": {
"type": [
"string",
"null"
],
"description": "Pass as `after` for the next page; null on the last one."
}
},
"required": [
"items",
"next_after"
],
"additionalProperties": false
} Refusals
The platform refusals apply to every call: version, authentication, authority, validation and rate limits, each in the same envelope.
Surfaces
DesktopF
MobileF
APIF
MCPF
VoiceD4
PushN
OneBoxN
OutboundN
- Voice: degraded: visualization
- Push: emits nothing
- OneBox: no document originates an account role listing
- Outbound: crosses to no counterparty
Events
None emitted.
Related
None.