create_data_share · Share data with a counterparty

Contract

shape: entity
authority: act
evidence: none
subscription: false
permission: any one of: org.admin (carried by the caller's role template in the org `org_id`); a deactivated caller is refused first
idempotency: keyed
emits: share.created
MCP tool: create_data_share
decision_set: approve, reject, edit
REST: POST https://api.containertradehq.com/v1/cap/create_data_share

Through MCP this call returns an approval request first; see Approvals.

Idempotency: keyed by the caller's Idempotency-Key, which is required: the same key and inputs replay the first result, the same key with other inputs is 409 idempotency_key_reused

Inputs

name	type	required	validation
org_id	org_id	required	tradehq-org-id; 1 to 20 characters The org sharing its data.
party_id	uuid	required	UUID The counterparty, from the shared party directory.
query	one_of	required	one of vendor_bill_request, vendor_forecast, vendor_sell_through The saved query: vendor_forecast (the org's open purchase orders with the vendor, with ETAs and units), vendor_sell_through (units bought from the vendor, sold and on hand, by size, type and condition) or vendor_bill_request (one bill request's units, as the cash flow audit's vendor export lists them).
contact_id	contact_id	optional	tradehq-contact-id; 3 to 20 characters For vendor_forecast and vendor_sell_through: the vendor, one of the org's own contacts. The party must hold the seller seat on at least one of the org's purchase orders with it, and only those purchase orders are shared. When the vendor is itself a Trade HQ org, the party must be the one that org has claimed.
request_id	bill_request_id	optional	tradehq-vendor-bill-request-id; 3 to 20 characters For vendor_bill_request: the cash flow audit's vendor bill request. Its units' one vendor is the vendor, and the party must hold the seller seat on every purchase order the units came in on.
recipients	emails	required	1 to 10 items; unique The counterparty's addresses the share is emailed to, 1 to 10.
cadence	one_of	optional	one of daily, hourly; default "daily" daily (the default) or hourly.

Response

data_share_id · string · The share, derived from the Idempotency-Key.
org_id · string · The org sharing.
party_id · string · The counterparty.
party_name · string · The counterparty's name in the directory.
query · string · The saved query shared.
title · string · The saved query's title, as the counterparty reads it.
recipients · value · Who it is emailed to, sorted.
cadence · string · How often it is emailed.
row_total · integer · How many rows it renders now.
created_at · string · When it was created.
revoked_at · stringnull · Null; set on a replay of a share revoked since.

Full JSON Schema

{
  "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, derived from the Idempotency-Key.",
      "x-data-class": "operational"
    },
    "org_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 20,
      "pattern": "^[A-Za-z0-9_-]{1,20}$",
      "format": "tradehq-org-id",
      "description": "The org sharing.",
      "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 counterparty.",
      "x-data-class": "operational"
    },
    "party_name": {
      "type": "string",
      "description": "The counterparty's name in the directory.",
      "x-data-class": "operational"
    },
    "query": {
      "type": "string",
      "enum": [
        "vendor_bill_request",
        "vendor_forecast",
        "vendor_sell_through"
      ],
      "description": "The saved query shared.",
      "x-data-class": "operational"
    },
    "title": {
      "type": "string",
      "description": "The saved query's title, as the counterparty reads it.",
      "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": "Who it is emailed to, sorted.",
      "x-data-class": "personal"
    },
    "cadence": {
      "type": "string",
      "enum": [
        "daily",
        "hourly"
      ],
      "description": "How often it is emailed.",
      "x-data-class": "operational"
    },
    "row_total": {
      "type": "integer",
      "minimum": 0,
      "description": "How many rows it renders now.",
      "x-data-class": "operational"
    },
    "created_at": {
      "type": "string",
      "format": "date-time",
      "description": "When it was created.",
      "x-data-class": "operational"
    },
    "revoked_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time",
      "description": "Null; set on a replay of a share revoked since.",
      "x-data-class": "operational"
    }
  },
  "required": [
    "data_share_id",
    "org_id",
    "party_id",
    "party_name",
    "query",
    "title",
    "recipients",
    "cadence",
    "row_total",
    "created_at",
    "revoked_at"
  ],
  "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

MobileD5

APIF

MCPF*

VoiceD5

PushF

OneBoxN

OutboundF

Mobile: degraded: composition
MCP: approval required
Voice: degraded: composition
OneBox: no document originates a data share

Events

share.created planned_webhook

claim_party, invite_guest, list_data_shares, preview_data_share, search_party_directory