API: listUsers
  • 7 Minutes to read
  • Dark
    Light

API: listUsers

  • 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 listUsers method retrieves users that meet the specified filters. 

Who Has Access

The following users have access to the listUsers method:

API Call XML Package

<SmarterU>
   <AccountAPI><![CDATA[]]></AccountAPI>
   <UserAPI><![CDATA[]]></UserAPI>
   <Method>listUsers</Method>
   <Parameters>

      <User>
         <Page><![CDATA[]]></Page>
         <PageSize></PageSize>
         <SortField></SortField>
         <SortOrder></SortOrder>

         <Filters>
            <Users>
               <UserIdentifier>
                  <Email>
                     <MatchType></MatchType>
                     <Value><![CDATA[]]></Value>
                  </Email> 
                     - AND/OR - 
                  <EmployeeID> 
                     <MatchType></MatchType> 
                     <Value><![CDATA[]]></Value> 
                  </EmployeeID> 
                     - AND/OR - 
                  <Name> 
                     <MatchType></MatchType> 
                     <Value><![CDATA[]]></Value> 
                  </Name> </UserIdentifier> 
            </Users> 

            <HomeGroup><![CDATA[]]></HomeGroup> 
            <GroupName><![CDATA[]]></GroupName>
            <UserStatus><![CDATA[]]></UserStatus>    
            <CreatedDate> 
               <CreatedDateFrom></CreatedDateFrom>
               <CreatedDateTo></CreatedDateTo> 
            </CreatedDate> 
            <ModifiedDate> 
               <ModifiedDateFrom></ModifiedDateFrom> 
               <ModifiedDateTo></ModifiedDateTo> 
            </ModifiedDate> 

            <Teams> 
               <TeamNames> 
                  <TeamName><![CDATA[]]></TeamName> 
               </TeamNames> 
            </Teams> 

            <CustomFields> 
               <CustomField> 
                  <CustomFieldName><![CDATA[]]></CustomFieldName> 
                  <CustomFieldValue><![CDATA[]]></CustomFieldValue> 
               </CustomField> 
            </CustomFields> 
         </Filters> 
      </User> 
   </Parameters> 
</SmarterU>

User Tag Group

The User tag group is a container for how the response is returned and the user filters. 

<User>
   <Page><![CDATA[]]></Page>
   <PageSize></PageSize>
   <SortField></SortField>
   <SortOrder></SortOrder>

   <Filters>
      <Users>
         <UserIdentifier>
            <Email>
               <MatchType></MatchType>
               <Value><![CDATA[]]></Value>
            </Email> 
               - AND/OR - 
            <EmployeeID> 
               <MatchType></MatchType> 
               <Value><![CDATA[]]></Value> 
            </EmployeeID> 
               - AND/OR - 
            <Name> 
               <MatchType></MatchType> 
               <Value><![CDATA[]]></Value> 
            </Name> 
         </UserIdentifier> 
      </Users> 

      <HomeGroup><![CDATA[]]></HomeGroup> 
      <GroupName><![CDATA[]]></GroupName>
      <UserStatus><![CDATA[]]></UserStatus>
    
      <CreatedDate> 
         <CreatedDateFrom></CreatedDateFrom>
         <CreatedDateTo></CreatedDateTo> 
      </CreatedDate>
 
      <ModifiedDate> 
         <ModifiedDateFrom></ModifiedDateFrom> 
         <ModifiedDateTo></ModifiedDateTo> 
      </ModifiedDate> 

      <Teams> 
         <TeamNames> 
            <TeamName><![CDATA[]]></TeamName> 
         </TeamNames> 
      </Teams> 

      <CustomFields> 
         <CustomField> 
            <CustomFieldName><![CDATA[]]></CustomFieldName> 
            <CustomFieldValue><![CDATA[]]></CustomFieldValue> 
         </CustomField> 
      </CustomFields> 
   </Filters> 
</User> 

The User tag may contain the following tags. 

Page (optional)

The page number to return. The default is 1. 

PageSize (optional)

The maximum number of users to return. If the PageSize tag is not provided, up to 50 results are returned by default. The maximum allowed value is 1000.

SortField (optional)

The field used to sort the results:

  • Name - The results will be sorted by user names.
  • Employee_ID - The results will be sorted by employee IDs.

SortOrder (optional)

