Book a demo

claim_party

Claim an org's party

act entity canonical-registry since 2026-10-01

Claims a party in the party directory as an org's own, which joins the org to the trade graph: the documents that seat that party are then the org's to read as a counterparty. Name the party by party_id and by name. For a party in the directory the name must be its name; a party that is not there yet is added under that id and name, unless the directory holds the name under another id, which is refused with that id. An org claims one party. A party another org has already claimed is not claimed: the call answers 202 and raises a staff exception, and staff decide. The same claim again changes nothing.

Contract

shape
entity
authority
act
evidence
none
subscription
false
permission
any one of: staff.provision (the staff role staff_provision 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
natural
emits
party.claimed
MCP tool
claim_party
decision_set
approve, reject, request_info, escalate
REST
POST https://api.containertradehq.com/v1/cap/claim_party

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 claims the party.
party_iduuidrequiredUUID
The party to claim: one from search_party_directory, or a new party's id.
namenamerequired1 to 200 characters
The party's name: for a party in the directory, its name there (without regard to case or spacing); for a new party, the name it is added under. Trimmed, with each run of whitespace one space.

Response

  • org_id · string · The claiming org.
  • party_id · string · The party.
  • name · string · The party's name in the directory.
  • claimed · boolean · True when the org now claims the party; false when another org holds it and a staff exception was raised.
  • exception_id · stringnull · The staff exception a conflicting claim raised; null when the claim landed.
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 claiming org.",
      "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.",
      "x-data-class": "operational"
    },
    "name": {
      "type": "string",
      "description": "The party's name in the directory.",
      "x-data-class": "operational"
    },
    "claimed": {
      "type": "boolean",
      "description": "True when the org now claims the party; false when another org holds it and a staff exception was raised.",
      "x-data-class": "operational"
    },
    "exception_id": {
      "type": [
        "string",
        "null"
      ],
      "description": "The staff exception a conflicting claim raised; null when the claim landed.",
      "x-data-class": "operational"
    }
  },
  "required": [
    "org_id",
    "party_id",
    "name",
    "claimed",
    "exception_id"
  ],
  "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
OutboundN
  • Mobile: degraded: composition
  • MCP: approval required
  • Voice: degraded: composition
  • OneBox: no document originates a claim
  • Outbound: crosses to no counterparty

Events

Related

add_file, create_data_share, create_upload, invite_guest, list_data_shares, preview_data_share