Book a demo

import_units

Import units from a CSV

act entity tenant-private since 2026-10-01

Creates many units at once from a CSV file, and claims each depot's BIC Facility Code (BFC) in the same pass. The header names the columns: ref, kind and name are required; parent_ref (another row's ref) and bfc are optional. Rows with no parent_ref go beneath parent_id, or become roots when it is absent. A depot is a leaf, and a BFC goes only on a depot. The file is checked whole and written whole: any bad row, or a BFC another org has claimed, refuses it and nothing is created. Send an Idempotency-Key header: under the same key, units already created exactly as the file says are reported and left alone and only the file's new rows are created, so a retry creates nothing and a file that extends an earlier one completes it; a row that differs from what the key created is refused.

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 `parent_id` or any unit above it by a member of that org; without `parent_id`, by the template); staff.provision (the staff role staff_provision held in the Internal org, tradehq_role.staff_role); a deactivated caller is refused first
idempotency
keyed
emits
units.imported, depot.claimed
MCP tool
import_units
decision_set
approve, reject, edit, request_info
REST
POST https://api.containertradehq.com/v1/cap/import_units

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 tree the units join.
parent_idunit_idoptionaltradehq-unit-id
Where rows with no parent_ref go. Absent, they become roots.
csvtextrequired1 to 1000000 characters
The file: a header row, then one row per unit. Columns ref, kind, name, and optionally parent_ref and bfc.

Response

  • import_id · string · This import's id, derived from the Idempotency-Key.
  • units_created · integer · The units this call created.
  • units_existing · integer · The file's units this key had already created, exactly as the file says; left alone.
  • depots_claimed · integer · The BFCs this call claimed for the org in the registry, one per depot.claimed event.
  • bfcs_set · integer · The units this call created carrying a BFC, the org's own claims included.
  • unit_ids · string[] · Every unit of the file, created now or before, in the file's row order.
Full JSON Schema 
{
  "type": "object",
  "properties": {
    "import_id": {
      "type": "string",
      "description": "This import's id, derived from the Idempotency-Key.",
      "x-data-class": "operational"
    },
    "units_created": {
      "type": "integer",
      "description": "The units this call created.",
      "x-data-class": "operational"
    },
    "units_existing": {
      "type": "integer",
      "description": "The file's units this key had already created, exactly as the file says; left alone.",
      "x-data-class": "operational"
    },
    "depots_claimed": {
      "type": "integer",
      "description": "The BFCs this call claimed for the org in the registry, one per depot.claimed event.",
      "x-data-class": "operational"
    },
    "bfcs_set": {
      "type": "integer",
      "description": "The units this call created carrying a BFC, the org's own claims included.",
      "x-data-class": "operational"
    },
    "unit_ids": {
      "type": "array",
      "items": {
        "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": "Every unit of the file, created now or before, in the file's row order.",
      "x-data-class": "operational"
    }
  },
  "required": [
    "import_id",
    "units_created",
    "units_existing",
    "depots_claimed",
    "bfcs_set",
    "unit_ids"
  ],
  "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*
VoiceN
PushF
OneBoxN
OutboundN
  • Mobile: degraded: composition
  • MCP: approval required
  • Voice: a file does not arrive by voice
  • OneBox: the file is this capability's input on every surface; no document originates it
  • Outbound: crosses to no counterparty

Events

Related

create_unit