The direction that the results will be sorted:

  • Asc - The results will be sorted in ascending order. 
  • Desc - The results will be sorted in descending order.

The default is Asc.

Filters

A container for user filters. Refer to Filters Tag Group.

Filters Tag Group

The Filters tag group is a container for user filters.

<Filters>
   <Users>
      <UserIdentifier>
         <Email>
            <MatchType></MatchType>
            <Value><![CDATA[]]></Value>
         </Email>
            - AND/OR -
         <EmployeeID>
            <MatchType></MatchType>
            <Value><![CDATA[]]></Value>
         </EmployeeID>
            - AND/OR -
         <Name>
            <MatchType></MatchType>
            <Value><![CDATA[]]></Value>
         </Name>
      </UserIdentifier>
   </Users>

   <HomeGroup><![CDATA[]]></HomeGroup>
   <GroupName><![CDATA[]]></GroupName>
   <UserStatus><![CDATA[]]></UserStatus>
   <CreatedDate>
      <CreatedDateFrom></CreatedDateFrom>
      <CreatedDateTo></CreatedDateTo>
   </CreatedDate>
   <ModifiedDate>
      <ModifiedDateFrom></ModifiedDateFrom>
      <ModifiedDateTo></ModifiedDateTo>
   </ModifiedDate>

   <Teams>
      <TeamNames>
         <TeamName><![CDATA[]]></TeamName>
      </TeamNames>
   </Teams>

   <CustomFields>
      <CustomField>
         <CustomFieldName><![CDATA[]]></CustomFieldName>
         <CustomFieldValue><![CDATA[]]></CustomFieldValue>
      </CustomField>
   </CustomFields>

</Filters>

The Filters tag may contain the following.

Users (optional)

A container for user filters. Refer to Users Tag Group.

HomeGroup (optional)

The home group's name

GroupName (optional)

The group's name

UserStatus (optional)

The user's status

  • Active
  • Inactive
  • All

The default is All.

CreatedDate (optional)

A container for the user's creation date range. 

<CreatedDate>
   <CreatedDateFrom></CreatedDateFrom>
   <CreatedDateTo></CreatedDateTo>
</CreatedDate>

The CreatedDate tag contains the following.

TagDescription
CreatedDateFromThe first date to include in the date range filter. 
CreatedDateToThe last date to include in the date range filter.
  • Only one CreatedDate filter can be specified. 
  • If both a CreatedDate filter and a ModifiedDate filter are specified, the method will return all users that were created within the created date range OR modified within the modified date range. For example, if a user was created within the created date range, but their modified date is outside the modified date range, the user will be included.

ModifiedDate (optional)

A container for the user's last updated date range. 

<ModifiedDate>
   <ModifiedDateFrom></ModifiedDateFrom>
   <ModifiedDateTo></ModifiedDateTo>
</ModifiedDate>

The ModifiedDate tag contains the following.

TagDescription
ModifiedDateFromThe first date to include in the date range filter. 
ModifiedDateToThe last date to include in the date range filter.
  • The dates should be in dd-mmm-yyyy format.
  • Only one ModifiedDate filter can be specified. 
  • If both a CreatedDate filter and a ModifiedDate filter are specified, the method will return all users that were created within the created date range OR modified within the modified date range. For example, if a user was created outside the created date range, but their modified date is within the modified date range, the user will be included.

Teams (optional)

A container for the teams that a user is assigned to. 

<Teams>
   <TeamNames>
      <TeamName><![CDATA[]]></TeamName>
   </TeamNames>
</Teams>

Each team is contained in a TeamNames tag and contains the following.

TagDescription
TeamNameThe team's name.
  • At least one TeamName filter must be specified.
  • Specifying multiple TeamName filters will be evaluated using the OR operator. 

CustomFields (optional)

A container for the custom user field values specified for a user. Refer to CustomFields tag group.

Users Tag Group

The Users tag group is a container for user filters.

<Users>
   <UserIdentifier>
      <Email>
         <MatchType></MatchType>
         <Value><![CDATA[]]></Value>
      </Email>
         - AND/OR -
      <EmployeeID>
         <MatchType></MatchType>
         <Value><![CDATA[]]></Value>
      </EmployeeID>
         - AND/OR -
      <Name>
         <MatchType></MatchType>
         <Value><![CDATA[]]></Value>
      </Name>
   </UserIdentifier>
