Book a demo

reference_depot

Reference a third-party depot

act entity tenant-private since 2026-10-01

Maps an org's own name and code for a depot it uses but does not run to the depot's BIC Facility Code (BFC) in the registry, so the org's documents can name the yard its own way and still mean the canonical one. The depot must be in the registry (list_depot_registry). With no private code, the alias is the code. An org maps a depot once, and a code to one depot; the same mapping again changes nothing. The mapping is the org's own: no other tenant sees it. Any member of the org may make it.

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`); a deactivated caller is refused first
idempotency
natural
emits
depot.referenced
MCP tool
reference_depot
decision_set
approve, reject, edit, request_info
REST
POST https://api.containertradehq.com/v1/cap/reference_depot

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 uses the depot.
bfcbfcrequiredbic-facility-code
The depot's BIC Facility Code, from list_depot_registry.
aliastextrequired1 to 200 characters
The org's own name for the depot.
private_codetextoptional1 to 64 characters
The org's own code for the depot, as its systems write it. Absent, the alias.

Response

  • depot_reference_id · string · The mapping's id.
  • org_id · string · The org.
  • bfc · string · The canonical BFC.
  • alias · string · The org's name for it.
  • private_code · string · The org's code for it.
Full JSON Schema 
{
  "type": "object",
  "properties": {
    "depot_reference_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 mapping's id.",
      "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.",
      "x-data-class": "operational"
    },
    "bfc": {
      "type": "string",
      "pattern": "^[A-Z]{2}[A-Z2-9]{3}[A-Z0-9]{4}$",
      "format": "bic-facility-code",
      "description": "The canonical BFC.",
      "x-data-class": "operational"
    },
    "alias": {
      "type": "string",
      "description": "The org's name for it.",
      "x-data-class": "operational"
    },
    "private_code": {
      "type": "string",
      "description": "The org's code for it.",
      "x-data-class": "operational"
    }
  },
  "required": [
    "depot_reference_id",
    "org_id",
    "bfc",
    "alias",
    "private_code"
  ],
  "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 a mapping
  • Outbound: crosses to no counterparty

Events

Related

claim_depot, list_depot_references