---
title: "API: createGroup"
slug: "api-creategroup"
tags: ["home groups", "variants", "permissions"]
updated: 2023-04-27T16:53:26Z
published: 2023-04-27T16:53:26Z
canonical: "support.smarteru.com/api-creategroup"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://support.smarteru.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API: createGroup

- SmarterU requires all API calls to POST to HTTPS. Any POST to HTTP will result in the SU:01 error (i.e., No POST data detected.).
- If you are viewing the help in a language other than English, please change your language to English before copying and pasting any code. All API attributes and functions are in English.
- Tags are required unless specified.

## **Description**

The createGroup method [adds a group](/v1/docs/adding-a-group) and assigns [users](/v1/docs/group-users), [courses](/v1/docs/group-courses) and [subscription variants](/v1/docs/group-subscriptions) to it.

## **Who Has Access**

The following users have access to the createGroup method:

- Users with the [Group Manager](/v1/docs/group-permission-group-manager-gm), [Manage Group Courses](/v1/docs/group-permission-manage-group-courses-mgc), or [Manage Group Users](/v1/docs/group-permission-manage-group-users-mgu) group permission.
- Users with the [Create New Group](/v1/docs/account-permission-create-new-group) account permission.
- [Administrators and owners](/v1/docs/user-profile-information#access-level).

## **API Call XML Package**

```markup
<SmarterU>
   <AccountAPI><![CDATA[]]></AccountAPI>
   <UserAPI><![CDATA[]]></UserAPI>
   <Method>createGroup</Method>
   <Parameters>
      <Group>
         <Name><![CDATA[]]></Name>
         <GroupID><![CDATA[]]></GroupID>
         <Status><![CDATA[]]></Status>
         <Description><![CDATA[]]></Description>
         <HomeGroupMessage><![CDATA[]]></HomeGroupMessage>

         <NotificationEmails>
            <NotificationEmail><![CDATA[]]></NotificationEmail>
         </NotificationEmails>

        <UserHelpOverrideDefault><![CDATA[]]></UserHelpOverrideDefault>
        <UserHelpEnabled><![CDATA[]]></UserHelpEnabled>
        <UserHelpEmail><![CDATA[]]></UserHelpEmail>
        <UserHelpText><![CDATA[]]></UserHelpText>

         <Tags2>
            <Tag2>
               <TagID><![CDATA[]]></TagID>
                  - OR -
               <TagName><![CDATA[]]></TagName>

               <TagValues><![CDATA[]]></TagValues>
            </Tag2>
         </Tags2>
       
         <UserLimit>
            <Enabled><![CDATA[]]></Enabled>
            <Amount><![CDATA[]]></Amount>
         </UserLimit>

         <Users>
            <User>
               <Email><![CDATA[]]></Email>
                  - OR -
               <EmployeeID><![CDATA[]]></EmployeeID>
               <HomeGroup><![CDATA[]]></HomeGroup>
               <Permissions>
                  <Permission>
                     <Code><![CDATA[]]></Code>
                  </Permission>
               </Permissions>
            </User>
         </Users>

         <LearningModules>
            <LearningModule>
               <ID><![CDATA[]]></ID>
               <AllowSelfEnroll><![CDATA[]]></AllowSelfEnroll>
               <AutoEnroll><![CDATA[]]></AutoEnroll>
            </LearningModule>
         </LearningModules>

         <SubscriptionVariants>
            <SubscriptionVariant>
               <ID><![CDATA[]]></ID>
               <RequiresCredits><![CDATA[]]></AllowSelfEnroll>
            </SubscriptionVariant>
         </SubscriptionVariants>

         <DashboardSetID><![CDATA[]]></DashboardSetID>

      </Group>
   </Parameters>
</SmarterU>
```

## Group Tag Group

The Group tag group is a container for the group's details.

```markup
<Group>
   <Name><![CDATA[]]></Name>
   <GroupID><![CDATA[]]></GroupID>
   <Status><![CDATA[]]></Status>
   <Description><![CDATA[]]></Description>
   <HomeGroupMessage><![CDATA[]]></HomeGroupMessage>

   <NotificationEmails>
      <NotificationEmail><![CDATA[]]></NotificationEmail>
   </NotificationEmails>

   <UserHelpOverrideDefault><![CDATA[]]></UserHelpOverrideDefault>
   <UserHelpEnabled><![CDATA[]]></UserHelpEnabled>
   <UserHelpEmail><![CDATA[]]></UserHelpEmail>
   <UserHelpText><![CDATA[]]></UserHelpText>

   <Tags2>
      <Tag2>
         <TagID><![CDATA[]]></TagID>
            - OR -
         <TagName><![CDATA[]]></TagName>
         <TagValues><![CDATA[]]></TagValues>
      </Tag2>
   </Tags2>
       
   <UserLimit>
      <Enabled><![CDATA[]]></Enabled>
      <Amount><![CDATA[]]></Amount>
   </UserLimit>

   <Users>
      <User>
         <Email><![CDATA[]]></Email>
            - OR -
         <EmployeeID><![CDATA[]]></EmployeeID>
         <HomeGroup><![CDATA[]]></HomeGroup>
         <Permissions>
            <Permission>
               <Code><![CDATA[]]></Code>
            </Permission>
         </Permissions>
      </User>
   </Users>

   <LearningModules>
      <LearningModule>
         <ID><![CDATA[]]></ID>
         <AllowSelfEnroll><![CDATA[]]></AllowSelfEnroll>
         <AutoEnroll><![CDATA[]]></AutoEnroll>
      </LearningModule>
   </LearningModules>

   <SubscriptionVariants>
      <SubscriptionVariant>
         <ID><![CDATA[]]></ID>
         <RequiresCredits><![CDATA[]]></AllowSelfEnroll>
      </SubscriptionVariant>
   </SubscriptionVariants>

   <DashboardSetID><![CDATA[]]></DashboardSetID>

</Group>
```

The Group tag may contain the following.

### Name

The [group's name](/v1/docs/group-group-information#name). Group names are unique for your SmarterU account.

### GroupID (optional)

The [group's unique, user-specified identifier](/v1/docs/group-group-information#group-id).

### Status

The [group's status](/v1/docs/group-group-information#status). Acceptable values are *Active* or *Inactive*.

### Description

The [group's description](/v1/docs/group-group-information#description).

### HomeGroupMessage

The [message](https://support.smarteru.com/v1/docs/group-home-group-message) displayed on the learner interface for learner who have the group set as their [home group](https://support.smarteru.com/v1/docs/home-groups).

### NotificationEmails

A container for the email addresses that the following emails will be sent to:

- [Certification Completion to Home Group Contact](/v1/docs/system-email-templates-certification-emails#certification-completion-to-home-group-contact)
- [Course Completion to Group Contact](/v1/docs/system-email-templates-course-emails-general#course-completion-to-group-contact)
- [Task Completion to Group Contact](/v1/docs/system-email-templates-course-emails-online-and-scorm#task-completion-to-group-contact)

This tag contains the following.

| Tag | Description |
| --- | --- |
| **NotificationEmail** | The [user's email address](https://support.smarteru.com/v1/docs/user-login-information#primary-email-required-if-employee-id-not-specified). Each email address should be contained in its own NotificationEmail tag. |

### UserHelpOverrideDefault (optional)

Indicates whether the [account's Enable User Help setting](/v1/docs/account-settings#enable-user-help) is overridden by the group. Acceptable values are:

- *1* - The account's Enable User Help setting is overridden by the group.
- *0* - The account's Enable User Help setting is not overridden by the group.

### UserHelpEnabled (optional)

Indicates whether a [link displays in the header of the learner interface](/v1/docs/group-group-information#enable-user-help) that enables users who have the group as their home group to request help. Acceptable values are:

- *1* - A link to request help displays in the learner interface's header.
- *0* - A link to request help doesn't display in the learner interface's header.

### UserHelpEmail (optional)

The [email addresses to which help requests will be sent](/v1/docs/group-group-information#user-help-email). To specify multiple email addresses, separate each with a comma. If no email address is specified, the help requests will be sent to all administrators.

If an administrator requests help, their request will be sent to our [Success Desk](mailto:success@neovation.com).

### UserHelpText (optional)

The [help link text displayed](/v1/docs/group-group-information#user-help-text) in the learner interface's header.

### Tags2 (optional)

A container for assigning tags to the group. Refer to [Tags2 Tag Group](/v1/docs/api-creategroup#tags2-tag-group-optional).

### **UserLimit** (optional)

Indicates whether there's a [limit on how many users can be added to the group](/v1/docs/group-users#adding-users-to-a-new-group) and what the maximum number is. The tag may contain the following.

| Tag | Description |
| --- | --- |
| **Enabled** | Indicates whether there's a limit on how many users can be added to the group. Acceptable values are: - *1* - There's a limit on how many users can be added to the group. - *0* - There's no limit on how many users can be added to the group. |
| **Amount** | The maximum number of users that can be added to the group. |

### Users

A container for assigning users to the group. Refer to [Users Tag Group](/v1/docs/api-creategroup#users-tag-group).

### LearningModules

A container for assigning courses to the group. Refer to [LearningModules Tag Group](/v1/docs/api-creategroup#learningmodules-tag-group).

### SubscriptionVariants (optional)

A container for assigning subscription variants to the group. Refer to [SubscriptionVariants Tag Group](/v1/docs/api-creategroup#subscriptionvariants-tag-group-optional).

### DashboardSetID (optional)

The dashboard set's system-generated identifier. If no value is provided, the [account's default dashboard set](/v1/docs/dashboard-set-scope-of-availability) is assigned to the group.

To obtain a dashboard set's identifier:

1. Navigate to the [Learner Dashboard Builder](https://support.smarteru.com/docs/learner-dashboard-builder).
2. Hover over the dashboard set's name. The dashboard set's ID displays at the bottom of the browser window.

![](https://cdn.document360.io/7efaadab-fef6-4186-806a-2ca14c9ce9ea/Images/Documentation/Dashboard%20Set%20ID%2020211115.png)

## **Tags2 Tag Group (optional)**

The Tags2 tag group is a container for the [group's tags](/v1/docs/group-tags).

```markup
<Tags2>
   <Tag2>
      <TagID><![CDATA[]]></TagID>
         - OR -
      <TagName><![CDATA[]]></TagName> 
      <TagValues><![CDATA[]]></TagValues>
   </Tag2>
</Tags2>
```

Each tag is contained in a Tag2 tag and contains the following.

### TagID

The tag's system-generated identifier. This tag is mutually exclusive with the [](https://help.smarteru.com/api-creategroup$tags2_TagName)[TagName tag](/v1/docs/api-creategroup#tagname).

To obtain a tag's ID:

1. Navigate to the [Tag Management Dashboard](https://support.smarteru.com/docs/tag-management-dashboard).
2. Right click on a tag.
3. Click **Inspect** (or Inspect Element, in some browsers). This displays the Developer Tools in your browser. The tag's ID will be located within the code.

![](https://cdn.document360.io/7efaadab-fef6-4186-806a-2ca14c9ce9ea/Images/Documentation/Tag%20ID%2020211115.png)

If you do not see the code, you may need to view a different tab within your Developer Tools.

### TagName

The [tag's name](/v1/docs/tag-main#name). This tag is mutually exclusive with the [](https://help.smarteru.com/api-creategroup$tags2_TagId)[TagID tag](/v1/docs/api-creategroup#tagid).

### **TagValues**

A comma-separated list of [values for the tag](https://support.smarteru.com/v1/docs/tag-pre-defined-values). The allowed values are controlled by the tag's settings.

## Users Tag Group

The Users tag group is a container for the [group's users](/v1/docs/group-users).

The Users tag group is required even if doesn't contain any tags.

```markup
<Users>
   <User>
      <Email><![CDATA[]]></Email>
         - OR -
      <EmployeeID><![CDATA[]]></EmployeeID>
      <HomeGroup><![CDATA[]]></HomeGroup>
      <Permissions>
         <Permission>
            <Code><![CDATA[]]></Code>
         </Permission>
      </Permissions>
   </User>
</Users>
```

If no tags are added to the Users tag, no users will be assigned to the group.

```markup
<Users></Users>
```

Each user is contained in a User tag and contains the following.

### Email

The [user's email address](/v1/docs/user-login-information#primary-email-required-if-employee-id-not-specified). This tag is mutually exclusive with the [EmployeeID tag](/v1/docs/api-creategroup#employeeid). This is the Email returned by the [getUser](https://help.smarteru.com/api-getuser$api_response_xml_package) and [listUsers](https://help.smarteru.com/api-listusers$api_response_xml_package) methods.

### EmployeeID

The [user's employee ID](/v1/docs/user-login-information#employee-id-required-if-primary-email-not-specified). This tag is mutually exclusive with the [Email tag](/v1/docs/api-creategroup#email). This is the EmployeeID returned by the [getUser](/v1/docs/api-getuser) and [listUsers](/v1/docs/api-listusers) methods.

### HomeGroup

Indicates if this is the user's [home group](/v1/docs/home-groups). Acceptable values are:

- *1* - The group is the user's home group.
- *0* - The group isn't the user's home group.

### Permissions

A container for the user's [group permissions](/v1/docs/group-permissions-1).

```markup
<Permissions>
   <Permission>
      <Code><![CDATA[]]></Code>
   </Permission>
</Permissions>
```

If no tags are added to the Permissions tag, no group permissions will be granted to the user, but they will be assigned to the group.

```markup
<Permissions></Permissions>
```

Each permission is contained in a Permission tag and contains the following.

| Tag | Description |
| --- | --- |
| **Code** | The permission to grant the user. Acceptable values are: - *Manage_Group* - Assigns the [Group Manager](/v1/docs/group-permission-group-manager-gm) group permission. - *Create_Course* - Assigns the [Create Course](/v1/docs/group-permission-create-course-cc) group permission. - *Manage_Group_Courses* - Assigns the [Manage Group Courses](/v1/docs/group-permission-manage-group-courses-mgc) group permission. - *Manage_Users* - Assigns the [Manage Users](/v1/docs/group-permission-manage-users-mu) group permission. - *Manage_Group_Users* - Assigns the [Manage Group Users](/v1/docs/group-permission-manage-group-users-mgu) group permission. - *View_Learner_Results* - Assigns the [View Learner Results](/v1/docs/group-permission-view-learner-results-vlr) group permission. - *Proctor* - Assigns the [Quiz Proctor](/v1/docs/group-permission-quiz-proctor-qp) group permission. - *Marker* - Assigns the [Long Answer Quiz Marker](/v1/docs/group-permission-long-answer-quiz-marker-laqm) group permission. - *Instructor* - Assigns the [Instructor-Led Training Instructor](/v1/docs/group-permission-instructor-led-training-instructor-ilti) group permission. For example, the following grants the user the Manage Users and Quiz Proctor permissions on the group. ```markup <Permissions> <Permission> <Code>MANAGE_USERS</Code> </Permission> <Permission> <Code>PROCTOR</Code> </Permission> </Permissions> ``` |

## LearningModules Tag Group

The LearningModules tag group is container for the [group's courses](/v1/docs/group-courses).

The LearningModules tag group is required even if doesn't contain any tags.

```markup
<LearningModules>
   <LearningModule>
      <ID><![CDATA[]]></ID>
      <AllowSelfEnroll><![CDATA[]]></AllowSelfEnroll>
      <AutoEnroll><![CDATA[]]></AutoEnroll>
   </LearningModule>
</LearningModules>
```

If no tags are added to the LearningModules tag, no courses will be assigned to the group.

```markup
<LearningModules></LearningModules>
```

Each course is contained in a LearningModule tag and contains the following.

### ID

The course's system-generated identifier. This is the LearningModuleID returned by [listLearningModules](/v1/docs/api-listlearningmodules), and the ID returned by [getLearnerReport](/v1/docs/api-getlearnerreport).

### AllowSelfEnroll

Indicates whether the group's users can [self-enroll](/v1/docs/group-courses#self) in the course. Acceptable values are:

- *1* - Group users can self-enroll in the course.
- *0* - Group users cannot self-enroll in the course.

### AutoEnroll

Indicates whether the group's user will be [automatically re-enrolled](/v1/docs/group-courses#automation) in the course. Acceptable values are:

- *1* - Group users will be automatically re-enrolled in the course.
- *0* - Users will not be automatically re-enrolled in the course.

## SubscriptionVariants Tag Group (optional)

The SubscriptionVariants tag group is a container for the [group's subscription variants](/v1/docs/group-subscriptions).

```markup
<SubscriptionVariants>
   <SubscriptionVariant>
      <ID><![CDATA[]]></ID>
      <RequiresCredits><![CDATA[]]></AllowSelfEnroll>
   </SubscriptionVariant>
</SubscriptionVariants>
```

If no tags are added to the SubscriptionVariants tag, no variants will be assigned to the group.

```markup
<SubscriptionVariants></SubscriptionVariants>
```

Each variant is contained in a SubscriptionVariant tag and contains the following.

### ID

The subscription variant's system-generated identifier. This is the VariantID returned by the [listVariants](https://help.smarteru.com/api-listvariants$top_of_page) method.

### RequiresCredits

Indicates whether enrollments in the subscription [require credits](/v1/docs/group-subscriptions). Acceptable values are:

- *1* - Subscription enrollments require credits.
- *0* - Subscription enrollments don't require credits.

## API Response XML Package

The [API response XML package](/v1/docs/api-response-xml-package) will always include a Result, Info, and [Errors](/v1/docs/api-creategroup#error-codes) tag.

```markup
<SmarterU>
   <Result></Result>
   <Info>
      <Group><![CDATA[]]></Group>
      <GroupID><![CDATA[]]></GroupID>
   </Info>

   <Errors>
      <Error>
         <ErrorID></ErrorID>
         <ErrorMessage></ErrorMessage>
      </Error>
   </Errors>
</SmarterU>
```

The response may also contain the following.

### **Group**

The [group's name](https://support.smarteru.com/v1/docs/group-group-information#name).

### **GroupID**

The [group's user-specified identifier](https://support.smarteru.com/v1/docs/group-group-information#group-id).

### Example API Response XML Package

Below is an example of an API response XML package.

```markup
<SmarterU>
   <Result>Success</Result>
   <Info>
      <Group><![CDATA[Fina Partners]]></Group>
      <GroupID><![CDATA[G-432]]></GroupID>
   </Info>

   <Errors>
   </Errors>
</SmarterU>
```

## **Error Codes**

| Error Code | Message |
| --- | --- |
| CG:01 | The name provided is not valid. |
| CG:02 | The status provided is not valid. |
| CG:03 | The description provided is not valid. |
| CG:04 | The home group message provided is not valid. |
| CG:05 | The notification email provided is not valid. |
| CG:07 | The email provided is not valid. |
| CG:08 | The employee id provided is not valid. |
| CG:09 | The code provided is not valid. |
| CG:10 | The value for a learning module/subscription variant id is not valid. |
| CG:11 | The value for allow self enroll notifications must be *1* or *0*. |
| CG:12 | The value for auto enroll notifications must be *1* or *0*. |
| CG:13 | The required permissions are not met to call the createGroup method. |
| CG:14 | User is not a part of the provided account. |
| CG:15 | Learning module is not a part of the provided account. |
| CG:16 | Group has too many notification records. |
| CG:17 | Users could not be added to the group. |
| CG:18 | Group permissions could not be granted to the users. |
| CG:19 | Home group could not be set. |
| CG:20 | Learning Modules could not be added to the group. |
| CG:21 | Learning Modules settings could not be updated. |
| CG:22 | Group name cannot be used. |
| CG:23 | The required permissions are not met to call the createGroup method. |
| CG:24 | The status provided is not valid. Only *Active* or *Inactive* are allowed values. |
| CG:25 | The group id provided is not valid. |
| CG:26 | Subscription Variant is not part of the provided account. |
| CG:27 | The value for requires credits notifications must be *1* or *0*. |
| CG:28 | The value for home group must be *1* or *0*. |
| CG:29 | One or more tags do not exist in the provided account. |
| CG:30 | All tags provided must have at least one value. |
| CG:31 | Values must be from the pre-defined list specified for the tag. |
| CG:32 | One or more values provided in the Tags2 nodes do not match. |
| CG:33 | The required permissions are not met to modify the group's dashboard set. |
| CG:34 | The dashboard set does not exist. |
| CG:35 | The dashboard set's scope of availability is not set to home group. |
| CG:36 | The user limit amount must be greater than 0 users. |
| CG:37 | Group would exceed user limit. |
| CG:38 | Number of users in this group would exceed the new limit. |
| CG:39 | Missing required fields to set user help settings. |
| CG:40 | User help email is invalid. |
| CG:41 | User help text is invalid. |

## Related

- [Account: Email Template Options](/account-email-template-options.md)
- [Adding a Group](/adding-a-group.md)
- [API: getLearnerReport](/api-getlearnerreport.md)
- [API: getUser](/api-getuser.md)
- [API: listLearningModules](/api-listlearningmodules.md)
- [API: listUsers](/api-listusers.md)
- [Group: Courses](/group-courses.md)
- [Group: Home Group Message](/group-home-group-message.md)
- [Group Permissions](/group-permissions-1.md)
- [Group: Subscriptions](/group-subscriptions.md)
- [Group: Users](/group-users.md)
- [System Email Templates: Course Emails - General](/system-email-templates-course-emails-general.md)