</Users>

Each user filter is contained in a UserIdentifier tag and may contain the following.

  • You must specify at least one of these tags.
  • Specifying multiple UserIdentifier tags will be evaluated using the OR operator.
  • Specifying multiple filters in a UserIdentifier tag will be evaluated using the OR operator.

Email

A container for the user email address filters. 

<Email>
   <MatchType></MatchType>
   <Value><![CDATA[]]></Value>
</Email>

The Email tag contains the following.

TagDescription
MatchTypeIndicates how the filter will be applied:
  • Exact - The email address must be an exact match to the filter value provided.
  • Contains - The email address must contain the filter value provided.
ValueThe user's email address.

EmployeeID

A container for the user employee ID filters. 

<EmployeeID>
   <MatchType></MatchType>
   <Value><![CDATA[]]></Value>
</EmployeeID>

The EmployeeID tag contains the following.

TagDescription
MatchTypeIndicates how the filter will be applied:
  • Exact - The employee ID must be an exact match to the filter value provided.
  • Contains - The employee ID must contain the filter value provided.
ValueThe user's employee ID.

Name

A container for the user names. 

<Name>
   <MatchType></MatchType>
   <Value><![CDATA[]]></Value>
</Name>

This tag contains the following.

TagDescription
MatchTypeIndicates how the filter will be applied:
  • Exact - The user name must be an exact match to the filter value provided.
  • Contains - The user name must contain the filter value provided.
ValueThe user's name.

CustomFields Tag Group

The CustomFields tag group is a container for the custom user field values specified for a user.

<CustomFields>
   <CustomField>
      <CustomFieldName><![CDATA[]]></CustomFieldName>
      <CustomFieldValue><![CDATA[]]></CustomFieldValue>
   </CustomField>
</CustomFields>

Each custom user field filter is contained in a CustomField tag and contains the following.

CustomFieldName

The custom user field's name

CustomFieldValue

The value of the custom user field. To specify the value for a hierarchical custom user field, separate each level's value with a greater than symbol (>). For example, suppose you have the following levels and values for the Place of Birth hierarchical custom user field.

Hierarchical Custom User Field Example 20221130

The following would filter the City level of the custom user field for the value Portland.

<CustomFields>
   <CustomField>
      <CustomFieldName><![CDATA[Place of Birth]]></CustomFieldName>
      <CustomFieldValue><![CDATA[USA>Oregon>Portland]]></CustomFieldValue>
   </CustomField>
</CustomFields>

API Response XML Package

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

<SmarterU>
    <Result></Result>
    <Info>
        <Users>
            <User>
                <ID><![CDATA[]]></ID>
                <Email><![CDATA[]]></Email>
                <EmployeeID><![CDATA[]]></EmployeeID>
                <GivenName><![CDATA[]]></GivenName>
                <Surname><![CDATA[]]></Surname>
                <Name><![CDATA[]]></Name>
                <Status><![CDATA[]]></Status>
                <Title><![CDATA[]]></Title>
                <Division><![CDATA[]]></Division>
                <HomeGroup><![CDATA[]]></HomeGroup>
                <CreatedDate><![CDATA[]]></CreatedDate>
                <ModifiedDate><![CDATA[]]></ModifiedDate>
                <Teams>
                   <Team><![CDATA[]]></Team>
                </Teams>
            </User>
        </Users>
        <TotalRecords></TotalRecords>
    </Info>
    <Errors>
        <Error>
            <ErrorID></ErrorID>
            <ErrorMessage></ErrorMessage>
        </Error>
    </Errors>
</SmarterU>

The Users tag is a container for the users returned by the listUsers method. Each user is contained in a User tag and may contain the following.

ID

The user's system-generated identifier.

Email

The user's email address.

EmployeeID

The user's employee ID.

GivenName

The user's first name.

Surname

The user's last name.

Name

The user's full name in the format Surname,FirstName.

Status

The user's status:

  • Active - The user account may be used to access SmarterU. 
  • Inactive - The user account may not be used to access SmarterU. 

Title

Division

HomeGroup

The name of the user's home group.

CreatedDate

The date the user's account was created.

ModifiedDate

The date the user's account was last updated.

Teams

A container for the user's teams. Each team name is contained in a Team tag.

TotalRecords

