Book a demo

list_users

List users

read collection tenant-private since 2026-10-01

Lists an org's members and pending invitees, ordered by user id, a page at a time. Each carries a name, an email address (null once anonymized), a status (invited, active, deactivated or anonymized), their membership role and their role template. Filters by status and by a case-insensitive substring of the name or address. An org admin reads it, and so does a member who administers a unit (delegated administration), read-only.

Contract

shape
collection
authority
read
evidence
none
subscription
false
permission
any one of: org.admin (carried by the caller's role template in the org `org_id`); staff.read (the staff role staff_read held in the Internal org, tradehq_role.staff_role); org.member (carried by the caller's role template in the org `org_id`); a deactivated caller is refused first
idempotency
safe
emits
none
MCP tool
list_users
REST
POST https://api.containertradehq.com/v1/cap/list_users

Idempotency: a read: calling again changes nothing

Inputs

nametyperequiredvalidation
org_idorg_idrequiredtradehq-org-id; 1 to 20 characters
The org whose users to list.
statusone_ofoptionalone of invited, active, deactivated, anonymized
Only users with this status.
querytextoptional1 to 100 characters
A case-insensitive substring of the name or email address.
limitintegeroptional1 to 200; default 50
The page size.
afteruser_idoptionaltradehq-user-id; 1 to 20 characters
The previous page's next_after.

Paginated: next next_after · ceiling not_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 user.",
            "x-data-class": "operational"
          },
          "name": {
            "type": [
              "string",
              "null"
            ],
            "description": "Their name; the tombstone once anonymized.",
            "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"
          },
          "status": {
            "type": "string",
            "enum": [
              "invited",
              "active",
              "deactivated",
              "anonymized"
            ],
            "description": "Where they are in their lifecycle.",
            "x-data-class": "operational"
          },
          "role_template_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "A member's assigned role template, which decides what they may call; an invitee's, the one they will hold. Null: none.",
            "x-data-class": "operational"
          },
          "unit_grants": {
            "type": "integer",
            "description": "How many roles they hold on units of the org that the caller may see: every one for an org admin or staff, only those on units a delegate administers for a delegate (TRA-473).",
            "x-data-class": "operational"
          }
        },
        "required": [
          "user_id",
          "name",
          "email",
          "status",
          "role_template_id",
          "unit_grants"
        ],
        "additionalProperties": false
      }
    },
    "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

not yet declared

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 a user listing
  • Outbound: crosses to no counterparty

Events

None emitted.

Related

list_accounts, list_agent_reads, list_audit_events, list_audit_exports, list_orgs, list_staff_grants, list_unit_access