v4

latestOpenAPI 3.1.1Apache 2.02026-07-31107278570.4 KB

Users

Create new user in organization

Creates a new user account and immediately adds them to the specified organization. Use this endpoint when you want to create a user and grant them access to an organization in a single operation. You can provide user profile information, assign roles, and configure membership metadata. The user receives an activation email unless this feature is disabled in the organization settings.

post/api/v1/organizations/{organization_id}/users

Path parameters

organization_idstring required

Query parameters

send_invitation_emailboolean

If true, sends an activation email to the user. Defaults to true.

Request body

emailstring

Primary email address for the user. Must be unique across the environment and valid per RFC 5322.

external_idstring

Your application's unique identifier for this organization, used to link Scalekit with your system.

metadataobject

Custom key-value pairs for storing additional user context. Keys (3-25 chars), values (1-256 chars).

Example request

{
  "email": "user@example.com",
  "external_id": "ext_12345a67b89c",
  "membership": {
    "inviter_email": "john.doe@example.com",
    "metadata": {
      "department": "engineering",
      "location": "nyc-office"
    },
    "roles": [
      {
        "name": "admin"
      }
    ]
  },
  "metadata": {
    "department": "engineering",
    "location": "nyc-office"
  },
  "user_profile": {
    "custom_attributes": {
      "department": "engineering",
      "security_clearance": "level2"
    },
    "family_name": "Doe",
    "gender": "male",
    "given_name": "John",
    "groups": [
      "engineering",
      "managers"
    ],
    "locale": "en-US",
    "metadata": {
      "account_status": "active",
      "signup_source": "mobile_app"
    },
    "name": "John Michael Doe",
    "phone_number": "+14155552671",
    "picture": "https://example.com/avatar.jpg",
    "preferred_username": "John Michael Doe"
  }
}

Response

User created successfully. Returns the created user object, including system-generated identifiers and timestamps

Example response

{
  "user": {
    "email": "user@example.com",
    "external_id": "ext_12345a67b89c",
    "id": "usr_1234abcd5678efgh",
    "memberships": [
      {
        "display_name": "Acme Corporation",
        "metadata": {
          "department": "engineering",
          "location": "nyc-office"
        },
        "name": "AcmeCorp",
        "organization_id": "org_1234abcd5678efgh",
        "permissions": [
          "read_projects",
          "write_tasks",
          "manage_users"
        ],
        "roles": [
          {
            "display_name": "Dev Team",
            "id": "role_79643236410327240",
            "name": "team_dev"
          }
        ]
      }
    ],
    "metadata": {
      "department": "engineering",
      "location": "nyc-office"
    },
    "user_profile": {
      "custom_attributes": {
        "department": "engineering",
        "security_clearance": "level2"
      },
      "email_verified": true,
      "external_identities": [
        {
          "connection_id": "conn_1234abcd5678efgh",
          "connection_type": "OAUTH",
          "connection_user_id": "ext_user_12345",
          "is_social": true
        }
      ],
      "family_name": "Doe",
      "gender": "male",
      "given_name": "John",
      "groups": [
        "admin",
        "developer"
      ],
      "id": "usr_profile_1234abcd5678efgh",
      "locale": "en-US",
      "metadata": {
        "department": "engineering",
        "employee_type": "full-time",
        "idp_user_id": "12345"
      },
      "name": "John Michael Doe",
      "phone_number": "+14155552671",
      "phone_number_verified": true,
      "picture": "https://example.com/avatar.jpg",
      "preferred_username": "johndoe"
    }
  }
}