LogMeIn Rescue API User Guide

createUsers

Creates a number of Rescue users in an existing group by reading and validating the details of the new users. For information about how to add individual users in the Rescue Administration Center, see Setting up Your Organization in the LogMeIn Rescue Administration Center User Guide.

Important: Only Master Administrators can use this API method. The maximum number of new users that can be created largely depends on the length of the optional parameters. For best results, it is not recommended to create more than 1000 users simultaneously - in one array.

Input Parameters

Element Description
USERDATA[] An array containing the parameters of the new users. These parameters are described in details below.
Note: You cannot add external technicians.
uniqueid The temporary ID of the new user. Required.
Note: Rescue automatically assigns a permanent node ID to each new user after the userdata array is validated.
parentid The ID of the parent group. Required.

Depending on what type of users you want to create, you must define the ID of their parent group:
  • To create Master Administrators, use the ID of the root-level category Master Administrators
  • To create Administrators, use the ID of an Administrator Group or the root-level category Administrators
  • To create Technicians, use the ID of a Technician Group. You cannot create users in the root-level category Technicians.
Note: If you want to add users to a new user group, first you must create that group as described in createGroup.
name The name of the user. Required.
Note: For special characters, use URL encoding.
nick The nickname of the user. Optional.
email The email address of the user. Required.
Note: You cannot use the email address of an existing Administrator or Master Administrator to create a Technician.
ssoid The Single Sign On ID of the user. Optional.
pwd The password of the user. Required.
confpwd The confirmation password. Required.
status The status of the user. Optional.
The possible values are as follows:
  • Enabled (default, if not specifically defined)
  • Disabled
description The description of the user. Optional.
addons Specifies whether the user has mobile addon. Required.
The possible values are as follows:
  • True
  • False
authcode The secret authentication code that is used to authenticate the user without logging in to Rescue. Optional.

Return Values

The return values contain the result of the user creation process itself in the state field and the details of creating the individual users in the other fields.

A user is created in Rescue if the creation process succeeds and a nodeID is created for the new user. If there is an error in the userStatus field, then the user is still created and you should update the details of the user to ensure that it is properly set up.

Displayed Return Value Description
state The status of processing the new users. Possible values are described below.
OK Adding all users in the provided list succeeded.
PARTIALLY_​PROCESSED Not all users were successfully created.
ERROR No users were created due to an unspecified error, such as timeout. The details of failure are listed in the userState field for the individual users.
NOTLOGGEDIN Adding users failed because the current user is no longer logged in.
INVALID_SECRETAUTHCODE The secret authentication code for the user is invalid.
USER_DELETED_OR_​DISABLED The administrator who tried to add users is deleted or disabled.
UNIQUE_ID_NOT_UNIQUE At least one of the specified user IDs (uniqueid) is already taken.
INVALIDPARAM_EMAIL_​ALREADY_IN_USE At least one of the specified email addresses is not unique.
SSO_ID_ALREADY_EXISTS The specified SSOID is already assigned to another newly created user.
UNKNOWN_ERROR Some or all users were not created due to an unspecified error.

The following information is returned about the individual users:

