list_received_data_shares · List data shares received

Contract

shape: collection
authority: read
evidence: none
subscription: false
permission: any one of: 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_received_data_shares
REST: POST https://api.containertradehq.com/v1/cap/list_received_data_shares

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 receiving org.

Paginated: next next_after · page_max 1000 · walk_max 1000 · 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": {
          "data_share_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 share.",
            "x-data-class": "operational"
          },
          "from_org_id": {
            "type": "string",
            "minLength": 1,
            "maxLength": 20,
            "pattern": "^[A-Za-z0-9_-]{1,20}$",
            "format": "tradehq-org-id",
            "description": "The org that made it.",
            "x-data-class": "operational"
          },
          "from_org_name": {
            "type": "string",
            "description": "That org's name.",
            "x-data-class": "operational"
          },
          "query": {
            "type": "string",
            "enum": [
              "vendor_bill_request",
              "vendor_forecast",
              "vendor_sell_through"
            ],
            "description": "The saved query it shares.",
            "x-data-class": "operational"
          },
          "title": {
            "type": "string",
            "description": "What it is called.",
            "x-data-class": "operational"
          },
          "recipients": {
            "anyOf": [
              {
                "type": "array",
                "items": {
                  "type": "string",
                  "pattern": "^[A-Za-z0-9!#$%&'*+/=?^_`{|}~-]+(\\.[A-Za-z0-9!#$%&'*+/=?^_`{|}~-]+)*@([A-Za-z0-9]([A-Za-z0-9-]*[A-Za-z0-9])?\\.)+([A-Za-z]{2,}|[Xx][Nn]--[A-Za-z0-9-]*[A-Za-z0-9])$",
                  "maxLength": 254
                },
                "uniqueItems": true
              },
              {
                "const": "•••",
                "description": "Masked by the caller's data policy."
              },
              {
                "type": "null",
                "description": "Denied by the caller's data policy."
              }
            ],
            "description": "The addresses it is emailed to.",
            "x-data-class": "personal"
          },
          "cadence": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "daily",
              "hourly",
              null
            ],
            "description": "How often it is emailed.",
            "x-data-class": "operational"
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "When it was made.",
            "x-data-class": "operational"
          },
          "declined_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "When the org stopped receiving it, or null.",
            "x-data-class": "operational"
          },
          "declinable": {
            "type": "boolean",
            "description": "Whether decline_data_share can still decline it: a live share can.",
            "x-data-class": "operational"
          }
        },
        "required": [
          "data_share_id",
          "from_org_id",
          "from_org_name",
          "query",
          "title",
          "recipients",
          "cadence",
          "created_at",
          "declined_at",
          "declinable"
        ],
        "additionalProperties": false
      },
      "maxItems": 1000
    },
    "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

org_party_unclaimed · 422 · the org has claimed no party, so no share can reach it

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 listing of shares received
Outbound: a listing is read inside Trade HQ; nothing is sent

Events

None emitted.

None.