API: listCredentials
  • 4 Minutes to read
  • Dark
    Light

API: listCredentials

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

Actions were previously referred to credentials.  

Who Has Access

The following users have access to the listCredentials method:

API Call XML Package

<SmarterU>
   <AccountAPI><![CDATA[]]></AccountAPI>
   <UserAPI><![CDATA[]]></UserAPI>
   <Method>listCredentials</Method>
   <Parameters>
      <Credential>
         <Page></Page>
         <PageSize></PageSize>
         <SortField></SortField>
         <SortOrder></SortOrder>

         <Filters>
            <CredentialStatus></CredentialStatus>

            <Expiration>
               <Days>
                  <DaysFrom></DaysFrom>
                  <DaysTo></DaysTo>
               </Days>
                  - OR -
               <Date>
                  <DateFrom><![CDATA[]]></DateFrom>
                  <DateTo><![CDATA[]]></DateTo>
               </Date>
            </Expiration> 

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

      </Credential>
   </Parameters>
</SmarterU>

Credential Tag Group

The Credential tag group is a container for the how the response is returned and the action filters.

<Credential>
   <Page></Page>
   <PageSize></PageSize>
   <SortField></SortField>
   <SortOrder></SortOrder>

   <Filters>
      <CredentialStatus></CredentialStatus>

      <Expiration>
         <Days>
            <DaysFrom></DaysFrom>
            <DaysTo></DaysTo>
         </Days>
            - OR -
         <Date>
            <DateFrom><![CDATA[]]></DateFrom>
            <DateTo><![CDATA[]]></DateTo>
         </Date>
      </Expiration> 

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

</Credential>

The Credential tag may contain the following.

Page (optional)

The page number to return. The default is 1.

PageSize (optional)

The maximum number of results 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. Acceptable values are:

  • Name - The action's name.
  • Status - The action's status
  • Expiration - The action's expiration date.

SortOrder (optional)

The direction that the results will be sorted:

  • Asc - The results will be sorted in ascending order. This is the default.
  • Desc - The results will be sorted in descending order.

Filters (optional)

The Filters tag is a container for action filters. Refer to Filters Tag Group

Filters Tag Group

The Filters tag group is a container for action filters. 

<Filters>
   <CredentialStatus></CredentialStatus>

   <Expiration>
      <Days>
         <DaysFrom></DaysFrom>
         <DaysTo></DaysTo>
      </Days>
         - OR -
      <Date>
         <DateFrom><![CDATA[]]></DateFrom>
         <DateTo><![CDATA[]]></DateTo>
      </Date>
   </Expiration> 

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

The Filters tag may contain the following.

CredentialStatus

The action's status. Acceptable values are Active, Inactive, or All. The default is All.

Expiration

A container for filtering actions by their expiration. Refer to Expiration Tag Group.

Tags2

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

Expiration Tag Group

The Expiration tag group is a container for filtering actions by their expiration.

<Expiration>
   <Days>
      <DaysFrom></DaysFrom>
      <DaysTo></DaysTo>
   </Days>
      - OR -
   <Date>
      <DateFrom><![CDATA[]]></DateFrom>
      <DateTo><![CDATA[]]></DateTo>
   </Date>
</Expiration>

The Expiration tag contains the following.

Days (optional)

A container for filtering actions based on the number of days until they expire. For example, actions that expire within 14-21 days. This tag is mutually exclusive with the Date tag and contains the following.

TagDescription

DaysFrom

The smaller number in the range of days that an action expires. For example, if you're filtering for actions that expire within 14-21 days, DaysFrom is 14. 

DaysTo

The larger number in the range of days that an action expires. For example, if you're filtering for actions that expire within 14-21 days, DaysTo is 21. 

Date (optional)

A container for filtering actions based on the date that they expire. This tag is mutually exclusive with the Days tag. This tag contains the following.

TagDescription

DateFrom

The first date to include in the action expiration date range filter in d-MMM format.

DateTo

The last date to include in the action expiration date range filter in d-MMM format. 

Tags2 Tag Group

The Tags2 tag group is a container for filtering actions 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 may contain the following.

TagID

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>
      <Credential>
        <Credential>
           <Name><![CDATA[]]></Name>
           <CredentialID></CredentialID>
           <Status></Status>

           <Expires></Expires>
           <ExpirationType></ExpirationType>
           <Expiration></Expiration>
 
           <Tags2>
              <Tag2>
                 <TagID><![CDATA[]]></TagID>
                 <TagName><![CDATA[]]></TagName>
                 <TagValues><![CDATA[]]></TagValues>
              </Tag2>
           </Tags2>
        </Credential>
     </Credential>
     <TotalRecords></TotalRecords>
   </Info>

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

The Credential tag is a container for the actions returned by the listCredentials method. Each action is contained in a Credential tag and may contain the following.

Name

The action's name.

CredentialID

The action's system-generated identifier.

Status

The action's status

Expires

Indicates whether the action expires. Acceptable values are:

  • 0  - The action doesn't expire.
  • 1 - The action expires.

ExpirationType

Indicates how the action's expiration is calculated:

  • ByDays - The action's expiration is calculated based on a specified number of days.
  • ByDate - The action's expiration is a specific date.

Expiration

The value returned depends on what ExpirationType returns:

Tags2

A container for the action's tags. Each tag is contained in a Tags2 tag and contains the following.

TagDescription
TagIDThe tag's system-generated identifer.
TagNameThe tag's name.
TagValuesA comma-separated list of tag values associated with the action.

TotalRecords

The total number of records returned.

Example API Response XML Package

Below is an example of an API response XML package.

<SmarterU>
   <Result>Success</Result>
   <Info>
      <Credential>
        <Credential>
           <Name><![CDATA[Background Check]]></Name>
           <CredentialID>1123</CredentialID>
           <Status>Active</Status>
           <Expires>0</Expires>
           <Tags2></Tags2>
        </Credential>

        <Credential>
           <Name><![CDATA[Driver's License]]></Name>
           <CredentialID>12</CredentialID>
           <Status>Active</Status>
           <Expires>1</Expires>
           <ExpirationType>ByDays</ExpirationType>
           <Expiration>365</Expiration>
           <Tags2>
              <Tag2>
                 <TagID><![CDATA[7]]></TagID>
                 <TagName><![CDATA[Machinery]]></TagName>
                 <TagValues><![CDATA[conveyor belt,forklift]]></TagValues>
              </Tag2>
           </Tags2>
        </Credential>

     </Credential>
   </Info>

   <Errors>
   </Errors>
</SmarterU>

Error Codes

Error CodeDescription
LC:01
The page provided is invalid.
LC:02
The filters provided is invalid.
LC:03
The credential status provided is invalid.
LC:04
The required permissions are not met to call the listCredentials method.
LC:05
The value for a role status must be Active, Inactive, or All.
LC:06
The page size provided is invalid.
LC:07
The sort field provided is invalid.
LC:08
The sort order provided is invalid.
LC:09
The expiration provided is invalid.
LC:10
The days provided is invalid.
LC:11
The days from provided is invalid.
LC:12
The days to provided is invalid.
LC:13
The date provided is invalid.
LC:14
The date from provided is invalid.
LC:15
The date to provided is invalid.

Was this article helpful?