Book a demo

get_test_twin

Get an org's test twin

read entity tenant-private since 2026-10-01

Returns the test twin of an org: the org of its own that test mode acts in, whose members, roles, units and settings mirror the live org and whose business data is its own. Accepts the live org's id or the twin's and answers the same. Says whether the twin is in line with the live org now, and which of those four it differs in if not. Changes nothing.

Contract

shape
entity
authority
read
evidence
none
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
safe
emits
none
MCP tool
get_test_twin
REST
POST https://api.containertradehq.com/v1/cap/get_test_twin

Idempotency: a read: calling again changes nothing

Inputs

nametyperequiredvalidation
org_idorg_idrequiredtradehq-org-id; 1 to 20 characters
The org, or its twin.

Response

  • org_id · string · The live org.
  • twin_org_id · string · Its test twin, the org test mode and sk_test_ keys act in.
  • twin_name · string · The twin's name.
  • org_type · string · The type the twin shares with its live org.
  • in_sync · boolean · Whether the twin's members, roles, units and settings equal the live org's now.
  • drift · stringnull · The classes the twin differs in, comma separated (roles, members, units, settings); null when in sync.
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 live org.",
      "x-data-class": "operational"
    },
    "twin_org_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 20,
      "pattern": "^[A-Za-z0-9_-]{1,20}$",
      "format": "tradehq-org-id",
      "description": "Its test twin, the org test mode and sk_test_ keys act in.",
      "x-data-class": "operational"
    },
    "twin_name": {
      "type": "string",
      "description": "The twin's name.",
      "x-data-class": "operational"
    },
    "org_type": {
      "type": "string",
      "enum": [
        "internal",
        "demo",
        "customer",
        "synthetic",
        "system"
      ],
      "description": "The type the twin shares with its live org.",
      "x-data-class": "operational"
    },
    "in_sync": {
      "type": "boolean",
      "description": "Whether the twin's members, roles, units and settings equal the live org's now.",
      "x-data-class": "operational"
    },
    "drift": {
      "type": [
        "string",
        "null"
      ],
      "description": "The classes the twin differs in, comma separated (roles, members, units, settings); null when in sync.",
      "x-data-class": "operational"
    }
  },
  "required": [
    "org_id",
    "twin_org_id",
    "twin_name",
    "org_type",
    "in_sync",
    "drift"
  ],
  "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
MobileF
APIF
MCPF
VoiceD4
PushN
OneBoxN
OutboundN
  • Voice: degraded: visualization
  • Push: emits nothing
  • OneBox: no document originates a twin lookup
  • Outbound: crosses to no counterparty

Events

None emitted.

Related

None.