Book a demo

claim_depot

Claim a depot's BFC

act entity canonical-registry since 2026-10-01

Claims a depot's BIC Facility Code (BFC) in the depot registry for the org that runs the yard, and sets it on the org's depot unit. A BFC not in the registry is added, named as given or after the unit. A unit carries one BFC and a BFC is on one unit of an org. A BFC another org has already claimed is not claimed: the call answers 202 and raises a staff exception, and staff decide. An org admin, or an admin of the unit or a unit above it, may claim. The same claim again changes nothing.

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`, or by a role held on the unit `unit_id` or any unit above it by a member of that org; without `unit_id`, by the template); a deactivated caller is refused first
idempotency
natural
emits
depot.claimed
MCP tool
claim_depot
decision_set
approve, reject, request_info, escalate
REST
POST https://api.containertradehq.com/v1/cap/claim_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 runs the yard.
unit_idunit_idrequiredtradehq-unit-id
The org's depot unit the BFC is set on.
bfcbfcrequiredbic-facility-code
The depot's BIC Facility Code.
nametextoptional1 to 200 characters
The depot's name, used only when the BFC is not in the registry yet. Absent, the unit's name.

Response

  • org_id · string · The claiming org.
  • unit_id · string · The depot unit.
  • bfc · string · The BFC.
  • claimed · boolean · True when the org holds the BFC and the unit carries it; 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"
    },
    "unit_id": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$",
      "format": "tradehq-unit-id",
      "description": "The depot unit.",
      "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 BFC.",
      "x-data-class": "operational"
    },
    "claimed": {
      "type": "boolean",
      "description": "True when the org holds the BFC and the unit carries it; 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",
    "unit_id",
    "bfc",
    "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

list_depot_references, reference_depot