Book a demo

invite_user

Invite a user

act entity tenant-private since 2026-10-01

Invites a person, by email address, into an org, optionally with a role template. Records the invite and the invite email as an outbound document; the person gets a login (no password) and the email once identity-provisioner has run. Inviting an address that already has a pending invite into the org changes nothing. A current member, or a deactivated user, 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`); 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
user.invited
MCP tool
invite_user
decision_set
approve, reject, edit, request_info
REST
POST https://api.containertradehq.com/v1/cap/invite_user

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 to invite them into.
emailemailrequiredemail address; 3 to 254 characters
Their email address. It becomes their sign-in.
nametextoptional1 to 255 characters
Their full name, used in the email and set only if they have none yet.
role_template_idtextoptional1 to 64 characters
The role template they will hold once they join: a shipped template or this org's own, carrying nothing your role does not. Recorded with the invite; it grants nothing until they are a member.

Response

  • user_id · string · The invitee.
  • org_id · string · The org.
  • email · value · The address, cleaned.
  • document_id · stringnull · The invite email's outbound document; null only for an invite made before TRA-319, which has none.
Full JSON Schema 
{
  "type": "object",
  "properties": {
    "user_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 20,
      "pattern": "^[A-Za-z0-9_-]{1,20}$",
      "format": "tradehq-user-id",
      "description": "The invitee.",
      "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"
    },
    "email": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "const": "•••",
          "description": "Masked by the caller's data policy."
        },
        {
          "type": "null",
          "description": "Denied by the caller's data policy."
        }
      ],
      "description": "The address, cleaned.",
      "x-data-class": "personal"
    },
    "document_id": {
      "type": [
        "string",
        "null"
      ],
      "description": "The invite email's outbound document; null only for an invite made before TRA-319, which has none.",
      "x-data-class": "operational"
    }
  },
  "required": [
    "user_id",
    "org_id",
    "email",
    "document_id"
  ],
  "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
OutboundF
  • MCP: approval required
  • Voice: degraded: confirmation
  • OneBox: no document originates an invitation

Events

Related

create_access_review, create_invite_link, create_sso_connection, decide_access_review_item, grant_unit_role, import_users, resolve_identity_finding, set_member_role, update_sso_connection