Book a demo

create_unit

Create a unit

act entity tenant-private since 2026-10-01

Creates a unit (a division, region, depot or office) in an org's unit tree, beneath a parent unit or as a root, and returns its id. A depot is a leaf: nothing can be created beneath one. An org admin can create anywhere in the tree; a member who holds admin on a unit can create beneath that unit. A role held on a unit reaches every unit beneath it. Send an Idempotency-Key header: a retry with the same key and inputs returns the same unit and creates 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 `parent_id` or any unit above it by a member of that org; without `parent_id`, by the template); a deactivated caller is refused first
idempotency
keyed
emits
unit.created
MCP tool
create_unit
decision_set
approve, reject, edit, request_info
REST
POST https://api.containertradehq.com/v1/cap/create_unit

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 unit joins.
parent_idunit_idoptionaltradehq-unit-id
The unit it goes beneath, in the same org. Absent, the unit is a root.
kindone_ofrequiredone of division, region, depot, office
division, region, depot (a yard, always a leaf) or office.
nametextrequired1 to 200 characters
The unit's name, as the org's people know it.

Response

  • unit_id · string · The new unit's id.
  • org_id · string · Its org.
  • parent_id · stringnull · Its parent; null for a root.
  • kind · string · Its kind.
  • name · string · Its name.
  • created_by · string · Who created it.
Full JSON Schema 
{
  "type": "object",
  "properties": {
    "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 new unit'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": "Its org.",
      "x-data-class": "operational"
    },
    "parent_id": {
      "type": [
        "string",
        "null"
      ],
      "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": "Its parent; null for a root.",
      "x-data-class": "operational"
    },
    "kind": {
      "type": "string",
      "enum": [
        "division",
        "region",
        "depot",
        "office"
      ],
      "description": "Its kind.",
      "x-data-class": "operational"
    },
    "name": {
      "type": "string",
      "description": "Its name.",
      "x-data-class": "operational"
    },
    "created_by": {
      "type": "string",
      "minLength": 1,
      "maxLength": 20,
      "pattern": "^[A-Za-z0-9_-]{1,20}$",
      "format": "tradehq-user-id",
      "description": "Who created it.",
      "x-data-class": "operational"
    }
  },
  "required": [
    "unit_id",
    "org_id",
    "parent_id",
    "kind",
    "name",
    "created_by"
  ],
  "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 unit
  • Outbound: crosses to no counterparty

Events

Related

import_units