Displayed Return Value Description
nodeId The ID of the new user. If creating the user failed, then its nodeId is 0.
uniqueId The temporary ID of the new user that was used during the import process.
userState The status of processing a specific user. Possible values are described below.
OK Adding the user succeeded.
ERROR The user was not created due to an unspecified error, such as timeout.
INVALIDPARAM_​PARENTID The ID of the parent group is incorrect either because it does not exist or because it is an incorrect group type. For example, a technician can only be created in a Technician Group, but not in a channel.
ACCESS_DENIED You do not have permission to create users in the specified group.
INVALIDPARAM_PARENTID_​IS_ZERO_OR_LESS The specified parent group ID is zero or a negative number.
INVALIDPARAM_NAME The name is more than 128 characters long or the field is empty.
INVALIDPARAM_NICK The name is more than 128 characters long.
INVALIDPARAM_DESCRIPTION The description is more than 1024 characters long.
INVALIDPARAM_EMAIL The email address of the user has an incorrect format or it is more than 128 characters long.
INVALIDPARAM_EMAIL_​ALREADY_IN_USE The specified email address is already in use.
INVALIDPARAM_PASSWORD_​CANNOT_CONTAIN_ WHITESPACE_CHARACTERS One of the password fields contains an extra space.
INVALIDPARAM_PASSWORD_​HAS_TO_BE_AT_LEAST_ 8_CHARACTERS_LONG The new password must be at least 8 characters in length.
INVALIDPARAM_PASSWORD_​HAS_TO_CONTAIN_AT_ LEAST_TWO_UPPERCASE_LETTERS_​OR_SPECIAL_ CHARACTERS The new password must contain at least 2 characters that are either uppercase or special characters.
INVALIDPARAM_PASSWORD_​DOES_NOT_MEET_THE_ MINIMUM_PASSWORD_STRENGHT_​REQUIREMENTS The Password Strength meter must meet the pre-defined minimum requirements.
INVALIDPARAM_NEW_PASSWORDS_​DO_NOT_MATCH The new and the confirmation passwords do not match.
INVALIDPARAM_CURRENT_​PASSWORD_IS_WRONG The current password of the user is incorrect.
INVALIDPARAM_MISSING_​CONFIRMATION_PASSWORD The confirmation password field cannot be empty.
NOT_ENOUGH_SEAT_LICENSES_​AVAILABLE There are not enough standard or mobile licenses available.
NODE_CANNOT_BE_ENABLED_​BECAUSE_ITS_PARENT_ NODE_IS_DISABLED The status of the user cannot be set to enabled because the parent node is disabled.
USER_DELETED_OR_​DISABLED The administrator who tried to add users is deleted or disabled.
CREATED_BUT_NOTIFICATION_​EMAIL_NOT_SENT Notification email was not sent to the Administrator who created the users.
SSO_ID_ALREADY_EXISTS The specified SSOID is already taken by an existing Rescue user.
INVALIDPARAM_UNIQUEID_IS_​ZERO_OR_LESS The specified user ID is zero or a negative number.
INVALIDPARAM_PASSWORD_​MISSING One of the passwords is not defined.
INVALIDPARAM_EMAIL_​MISSING The email address of the user is not defined.

Sample Code

The following are examples for using the createUsers method that you can call in your environment.

SOAP

For sample SOAP 1.1 and SOAP 1.2 request and response messages, visit https://secure.logmeinrescue.com/api/API.asmx?op=createUsers.

C# with SOAP

The example values shown must be replaced with actual values.

using System;
using System.Collections.Generic;
using System.Linq;
using System.Web;
using System.Web.UI;
using System.Web.UI.WebControls;
using System.Net;
using System.IO;
using createUsers.APIServiceReference;

namespace Rescue.API
{
  public partial class Default : System.Web.UI.Page
  {
    protected void Page_Load(object sender, EventArgs e)
    {
      try
      {
        APIServiceReference.APISoapClient proxy = new APIServiceReference.
APISoapClient("APISoap12");  
        proxy.CookieContainer = new CookieContainer();

        string sEmail = "some@email.com";
        string sPwd = "secretPassword";
                
        string sAuthCode = string.Empty;

        APIServiceReference.requestAuthCodeRet authCodeRet = proxy.requestAuthCode(out 
sAuthCode, sEmail, sPwd);


        if (authCodeRet != APIServiceReference.requestAuthCodeRet.requestAuthCode_OK)
        {
        Response.Write("Auth code missing: " +  authCodeRet + "<br />");
        return;
        }

        int iParent = [ID of the parent node];

        int iUId = 0;

        APIServiceReference.USERDATA userDataFirst = new APIServiceReference.USERDATA
                {
                    iUniqueId = ++iUId,
                    iParentID = iParent,
                    sName = "John Doe",
                    sNick = "JDoe",
                    sEmail = "jdoe@company.com",
                    sSSOID = "123456",
                    sPwd = "secretPassword",
                    sConfPwd = "secretPassword",
                    eStatus = APIServiceReference.nodeStatus.Enabled,
                    sDescription = "Admin",
                    eAddOns = APIServiceReference.hasMobileAddon.False
                };


        APIServiceReference.USERDATA userDataSecond = new APIServiceReference.USERDATA
                {
                    iUniqueId = ++iUId,
                    iParentID = iParent,
                    sName = "Jane Doe",
                    sNick = "JaneDoe",
                    sEmail = "janedoe@company.com",
                    sSSOID = "654321",
                    sPwd = "secretPassword",
                    sConfPwd = "secretPassword",
                    eStatus = APIServiceReference.nodeStatus.Enabled,
                    sDescription = "Admin",
                    eAddOns = APIServiceReference.hasMobileAddon.False
                };


        APIServiceReference.CREATEUSERSINFO ret = sAPI.createUsers(new[] { userDataFirst,
 userDataSecond }, sAuthCode);

        Response.Write(ret.state.ToString());

        if (ret.createUserInfos.Length > 0)
        {
            Response.Write(ret.createUserInfos[0].userState + "<br />" + 
ret.createUserInfos[0].iNodeId);
        }
      }
      catch (Exception ex)
      {
        lblError.Text = ex.Message;
      }
    }
  }
}