API: listUsers

7 Minutes to read

Print
Share
Dark
Light

API: listUsers

7 Minutes to read

Print
Share
Dark
Light

Article summary

Did you find this summary helpful?

Thank you for your feedback

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:

Users with the Group Manager, Manage Group Users, or Manage Users group permission.
Supervisors, if the account's Supervisor Access setting'sView Supervisees or Edit Supervisees option is checked.
Administrators and owners.

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>

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.

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.

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.

Tag	Description
CreatedDateFrom	The first date to include in the date range filter.
CreatedDateTo	The 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.

Tag	Description
ModifiedDateFrom	The first date to include in the date range filter.
ModifiedDateTo	The 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.

Tag	Description
TeamName	The 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.

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.

Tag	Description
MatchType	Indicates 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.
Value	The 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.

Tag	Description
MatchType	Indicates 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.
Value	The user's employee ID.

Name

A container for the user names.

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

This tag contains the following.

Tag	Description
MatchType	Indicates 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.
Value	The user's name.

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

The user's title.

Division

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

Was this article helpful?

What's Next

API: listUsersCounts

Table of contents

Description
Who Has Access
API Call XML Package
User Tag Group
Filters Tag Group
Users Tag Group
CustomFields Tag Group
API Response XML Package
Error Codes

API: listUsers

Description

Who Has Access

API Call XML Package

User Tag Group

Page (optional)

PageSize (optional)

SortField (optional)

SortOrder (optional)

Filters

Filters Tag Group

Users (optional)

HomeGroup (optional)

GroupName (optional)

UserStatus (optional)

CreatedDate (optional)

ModifiedDate (optional)

Teams (optional)

CustomFields (optional)

Users Tag Group

Email

EmployeeID

Name

CustomFields Tag Group

CustomFieldName

CustomFieldValue

API Response XML Package

ID

Email

EmployeeID

GivenName

Surname

Name

Status

Title

Division

HomeGroup

CreatedDate

ModifiedDate

Teams

TotalRecords

Example API Response XML Package

Error Codes

Related articles

What's Next