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); org.admin (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_guests
- REST
- POST https://api.containertradehq.com/v1/cap/list_guests
Idempotency: a read: calling again changes nothing
Inputs
| name | type | required | validation |
|---|---|---|---|
| org_id | org_id | required | tradehq-org-id; 1 to 20 characters The org whose guests to list. |
| limit | integer | optional | 1 to 200; default 50 The page size. |
| after | user_id | optional | tradehq-user-id; 1 to 20 characters Only guests whose user_id sorts strictly after this one: pass the previous page's next_after, which is the last user_id that page returned. Absent, the first page. |
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 guest.",
"x-data-class": "operational"
},
"email": {
"anyOf": [
{
"type": "string"
},
{
"const": "•••",
"description": "Masked by the caller's data policy."
},
{
"type": "null",
"description": "Denied by the caller's data policy."
}
],
"description": "Their sign-in address.",
"x-data-class": "personal"
},
"name": {
"type": [
"string",
"null"
],
"description": "Their name, when they have one.",
"x-data-class": "operational"
},
"party_id": {
"type": "string",
"pattern": "^[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}$",
"format": "uuid",
"description": "The party they are.",
"x-data-class": "operational"
},
"party_name": {
"type": "string",
"description": "The party's name in the directory.",
"x-data-class": "operational"
},
"seat": {
"type": "string",
"enum": [
"lessee",
"seller"
],
"description": "Their seat.",
"x-data-class": "operational"
},
"role_id": {
"type": [
"string",
"null"
],
"description": "The Counterparty template they hold; null once revoked.",
"x-data-class": "operational"
},
"shape": {
"type": "string",
"enum": [
"forwarder",
"supplier"
],
"description": "What their view shows.",
"x-data-class": "operational"
},
"invited_from_kind": {
"type": "string",
"enum": [
"asset_intake",
"order"
],
"description": "The kind of the document they were invited from.",
"x-data-class": "operational"
},
"invited_from_id": {
"type": "string",
"description": "That document's id.",
"x-data-class": "operational"
},
"invited_by": {
"type": "string",
"minLength": 1,
"maxLength": 20,
"pattern": "^[A-Za-z0-9_-]{1,20}$",
"format": "tradehq-user-id",
"description": "Who invited them.",
"x-data-class": "operational"
},
"invited_at": {
"type": "string",
"format": "date-time",
"description": "When.",
"x-data-class": "operational"
},
"expires_on": {
"type": [
"string",
"null"
],
"pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$",
"format": "date",
"description": "Their last day of access, a UTC date, or null when it does not expire.",
"x-data-class": "operational"
},
"status": {
"type": "string",
"enum": [
"active",
"expired",
"revoked"
],
"description": "active; expired once past expires_on, when they are refused in the org as a revoked guest is; revoked once revoke_guest has ended their access.",
"x-data-class": "operational"
},
"revoked_at": {
"type": [
"string",
"null"
],
"format": "date-time",
"description": "When their access was revoked, or null.",
"x-data-class": "operational"
},
"signed_in": {
"type": "boolean",
"description": "Whether they have signed in to the org.",
"x-data-class": "operational"
},
"document_count": {
"type": "integer",
"minimum": 0,
"description": "How many of the org's documents their party holds their seat on: what their view lists while their access stands.",
"x-data-class": "operational"
}
},
"required": [
"user_id",
"email",
"name",
"party_id",
"party_name",
"seat",
"role_id",
"shape",
"invited_from_kind",
"invited_from_id",
"invited_by",
"invited_at",
"expires_on",
"status",
"revoked_at",
"signed_in",
"document_count"
],
"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 guest listing
- Outbound: crosses to no counterparty
Events
None emitted.