The total number of records returned for all the pages.

Example API Response XML Package

Below is an example of an API response XML package.

<SmarterU>
   <Result>Success</Result>

   <Info>
      <Users>
         <User>
            <ID><![CDATA[25367]]></ID>
            <Email><![CDATA[robin.atkins@finashoes.com]]></Email>
            <EmployeeID><![CDATA[Rob007]]></EmployeeID>
            <GivenName><![CDATA[Robin]]></GivenName>
            <Surname><![CDATA[Atkins]]></Surname>
            <Name><![CDATA[Atkins,Robin]]></Name>
            <Status><![CDATA[Active]]></Status>
            <Title><![CDATA[Sales Associate]]></Title>
            <Division><![CDATA[Retail]]></Division>
            <HomeGroup><![CDATA[Human Resources]]></HomeGroup>
            <CreatedDate><![CDATA[ 23-Jan-2018]]></CreatedDate>
            <ModifiedDate><![CDATA[ 10-Jul-2019]]></ModifiedDate>
            <Teams>
               <Team><![CDATA[Sales]]></Team>
            </Teams>
        </User>

        <User>
            <ID><![CDATA[804030]]></ID>
            <Email><![CDATA[helen.bonner@finashoes.com]]></Email>
            <EmployeeID/>
            <GivenName><![CDATA[Helen]]></GivenName>
            <Surname><![CDATA[Bonner]]></Surname>
            <Name><![CDATA[Bonner,Helen]]></Name>
            <Status><![CDATA[Active]]></Status>
            <Title><![CDATA[Director]]></Title>
            <Division/>
            <HomeGroup><![CDATA[Marketing]]></HomeGroup>
            <CreatedDate><![CDATA[ 21-Mar-2018]]></CreatedDate>
            <ModifiedDate><![CDATA[ 27-Jun-2019]]></ModifiedDate>
            <Teams>
               <Team><![CDATA[Leadership]]></Team>
            </Teams>
         </User>

         <User>
            <ID><![CDATA[25374]]></ID>
            <Email><![CDATA[anthony.cruz@finashoes.com]]></Email>
            <EmployeeID/>
            <GivenName><![CDATA[Anthony]]></GivenName>
            <Surname><![CDATA[Cruz]]></Surname>
            <Name><![CDATA[Cruz,Anthony]]></Name>
            <Status><![CDATA[Active]]></Status>
            <Title><![CDATA[HR Specialist]]></Title>
            <Division><![CDATA[Human Resources]]></Division>
            <HomeGroup><![CDATA[Human Resources]]></HomeGroup>
            <CreatedDate><![CDATA[ 24-Jan-2018]]></CreatedDate>
            <ModifiedDate><![CDATA[ 24-Jan-2018]]></ModifiedDate>
            <Teams>
               <Team><![CDATA[Leadership]]></Team>
            </Teams>
         </User>
      </Users>
      <TotalRecords>3</TotalRecords>
   </Info>

   <Errors>
   </Errors>
</SmarterU> 

Error Codes

Error CodeMessage
LU:01The page number provided is not valid.
LU:02The group name provided is invalid.
LU:03The user status provided is invalid.
LU:04The required permissions are not met to call the listUsers method.
LU:05The created date provided is not valid.
LU:06The modified date provided is not valid.
LU:07The page size provided is not valid.
LU:08The sort field provided is not valid.
LU:09The sort order provided is not valid.
LU:10The email address provided is not valid.
LU:11The employee ID provided is not valid.
LU:12The name provided is not valid.
LU:13The user identifier match type provided is not valid.
LU:14The user identifier value provided is not valid.
LU:15The value for the sort field must be NAME or EMPLOYEE_ID.
LU:16The value for the sort order must be ASC or DESC.
LU:17User and/or Team filters are exceeding the 2000 filter limit. Remove # User/Team filter(s).
LU:18The user email match type provided is not valid.
LU:19The user employee ID match type provided is not valid.
LU:20The user name match type provided is not valid.
LU:21The team names provided are not valid.
LU:22The team name provided is not valid.
LU:23The home group provided is not valid.
LU:24A minimum of one custom field must be provided.
LU:25A custom field name and value must be provided for all custom fields.
LU:26A custom field name provided is not valid.
LU:27A custom field value provided is not valid.

Was this article helpful?