---
title: "API: listGroups"
slug: "api-listgroups"
updated: 2023-01-18T15:45:29Z
published: 2023-01-18T15:45:29Z
canonical: "support.smarteru.com/api-listgroups"
---

> ## 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: listGroups

- Starting June 1, 2022, SmarterU will require 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 listGroups method is retrieves [groups](/v1/docs/groups) that meet the specified filters.

## **Who Has Access**

The following users have access to the listGroups 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.
- [Administrators and owners](/v1/docs/user-profile-information#access-level).

## **API Call XML Package**

```markup
<SmarterU>
   <AccountAPI><![CDATA[]]></AccountAPI>
   <UserAPI><![CDATA[]]></UserAPI>
   <Method>listGroups</Method>
   <Parameters>
      <Group>
         <Filters>
            <GroupName>
               <MatchType><![CDATA[]]></MatchType>
               <Value><![CDATA[]]></Value>
            </GroupName>
            <GroupStatus><![CDATA[]]></GroupStatus>
            <Tags2>
               <Tag2>
                  <TagID><![CDATA[]]></TagID>
                     - OR -
                  <TagName><![CDATA[]]></TagName>
                  <TagValues><![CDATA[]]></TagValues>
               </Tag2>
            </Tags2>
        </Filters>
     </Group>
   </Parameters>
</SmarterU>
```

## 

## Group Tag Group

The Group tag group is a container for group filters.

```markup
<Group>
   <Filters>
      <GroupName>
         <MatchType><![CDATA[]]></MatchType>
         <Value><![CDATA[]]></Value>
      </GroupName>
      <GroupStatus><![CDATA[]]></GroupStatus>
      <Tags2>
         <Tag2>
            <TagID><![CDATA[]]></TagID>
               - OR -
            <TagName><![CDATA[]]></TagName>
            <TagValues><![CDATA[]]></TagValues>
         </Tag2>
      </Tags2>
   </Filters>
</Group>
```

The Group tag may contain the following.

### Filters

A container for the group filters. Refer to [Filters Tag Group](/v1/docs/api-listgroups#filters-tag-group).

## Filters Tag Group

The Filters tag group is a container for the group filters.

```markup
<Filters>
   <GroupName>
      <MatchType><![CDATA[]]></MatchType>
      <Value><![CDATA[]]></Value>
   </GroupName>
   <GroupStatus><![CDATA[]]></GroupStatus>
   <Tags2>
      <Tag2>
         <TagID><![CDATA[]]></TagID>
            - OR -
         <TagName><![CDATA[]]></TagName>
         <TagValues><![CDATA[]]></TagValues>
      </Tag2>
   </Tags2>
 </Filters>
```

The Filters tag may contain the following.

### GroupName (optional)

The [group's name](https://support.smarteru.com/v1/docs/group-group-information#name). The GroupName tag may contain the following.

| Tag | Description |
| --- | --- |
| **MatchType** | Indicates how the filter will be applied. Acceptable values are: - *Exact* - The group name must be an exact match to the value provided. - *Contains* - The group name must contain the value provided. |
| **Value** | The filter value to apply to group names. |

### GroupStatus (optional)

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

### Tags2 (optional)

A container for filtering groups by their tags. Refer to [Tags2 Tag Group](/v1/docs/api-listgroups#tags2-tag-group).

## Tags2 Tag Group

The Tags2 tag group is a container for filtering groups by their [tags](/v1/docs/group-tags).

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

Each tag filter 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-listgroups$tags2_TagName)[TagName tag](/v1/docs/api-listgroups#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-listgroups$tags2_TagId)[TagID tag](/v1/docs/api-listgroups#tagid).

### TagValues (optional)

A comma-separated list of the [tag values](/v1/docs/tag-pre-defined-values) to include.

## 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-listgroups#error-codes) tag.

```markup
<SmarterU>
   <Result></Result>

   <Info>
      <Groups>
         <Group>
            <Name><![CDATA[]]></Name>
            <GroupID><![CDATA[]]></GroupID>
         </Group>
      </Groups>
   </Info>     

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

The Groups tag is a container for the groups returned by the listGroups method. Each group is contained in a Group tag and may contain the following.

### Name

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

### GroupID

The [group's user-specified identifier](/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>
      <Groups>
         <Group>
            <Name><!--[CDATA[Human Resources]]--></Name>
            <GroupID><![CDATA[G-1001]]></GroupID>
         </Group>
 
         <Group>
            <Name><![CDATA[Retail]]></Name>
            <GroupID><![CDATA[G-3039]]></GroupID>
         </Group>
      </Groups>
   </Info>     

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

## **Error Codes**

| Error Code | Message |
| --- | --- |
| LG:01 | The match type provided is not valid. |
| LG:02 | The group name provided is not valid. |
| LG:03 | The status provided is not valid. |
| LG:05 | The required permissions are not met to call the listGroups method. |
| LG:06 | One or more tags do not exist in the provided account. |
| LG:07 | One or more values provided in the Tags2 nodes do not match. |

## Related

- [API: createGroup](/api-creategroup.md)
- [API: getGroup](/api-getgroup.md)
- [API: getGroupLearningModules](/api-getgrouplearningmodules.md)
- [API: updateGroup](/api-updategroup.md)
- [Groups](/groups.md)