Book a demo

set_document_parties

Set a document's parties

act entity controlled-share since 2026-10-01

Sets the parties on one commercial document (a purchase order is an asset_intake, a lease or sale is an order) and the seat each holds, replacing the seats it had. Each party is from the shared directory. When a Trade HQ org has claimed a party, that org's members can then read their own seat on this document. Sending the same set again changes nothing.

Contract

shape
entity
authority
act
evidence
none
subscription
false
permission
any one of: org.member (carried by the caller's role template in the org `org_id`, which owns the document `document_kind`/`document_id`); a deactivated caller is refused first
idempotency
natural
emits
document.parties_changed
MCP tool
set_document_parties
decision_set
approve, reject, edit
REST
POST https://api.containertradehq.com/v1/cap/set_document_parties

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

Idempotency: keyed by the contract's own inputs: the same inputs replay the first call's result

Inputs

nametyperequiredvalidation
org_idorg_idrequiredtradehq-org-id; 1 to 20 characters
The org that owns the document.
document_kindone_ofrequiredone of asset_intake, order
The table the document is in: asset_intake (a purchase order) or order.
document_idtextrequired1 to 64 characters
The document's id in that table.
partiespartiesrequired0 to 20 items
Every party on the document and its seat. An asset_intake takes buyer and seller; an order takes buyer, seller, lessor and lessee. An empty list removes every seat.

Response

  • org_id · string · The org that owns the document.
  • document_kind · string · The document's kind.
  • document_id · string · The document's id.
  • seats · integer · How many seats the document now carries.
Full JSON Schema 
{
  "type": "object",
  "properties": {
    "org_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 20,
      "pattern": "^[A-Za-z0-9_-]{1,20}$",
      "format": "tradehq-org-id",
      "description": "The org that owns the document.",
      "x-data-class": "operational"
    },
    "document_kind": {
      "type": "string",
      "enum": [
        "asset_intake",
        "order"
      ],
      "description": "The document's kind.",
      "x-data-class": "operational"
    },
    "document_id": {
      "type": "string",
      "description": "The document's id.",
      "x-data-class": "operational"
    },
    "seats": {
      "type": "integer",
      "description": "How many seats the document now carries.",
      "x-data-class": "operational"
    }
  },
  "required": [
    "org_id",
    "document_kind",
    "document_id",
    "seats"
  ],
  "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*
VoiceD2
PushF
OneBoxN
OutboundN
  • MCP: approval required
  • Voice: degraded: confirmation
  • OneBox: no document originates its own party assignment
  • Outbound: a seat is read inside Trade HQ; nothing is sent to the counterparty

Events

Related

invite_guest, list_document_parties