Links

Add Users

Adds user data to the import staging area. It requires the current import operation state to be either new or ready. If successful, it changes the operation state to ready .
It requires the run-import permission.
URL
Requires Auth
HTTP Method
/api/v1/import.addUsers
yes
POST

Headers

Argument
Example
Required
Description
X-User-Id
myuser-name
Required
The authenticated user ID.
X-Auth-Token
myauth-token
Required
Auth token.

Payload

Argument
Required
Description
users
yes
An array of user objects.

User Object

Attribute
Type
Required
Example
Description
username
String
Optional
"john.doe"
The user's username.
emails
String Array
Required
The user's email addresses.
importIds
String Array
Required
["1523"]
A list of IDs that can identify the user.
name
String
Optional
"John Doe"
The user's display name.
utcOffset
Number
Optional
-3
The user's timezone, in number of hours relative to UTC.
roles
String Array
Optional
["user"]
A list of roles to assign to the user
type
String
Optional
"user"
The user type, must be either "user" or "bot".
bio
String
Optional
The user's profile bio.
password
String
Optional
"P@ssw0rd"
A password to assign to this user.
deleted
Boolean
Optional
false
Was the user deleted from the previous system?
avatarUrl
String
Optional
A URL pointing to the user's avatar picture.

Example Payload

{
"users": [
{
"username": "john.doe",
"emails": [
],
"importIds": [
"1523"
],
"name": "John Doe",
"password": "P@ssw0rd"
},
{
"username": "jane.doe",
"emails": [
],
"importIds": [
"1524"
],
"name": "Jane Doe"
}
]
}

Example Call

curl --location 'http://localhost:3000/api/v1/import.addUsers' \
--header 'x-auth-token: QizJozLOnWMi_2vWaLHhjfd-XYKT6XM40lTZ3zg1UMd' \
--header 'x-user-id: rbAXPnMktTFbNpwtJ' \
--header 'Content-Type: application/json' \
--data-raw '{
"users": [
{
"username": "john.doe",
"emails": [
],
"importIds": [
"1523"
],
"name": "John Doe",
"password": "P@ssw0rd"
},
{
"username": "jane.doe",
"emails": [
],
"importIds": [
"1524"
],
"name": "Jane Doe"
}
]
}'
Here are some key points to note:
  1. 1.
    A minimum of one email address and one Import Id is required. If any user is missing those, the endpoint will fail and no user will be added to the operation.
  2. 2.
    Emails and usernames will not be validated, but they must be unique or the user creation will fail.
  3. 3.
    If roles are added, they must be valid Rocket.Chat roles, or the endpoint will fail and no user will be added to the operation.
  4. 4.
    The default roles will be added to all users automatically.
  5. 5.
    If no password is added, a temporary random password will be generated automatically.
  6. 6.
    Users flagged as deleted will be created as Deactivated on Rocket.Chat.
  7. 7.
    Avatar URLs will not be fetched automatically. The workspace administrator uses the "Download Pending Avatars" button in Administration > Workspace > Import on the workspace after the import is completed.
  8. 8.
    Import Ids will not be used as Ids by Rocket.Chat, but you can query users by their import id with the users.info endpoint.

Example Result

Success

{
"success": true
}

Error

  • No Permission: This occurs when the authenticated user doesn't have the run-import permission.
  • Initialize Import: This occurs when there is no current import operation. See New Import to create a new import operation.
No Permission
Initialize Import
{
"success": false,
"error": "User does not have the permissions required for this action [error-unauthorized]"
}
{
"success": false,
"error": "Import operation not initialized."
}

Change Log

Version
Description
6.3.0
Added
Last modified 6mo ago
Rocket.Chat versions receive support for six months after release.