API: getCustomFieldHierarchy
  • 2 Minutes to read
  • Dark
    Light

API: getCustomFieldHierarchy

  • 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 getCustomFieldHierarchy method retrieves details about the levels and values for a custom user field's hierarchy.

Who Has Access

Administrators and owners have access to the getCustomFieldHierarchy method. 

API Call XML Package

<SmarterU>
   <AccountAPI><![CDATA[]]></AccountAPI>
   <UserAPI><![CDATA[]]></UserAPI>
   <Method>getCustomFieldHierarchy</Method>
   <Parameters>
      <CustomField>
         <ID><![CDATA[]]></ID>
            - OR -
         <Name><![CDATA[]]></Name>
      </CustomField>
   </Parameters>
</SmarterU>

CustomField Tag Group

The CustomField tag group is a container for the custom user field filters.

<CustomField>
   <ID><![CDATA[]]></ID>
      - OR -
   <Name><![CDATA[]]></Name>
</CustomField>

The CustomField tag contains one of the following.

ID

The custom user field's system-generated identifier. This is the ID returned by the listCustomFields method. This is mutually exclusive with the Name tag.

Name

The custom user field's name. This is mutually exclusive with the ID tag.

API Response XML Package

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

<SmarterU>
   <Result></Result>
   <Info>
      <CustomField>
         <ID>![CDATA[]]</ID>
         <Name><![CDATA[]]></Name>
         <Levels>
            <Level>
               <LevelID>![CDATA]]</LevelID>
               <Name><![CDATA[]]></Name>
               <Values>
                  <Value>
                     <ValueID>![CDATA[]]</ValueID>
                     <ParentValueID>![CDATA[]]<ParentValueID/>
                     <Value><![CDATA[]]></Value>
                  </Value>
                </Values>
             </Level>
         </Levels>
      </CustomField>
   </Info>
   <Errors>
      <Error>
         <ErrorID></ErrorID>
         <ErrorMessage></ErrorMessage>
      </Error>
   </Errors>
</SmarterU> 

The custom user field is contained in a CustomField tag and may contain the following.

ID

The custom user field's system-generated identifier.

Name

The custom user field's name.

Levels

The Levels tag is a container for the hierarchical custom user field's levels. Each level is contained in a Level tag and may contain the following. 

TagDescription
LevelIDThe custom user field level's system-generated identifier.
NameThe custom user field level's name.
Values

The Values tag is a container for the values assigned to the level. Each value is contained in a Value tag and contains the following:

  • ValueID - The value's system-generated identifier. 
  • ParentValueID - The system-generated identifier for the value's parent. This tag will be blank if the value does not have a parent (i.e., it's the top value).
  • Value - The value's name.

Example API Response XML Package

<SmarterU>
   <Result>Success</Result>
   <Info>
      <CustomField>
         <ID>1824</ID>
         <Name><![CDATA[Location]]></Name>
         <Levels>
            <Level>
               <LevelID>1825</LevelID>
               <Name><![CDATA[Country]]></Name>
               <Values>
                  <Value>
                     <ValueID>17</ValueID>
                     <ParentValueID/>
                     <Value><![CDATA[United States]]></Value>
                  </Value>
                  <Value>
                     <ValueID>4162</ValueID>
                     <ParentValueID/>
                     <Value><![CDATA[Canada]]></Value>
                  </Value>
               </Values>
            </Level>

            <Level>
               <LevelID>1827</LevelID>
               <Name><![CDATA[Region]]></Name>
               <Values>
                  <Value>
                     <ValueID>19</ValueID>
                     <ParentValueID>17</ParentValueID>
                     <Value><![CDATA[California]]></Value>
                  </Value>
                  <Value>
                     <ValueID>4163</ValueID>
                     <ParentValueID>4162</ParentValueID>
                     <Value><![CDATA[Manitoba]]></Value>
                  </Value>
                  <Value>
                     <ValueID>4164</ValueID>
                     <ParentValueID>4162</ParentValueID>
                     <Value><![CDATA[Ontario]]></Value>
                  </Value>
               </Values>
            </Level>
      </CustomField>
   </Info>

   <Errors>
   </Errors>

</SmarterU> 

Error Codes

Error CodeMessage
GCFH:01
The ID provided is not valid.
GCFH:02
The name provided is not valid.
GCFH:03
The required permissions are not met to call the getCustomFieldHierarchy method.
GCFH:04
The custom hierarchy field requested does not exist.

Was this article helpful?