Book a demo

list_staff

List Trade HQ staff

read collection tenant-private since 2026-10-01

Lists every staff role held in Trade HQ's Internal org: one item per person and role, with their name, email address, status (active, deactivated or anonymized), the role, who granted it and when. Ordered by person, then role. Staff only.

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); a deactivated caller is refused first
idempotency
safe
emits
none
MCP tool
list_staff
REST
POST https://api.containertradehq.com/v1/cap/list_staff

Idempotency: a read: calling again changes nothing

Inputs

No inputs.

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 staff member.",
            "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": [
              "active",
              "deactivated",
              "anonymized"
            ],
            "description": "active, deactivated or anonymized.",
            "x-data-class": "operational"
          },
          "role_id": {
            "type": "string",
            "enum": [
              "staff_read",
              "staff_ops",
              "staff_provision",
              "staff_finance",
              "staff_adjudicate"
            ],
            "description": "The staff role held.",
            "x-data-class": "operational"
          },
          "granted_by": {
            "type": "string",
            "description": "Who granted it: a user id, or rolemigrate:TRA-318 for the one-shot adoption.",
            "x-data-class": "operational"
          },
          "granted_at": {
            "type": "string",
            "format": "date-time",
            "description": "When it was granted.",
            "x-data-class": "operational"
          }
        },
        "required": [
          "user_id",
          "name",
          "email",
          "status",
          "role_id",
          "granted_by",
          "granted_at"
        ],
        "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 staff listing
  • Outbound: Trade HQ's own staff; crosses to no counterparty

Events

None emitted.

Related

None.