Create User

Post
/api/v1/users.create

Create a new user in your workspace. This endpoint is typically used by admins to create user accounts in the workspace.
Permissions required:

  • create-user: Permission to create users
  • edit-other-user-active-status: Permission to enable or disable other accounts

Changelog

Version Description
0.48.0 role property is now roles which is an array of strings for the roles to create the user with.
0.45.0 Users created via this now join the default channels.
0.40.0 Added
Header parameters
X-User-Id
stringRequired

The authenticated user ID.

ExamplerbAXPnMktTFbNpwtJ
X-Auth-Token
stringRequired

The authenticated user token.

ExampleRScctEHSmLGZGywfIhWyRpyofhKOiMoUIpimhvheU3f
Body parameters
Expand All
object
name
string Required

The display name of the user.

ExampleTest User
email
string Required

The email address for the user.

Example[email protected]
password
string Required

The password for the user.

Exampleanypassyouwant
username
string Required

The username for the user.

Exampleuniqueusername1
active
boolean

Set the users' active status. If the user is deactivated, they can not login. By default, the user is active.

Defaulttrue
ExampleTrue
nickname
string

The nickname for the user.

Exampletestusername
bio
string

The bio for the user.

ExampleAll about the user
joinDefaultChannels
boolean

Select whether users should automatically join default channels once they are created. By default, it is set to true.

Defaulttrue
ExampleTrue
statusText
string

The status text of the user.

ExampleOn a vacation
roles
Array of string

The roles to be assigned to this user. If it is not specified, the user role is assigned by default. Note:

  • For default roles, the role name and ID are the same. For custom roles, the name and ID are different.
  • If you are setting a custom role for a user, make sure to enter the custom role ID, and not the role name. Refer to Roles for more information.
Example[ "bot" ]
string
Examplebot
requirePasswordChange
boolean

Should the user be required to change their password when they login? It is set to false by default

Defaultfalse
ExampleFalse
setRandomPassword
boolean

Should the user be assigned a random password once they are created? It is set to false by defualt.

Defaultfalse
ExampleFalse
sendWelcomeEmail
boolean

Should the user get a welcome email? It is set to true by default.

Defaultfalse
ExampleFalse
verified
boolean

Should the user's email address be verified when created? It is set to false by default.

Defaultfalse
ExampleFalse
customFields
object

A valid JSON object of key-value pairs consisting of additional fields to be added during user registration. By default, the value is undefined. To save custom fields, you must first define them in the workspace admin settings. For information on how to view the custom fields, see the Get Users List endpoint.

Example{ "clearance": "High", "team": "Queen" }
Responses
200

OK

Success Example
{
  "user": {
    "_id": "BsNr28znDkG8aeo7W",
    "createdAt": "2016-09-13T14:57:56.037Z",
    "services": {
      "password": {
        "bcrypt": "$2a$i7BFS55uFYRf5TE4ErSUH8HymMNAbpMAvsOcl2C"
      }
    },
    "username": "uniqueusername",
    "emails": [
      {
        "address": "[email protected]",
        "verified": false
      }
    ],
    "type": "user",
    "status": "offline",
    "active": true,
    "roles": [
      "user"
    ],
    "_updatedAt": "2016-09-13T14:57:56.175Z",
    "name": "name",
    "settings": {}
  },
  "success": true
}
Expand All
object
user
object
_id
string
createdAt
string
username
string
emails
Array of object
object
address
string
verified
boolean
type
string
roles
Array of string
string
status
string
active
boolean
_updatedAt
string
bio
string
name
string
nickname
string
requirePasswordChange
boolean
settings
object
success
boolean
400

Bad Request

Permission Error
{
  "success": false,
  "error": "Adding user is not allowed [error-action-not-allowed]",
  "errorType": "error-action-not-allowed",
  "details": {
    "method": "insertOrUpdateUser",
    "action": "Adding_user"
  }
}
Expand All
object
success
boolean
error
string
errorType
string
details
object
method
string
action
string
401

Unauthorized

Authorization Error
{
  "status": "error",
  "message": "You must be logged in to do this."
}
object
status
string
message
string