Book a demo

record_gate_event

Record a gate event

act entity tenant-private since 2026-10-01

Records that a container crossed a depot's gate, in or out: when it happened, when Trade HQ learned it, where the report came from and its EIR if any. The first report of a movement records it. A later report of the same movement is linked to it and records nothing new, and one that disagrees with it is linked and raises an exception for a person to decide; nothing is overwritten. Send an Idempotency-Key: the same key and report again returns the first answer.

Contract

shape
entity
authority
act
evidence
optional
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
keyed
emits
gate_event.recorded, gate_event.conflicted
MCP tool
record_gate_event
decision_set
approve, reject, edit, request_info
REST
POST https://api.containertradehq.com/v1/cap/record_gate_event

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

nametyperequiredvalidation
org_idorg_idrequiredtradehq-org-id; 1 to 20 characters
The org whose depot ledger the movement is in.
kindone_ofrequiredone of gate-in, gate-out
gate-in: the container entered the depot. gate-out: it left.
containerunit_numberrequiredISO 6346
The container's ISO 6346 number, upper case, with its check digit.
depottextrequired1 to 20 characters
The depot's yard id: a yard of this org, or a shared one.
occurred_attimestamprequiredtimestamp, RFC 3339
When the container crossed the gate, with its offset. The movement's day (gated_at) is this instant's UTC calendar day.
observed_attimestampoptionaltimestamp, RFC 3339
When Trade HQ learned of it, with its offset. Leave out for now.
sourceone_ofrequiredone of eir, email_report, carrier_feed, depot_system, manual
Where the report came from: an EIR, an emailed depot report, a carrier's feed, a depot's own system, or a person.
eir_reftextoptional1 to 100 characters
The equipment interchange receipt's reference, if the report carries one.

Response

  • observation_id · string · This report's observation.
  • relation · string · original: this report recorded the movement. duplicate: it agrees with an earlier report and was linked to it. conflict: it disagrees, was linked, and raised an exception.
  • gate_event_id · string · The movement: its gate-in or gate-out id.
  • duplicate_of · stringnull · The earlier observation this one is linked to; null for an original.
  • exception_id · stringnull · The exception a conflict raised; null otherwise.
  • kind · string · The movement's kind.
  • container · string · The container's ISO 6346 number.
Full JSON Schema 
{
  "type": "object",
  "properties": {
    "observation_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": "This report's observation.",
      "x-data-class": "operational"
    },
    "relation": {
      "type": "string",
      "enum": [
        "original",
        "duplicate",
        "conflict"
      ],
      "description": "original: this report recorded the movement. duplicate: it agrees with an earlier report and was linked to it. conflict: it disagrees, was linked, and raised an exception.",
      "x-data-class": "operational"
    },
    "gate_event_id": {
      "type": "string",
      "description": "The movement: its gate-in or gate-out id.",
      "x-data-class": "operational"
    },
    "duplicate_of": {
      "type": [
        "string",
        "null"
      ],
      "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 earlier observation this one is linked to; null for an original.",
      "x-data-class": "operational"
    },
    "exception_id": {
      "type": [
        "string",
        "null"
      ],
      "description": "The exception a conflict raised; null otherwise.",
      "x-data-class": "operational"
    },
    "kind": {
      "type": "string",
      "enum": [
        "gate-in",
        "gate-out"
      ],
      "description": "The movement's kind.",
      "x-data-class": "operational"
    },
    "container": {
      "type": "string",
      "description": "The container's ISO 6346 number.",
      "x-data-class": "operational"
    }
  },
  "required": [
    "observation_id",
    "relation",
    "gate_event_id",
    "duplicate_of",
    "exception_id",
    "kind",
    "container"
  ],
  "additionalProperties": false
}

Refusals

  • capability_not_enabled · 422 · record_gate_event is not switched on for this org yet (its release flag)
  • observed_before_occurred · 422 · observed_at is before occurred_at; a movement is not learned of before it happens
  • observed_in_future · 422 · observed_at is later than now, past five minutes of clock skew
  • unknown_depot · 422 · the depot is not a yard of this org or a shared one
  • retry_key_mismatch · 409 · the Idempotency-Key was already used with a different report
  • retry_key_in_flight · 409 · a request with this Idempotency-Key is still running
  • retry_key_lost · 409 · another request took over this Idempotency-Key first; nothing was recorded

The platform refusals apply to every call: version, authentication, authority, validation and rate limits, each in the same envelope.

Surfaces

DesktopF
MobileD5
APIF
MCPF*
VoiceD2
PushF
OneBoxD5
OutboundN
  • Mobile: degraded: composition
  • MCP: approval required
  • Voice: degraded: confirmation
  • OneBox: degraded: composition
  • Outbound: crosses to no counterparty

Events

Related

None.