AVAILABLE WITH BUSINESS SUBSCRIPTION

Method: addUser

Permissions to Run the Request

Account Owner, Account Administrators, Department Administrators, or custom roles

Department Administrators and users with a custom role can add users only to the departments they manage and their sub-departments.

Request Parameters

Parameter

Type

Description

token (required)stringAccess token. You can obtain a token by making a request.
email (optional)stringEmail of the new user.
login (required)stringLogin of the new user.
password (optional)stringThe password of the new user. 
departmentId (required)stringDepartment ID the user will be added to.
sendLoginEmail (optional, default: false)boolA parameter that determines whether an email is sent to the added user.
invitationMessage (optional, required if the sendLoginEmail parameter is set to true)stringThe text of the email invitation message that is sent to the added user.
sendLoginSMS (optional, default: false)boolThe parameter that determines whether an SMS is sent to the added user.
invitationSMSMessage (optional, required if the sendLoginSMS parameter is set to true)stringThe text of the SMS that is sent to the added user.
role (optional)string

If you assign one of the standard roles to the user (except for Account Owner and Publisher), use one of the following values for the role parameter:

  • learner
  • department_administrator
  • administrator

If you assign the Publisher role or one of the custom roles to the users, use the custom value for the role parameter. 

Learn more about using the role parameter in the Important section.

roleId (required if the custom value is used for the role parameter)stringThe roleId parameter is used, if you assign or the Publisher role or one of the custom roles to the user. In this case, you will need to use the needed role ID for the roleId parameter.

Learn more about using the roleId parameter in the Important section.

manageableDepartmentIds (required if the user's role is Department Administrator, Publisher, or a custom role)

string[]

An array with the IDs of the departments the user will manage.

groups (optional)string[]An array with the IDs of the groups the user will be added to.
roles  (optional)string[]An array of data using which you can assign one or two roles to a user. You will need to use the needed role ID for the roleId parameter inside the array.

If you assign two roles, one of them will be Learner, and the second role — one of the administrative roles (Account Administrator, Department Administrator, Publisher, or a custom role).

Learn more about using the roles parameter in the Important section.

Return Value

After the request has been completed, the system returns an object with the following properties:

Parameter

Type

Description

userIdstringThe ID of the added user.

Important Info

  1. If in the account there are required user profile fields (apart from the fields of the 'Country' format), they should be also put into the request.

  2. The user role can be assigned in one of two ways:

    1. Using the role (if the assigned role is Account Administrator, Department Administrator, or Learner) and roleId (if the role is Publisher or a custom role) tags,

    2. Using the roles array of data.

  3. If you use the roles array of data to assign a user role, you will be able to select two roles at once. 

    One of the roles will be Learner and the second role will be one of the administrative roles (Account Administrator, Department Administrator, Publisher, or a custom role).

    If you add two administrative role to the roles array of data, the user won't be added.

  4. If you have assigned a user role both with the role/roleId tags and the roles array of data, the user will be assigned to a role or roles specified in the roles array of data and the value specified in the role/roleId tags will be then ignored.

  5. If you haven't specified the user role with the role/roleId tags or with the roles array of data, the user will be assigned to the Learner role.

Possible Errors

Error

Description

User with the same email is already registered.A user with the specified e-mail address already exists.
User with the same login is already registered.A user with the specified e-mail address already exists.
Number of user accounts is exceededA user hasn't been added because the number of user accounts supported by your subscription plan has been exceeded.
Permission DeniedAn authorized user does not have enough permissions to handle the operation. For example, Department Administrator can't add users to a department they don't manage.
Wrong parametersSome of the sent parameters are incorrect.

Sample Request

<?xml version="1.0" encoding="utf-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="https://schemas.xmlsoap.org/soap/envelope/"
                   xmlns="https://ispringlearn.com/go/services/api/soap">
  <SOAP-ENV:Body>
    <AddUserRequest>
      <credentials>          \
        <token>p-1sJDjmULL5DdpXPJTcbm4jVIaWVHvNmrjAxATRbNE</token>
      </credentials>
      <password>password</password>
      <sendLoginEmail>true</sendLoginEmail>
      <invitationMessage>Please use the following credentials to sign up at iSpring Academy:
      </invitationMessage>
      <sendLoginSMS>true</sendLoginSMS>
      <invitationSMSMessage>Please use the following credentials to sign up at iSpring Academy:
      </invitationSMSMessage>
      <departmentId>8bcda39e-a993-11e9-b267-7ee902e2417c</departmentId>
      <role>custom</role>
      <roleId>209b9312-afb3-11e9-aaf2-dabe560e07b1</roleId>
      <fields>
        <field>
          <name>login</name>
          <value>kate.smith@ispringsolutions.com</value>
        </field>
      </fields>
      <groups>
        <id>string</id>
        <id>string</id>
      </groups>
      <manageableDepartmentIds>
       <id>string</id>
       <id>string</id>
      </manageableDepartmentIds>
    </AddUserRequest>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>
XML

Sample Response

<?xml version="1.0" encoding="utf-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="https://schemas.xmlsoap.org/soap/envelope/"
                   xmlns="https://ispringlearn.com/go/services/api/soap">
  <SOAP-ENV:Body>
    <AddUserResult>
      <userId>d6d3579a-f695-11e9-89d0-6ea588b9ace6<userId>
    </AddUserResult>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>
XML