API: listGroups
  • 2 Minutes to read
  • Dark
    Light

API: listGroups

  • Dark
    Light

Article Summary

  • 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 that meet the specified filters.

Who Has Access

The following users have access to the listGroups method:

API Call XML Package

<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. 

<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

Filters Tag Group

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

<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. The GroupName tag may contain the following.

TagDescription

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. Acceptable values are Active or Inactive.

Tags2 (optional)

A container for filtering groups by their tags. Refer to Tags2 Tag Group.

Tags2 Tag Group

The Tags2 tag group is a container for filtering groups by their tags.

<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 TagName tag

To obtain a tag's ID:

  1. Navigate to the 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. 

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

TagName

The tag's name. This tag is mutually exclusive with the TagID tag.

TagValues (optional)

A comma-separated list of the tag values to include.

API Response XML Package

The API response XML package will always include a Result, Info, and Errors tag.

<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.

GroupID

The group's user-specified identifier.

Example API Response XML Package

Below is an example of an API response XML package.

<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 CodeMessage
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.

Was this article helpful?