Book a demo

create_invite_link

Create an invite link

act entity tenant-private since 2026-10-01

Creates a link that invites whoever opens it into an org, optionally with a role template, valid for 1 to 30 days (7 by default). The link is shown once, in this answer; only its hash is kept. Send an Idempotency-Key header: a retry with the same key and inputs returns the same link id with url null, 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`); staff.ops (the staff role staff_ops held in the Internal org, tradehq_role.staff_role); a deactivated caller is refused first
idempotency
keyed
emits
invite_link.created
MCP tool
create_invite_link
decision_set
approve, reject, edit
REST
POST https://api.containertradehq.com/v1/cap/create_invite_link

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 the link invites into.
role_template_idtextoptional1 to 64 characters
The role template a person joining by the link will hold: shipped or this org's own, and carrying nothing your role does not.
expires_in_daysintegeroptional1 to 30; default 7
How many days the link works.

Response

  • link_id · string · The link's id, for revoking it.
  • org_id · string · The org.
  • role_template_id · stringnull · The role template, if any.
  • expires_at · string · When it stops working.
  • url · stringnull · The link. Only in the creating call's answer; null on a replay, because only its hash is stored.
Full JSON Schema 
{
  "type": "object",
  "properties": {
    "link_id": {
      "type": "string",
      "description": "The link's id, for revoking it.",
      "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.",
      "x-data-class": "operational"
    },
    "role_template_id": {
      "type": [
        "string",
        "null"
      ],
      "description": "The role template, if any.",
      "x-data-class": "operational"
    },
    "expires_at": {
      "type": "string",
      "format": "date-time",
      "description": "When it stops working.",
      "x-data-class": "operational"
    },
    "url": {
      "type": [
        "string",
        "null"
      ],
      "description": "The link. Only in the creating call's answer; null on a replay, because only its hash is stored.",
      "x-data-class": "operational"
    }
  },
  "required": [
    "link_id",
    "org_id",
    "role_template_id",
    "expires_at",
    "url"
  ],
  "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*
VoiceD2
PushF
OneBoxN
OutboundN
  • MCP: approval required
  • Voice: degraded: confirmation
  • OneBox: no document originates an invite link
  • Outbound: the admin hands the link over; nothing is sent

Events

Related

decide_access_review_item, grant_unit_role, import_users, invite_user, resolve_identity_finding, set_member_role