> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wisdom.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Users

The `createUsers` mutation provisions one or more users in a workspace. Call this before impersonating a user in the embedded flow — a user must exist before they can be impersonated.

## Signature

```graphql theme={null}
createUsers(input: CreateUsersInput!): CreateUsersResponse!
```

## Arguments

<ParamField path="input" type="CreateUsersInput!" required>
  Input object containing the details for the users to create.
</ParamField>

### CreateUsersInput fields

<ParamField path="emails" type="[String!]!" required>
  One or more email addresses to provision. User matching is email-based — each email must be unique within the workspace.

  <Note>
    If your embedded users may share email addresses across tenants (e.g., the same person is a customer of multiple clients), append a unique identifier to the email prefix: `alice+tenant123@yourcompany.com`. This prevents cross-tenant session collisions.
  </Note>
</ParamField>

<ParamField path="workspaceID" type="ID">
  The workspace to create the users in. Required for multi-workspace deployments.
</ParamField>

<ParamField path="roleAssignments" type="[RoleAssignmentInput!]">
  Role assignments for the new users. Each entry specifies a `roleId` and `scopes` (`RoleAssignmentInput`).

  For embedded dashboards, assign the Viewer role to hide edit controls:

  ```json theme={null}
  [{ "roleId": "00000000-0000-0000-0000-000000000003", "scopes": ["{{DOMAIN_ID}}"] }]
  ```
</ParamField>

<ParamField path="sendWelcomeEmail" type="Boolean">
  Whether to send a welcome email to the new users. Default: `false`. Set to `false` for programmatically provisioned embedded users.
</ParamField>

<ParamField path="userAttributes" type="[UserAttributeInput!]">
  Key-value pairs for parameterized connections and row-level data access. These are stored as DATABASE-sourced attributes. See [User attributes](/integrations/user-management/user-attributes).
</ParamField>

<ParamField path="userGroupIds" type="[ID!]">
  Optional group IDs to assign the users to on creation.
</ParamField>

<Note>
  `CreateUsersInput` does not include a display name field. Users provisioned via this mutation appear as their email address in the WisdomAI admin screen. If a display name is needed, pass it as a `userAttributes` entry (for example, `{ "key": "display_name", "value": "Alice Smith" }`).
</Note>

## Response

<ParamField path="status" type="ResponseStatus!">
  Indicates whether the operation succeeded. See [ResponseStatus](/integrations/graphql-api/objects/response-status).

  <Info>
    The `status` field here returns a `ResponseStatus` object (with `code` and `message`). This is distinct from the `UserStatus` enum (e.g., `ACTIVE`) found on the `User` object.
  </Info>
</ParamField>

## Usage example

```graphql theme={null}
mutation CreateUsers($input: CreateUsersInput!) {
  createUsers(input: $input) {
    status {
      code
      message
    }
  }
}
```

<RequestExample>
  ```bash Single user theme={null}
  curl -s -X POST \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer <access_token>" \
    -d '{
      "query": "mutation CreateUsers($input: CreateUsersInput!) { createUsers(input: $input) { status { code message } } }",
      "variables": {
        "input": {
          "emails": ["alice@yourcompany.com"],
          "workspaceID": "workspace_123",
          "roleAssignments": [{ "roleId": "00000000-0000-0000-0000-000000000003", "scopes": ["{{DOMAIN_ID}}"] }],
          "sendWelcomeEmail": false
        }
      }
    }' \
    https://{ACCOUNT}.askwisdom.ai/graphql
  ```

  ```bash Multiple users theme={null}
  curl -s -X POST \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer <access_token>" \
    -d '{
      "query": "mutation CreateUsers($input: CreateUsersInput!) { createUsers(input: $input) { status { code message } } }",
      "variables": {
        "input": {
          "emails": ["alice@yourcompany.com", "bob@yourcompany.com"],
          "workspaceID": "workspace_123",
          "roleAssignments": [{ "roleId": "00000000-0000-0000-0000-000000000003", "scopes": ["{{DOMAIN_ID}}"] }],
          "sendWelcomeEmail": false
        }
      }
    }' \
    https://{ACCOUNT}.askwisdom.ai/graphql
  ```

  ```bash With user attributes theme={null}
  curl -s -X POST \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer <access_token>" \
    -d '{
      "query": "mutation CreateUsers($input: CreateUsersInput!) { createUsers(input: $input) { status { code message } } }",
      "variables": {
        "input": {
          "emails": ["alice@yourcompany.com"],
          "workspaceID": "workspace_123",
          "roleAssignments": [{ "roleId": "00000000-0000-0000-0000-000000000003", "scopes": ["{{DOMAIN_ID}}"] }],
          "sendWelcomeEmail": false,
          "userAttributes": [
            { "key": "account_id", "value": "acct_456" },
            { "key": "region", "value": "us-east" }
          ]
        }
      }
    }' \
    https://{ACCOUNT}.askwisdom.ai/graphql
  ```
</RequestExample>

<ResponseExample>
  ```json Success theme={null}
  {
    "data": {
      "createUsers": {
        "status": {
          "code": "OK",
          "message": "Users created successfully"
        }
      }
    }
  }
  ```
</ResponseExample>

<Warning>
  If a user with the same email already exists, the call succeeds but re-applies the role assignments you pass in, overwriting any manually assigned roles. To avoid resetting roles on existing users, check [`listUsers`](/integrations/graphql-api/queries/user/list-users) first and skip `createUsers` for users already provisioned.
</Warning>

## Related articles

<CardGroup cols={2}>
  <Card title="Set user attributes" icon="tag" href="/integrations/graphql-api/mutations/user/set-user-attributes">
    Update attributes on existing users
  </Card>

  <Card title="Impersonate user" icon="user-secret" href="/integrations/graphql-api/mutations/auth/impersonate-user">
    Generate a session JWT for the created user
  </Card>

  <Card title="User attributes" icon="list" href="/integrations/user-management/user-attributes">
    How attributes control data access
  </Card>

  <Card title="Embedding overview" icon="code" href="/integrations/embeddings/embedding">
    Full server-side embedding flow
  </Card>
</CardGroup>