Book a demo

import_users

Import users

act entity tenant-private since 2026-10-01

Invites a list of up to 500 people into an org in one step, each exactly as invite_user would, optionally all with one role template. The whole list is invited or none of it is. Answers how many were invited, already invited or already members, and which addresses were refused because they belong to a deactivated user. Send an Idempotency-Key header: a retry with the same key and list returns the first answer and invites nobody again.

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
user.invited, users.imported
MCP tool
import_users
decision_set
approve, reject, edit, request_info
REST
POST https://api.containertradehq.com/v1/cap/import_users

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 to invite them into.
inviteesinviteesrequired1 to 500 items
The people: each an email address and, optionally, a full name.
role_template_idtextoptional1 to 64 characters
The role template every new invitee will hold once they join: shipped or this org's own, and carrying nothing your role does not.

Response

  • import_id · string · The import.
  • org_id · string · The org.
  • invited · integer · New invites, each with its invite email.
  • already_invited · integer · Addresses with a pending invite already; nothing written.
  • already_members · integer · Addresses that are members already.
  • refused · string[] · Addresses of deactivated users, not invited.
Full JSON Schema 
{
  "type": "object",
  "properties": {
    "import_id": {
      "type": "string",
      "description": "The import.",
      "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"
    },
    "invited": {
      "type": "integer",
      "description": "New invites, each with its invite email.",
      "x-data-class": "operational"
    },
    "already_invited": {
      "type": "integer",
      "description": "Addresses with a pending invite already; nothing written.",
      "x-data-class": "operational"
    },
    "already_members": {
      "type": "integer",
      "description": "Addresses that are members already.",
      "x-data-class": "operational"
    },
    "refused": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Addresses of deactivated users, not invited.",
      "x-data-class": "operational"
    }
  },
  "required": [
    "import_id",
    "org_id",
    "invited",
    "already_invited",
    "already_members",
    "refused"
  ],
  "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
OutboundF
  • Mobile: degraded: composition
  • MCP: approval required
  • Voice: degraded: composition
  • OneBox: a user list arrives as rows, not as a document

Events

Related

create_invite_link, decide_access_review_item, grant_unit_role, invite_user, resolve_identity_finding, set_member_role