Book a demo

route_held_file

Route a held file

act entity tenant-private since 2026-10-01

Gives a held file (one that arrived where no org could be told) the org it belongs to, so it is filed there. Staff only.

Contract

shape
entity
authority
act
evidence
none
subscription
false
permission
any one of: staff.ops (the staff role staff_ops held in the Internal org, tradehq_role.staff_role); a deactivated caller is refused first
idempotency
natural
emits
intake.received
MCP tool
route_held_file
decision_set
approve, reject
REST
POST https://api.containertradehq.com/v1/cap/route_held_file

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 the file belongs to.
upload_idtextrequired26 to 26 characters
The held file's intake id.

Response

  • upload_id · string · The file's intake id.
  • org_id · string · The org it was routed to.
  • state · string · received when it is waiting to be filed, then filed.
Full JSON Schema 
{
  "type": "object",
  "properties": {
    "upload_id": {
      "type": "string",
      "description": "The file's intake 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 it was routed to.",
      "x-data-class": "operational"
    },
    "state": {
      "type": "string",
      "enum": [
        "received",
        "filed"
      ],
      "description": "received when it is waiting to be filed, then filed.",
      "x-data-class": "operational"
    }
  },
  "required": [
    "upload_id",
    "org_id",
    "state"
  ],
  "additionalProperties": false
}

Refusals

  • held_object_missing · 409 · the intake holds no object for this held file, neither held nor back at its holding key
  • files_unavailable · 422 · this deployment has no intake or files store configured yet
  • org_is_a_test_twin · 422 · the org is a test twin; files belong to its live org

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

Surfaces

DesktopF
MobileN
APIF
MCPF*
VoiceN
PushF
OneBoxN
OutboundN
  • Mobile: staff route held files from a desk
  • MCP: approval required
  • Voice: a voice surface routes no file
  • OneBox: a held file is routed by a person, not a document
  • Outbound: crosses to no counterparty

Events

Related

complete_upload