create-user.md

Create User

Create a new workspace user.

HTTP Method	URL	Requires Auth
POST	/api/v1/users.create	yes

{% hint style="info" %} Permission required: create-user {% endhint %}

Body Parameters

Key	Example Value	Description
email*	example@example.com	The email address for the user.
name*	Example User	The display name of the user.
password*	pass@w0rd	The password for the user.
username*	example	The username for the user.
active	false	Whether the user is active, which determines if they can login or not. By default, the value is true.
bio	Enginer|GitHub Star	The bio of the user.
nickname	lola	The nickname of the user.
statusText	On a vacation	The status text of the user.
roles	["moderator", "user", "653fb63ba2f73c7460e18e90"]	The roles the user is assigned on creation. The default value is user. 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.
joinDefaultChannels	false	Whether the user should join the default channels when created. The default value is true.
requirePasswordChange	true	Whether the user be required to change their password when they login. The default value is false.
setRandomPassword	true	Set random password for the user and send by email. If setRandomPassword is set to true, the password field can be left empty.
sendWelcomeEmail	true	Whether the user get a welcome email. The default value is false.
verified	true	Whether the user's email address be verified when created. The default value is false.
customFields	{ twitter: '@example' }	Any custom fields the user should have on their account. The default value is undefined.

{% hint style="info" %}

• To save customFields you must first define the custom fields in the admin panel (Administration > Settings > Accounts > Registration > Custom Fields). For details on how to configure this field, see Custom Fields.
• For information on how to view the custom fields, see the Get Users List endpoint. {% endhint %}

Example Call

{% code overflow="wrap" %}

curl -H "X-Auth-Token: 9HqLlyZOugoStsXCUfD_0YdwnNnunAJF8V47U3QHXSq" \
     -H "X-User-Id: aobEdbYhXfu5hkeqG" \
     -H "Content-type:application/json" \
     http://localhost:3000/api/v1/users.create \
     -d '{
          "name": "name", 
          "email": "email@user.tld", 
          "password": "anypassyouwant", 
          "username": "uniqueusername", 
          "roles":["bot","user"]}'

{% endcode %}

Example Response

{
   "user": {
      "_id": "BsNr28znDkG8aeo7W",
      "createdAt": "2016-09-13T14:57:56.037Z",
      "services": {
         "password": {
            "bcrypt": "$2a$i7BFS55uFYRf5TE4ErSUH8HymMNAbpMAvsOcl2C"
         }
      },
      "username": "uniqueusername",
      "emails": [
         {
            "address": "email@user.tld",
            "verified": false
         }
      ],
      "type": "user",
      "status": "offline",
      "active": true,
      "roles": [
         "user"
      ],
      "_updatedAt": "2016-09-13T14:57:56.175Z",
      "name": "name",
      "settings": {}
   },
   "success": true
}

Change Log

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