---
title: "API: updateCustomFieldHierarchyValue"
slug: "api-updatecustomfieldhierarchyvalue"
updated: 2022-08-30T14:19:08Z
published: 2022-08-30T14:19:08Z
canonical: "support.smarteru.com/api-updatecustomfieldhierarchyvalue"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://support.smarteru.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API: updateCustomFieldHierarchyValue

- SmarterU requires 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 updateCustomFieldHierarchyValue adds, edits, or removes values from a [hierarchical custom user field](https://support.smarteru.com/docs/account-custom-user-fields#adding-levels-and-values-to-a-hierarchical-custom-user-fields).

## Who Has Access

The following users have access to the updateCustomFieldHierarchyValue:

- Users with the [Manage Account Settings](/v1/docs/account-permission-manage-account-settings) account permission.
- [Administrators and owners](https://support.smarteru.com/docs/user-profile-information#access-level).

## API Call XML Package

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

         <Values>
            <Value>
               <ValueAction></ValueAction>
               <ParentValueID></ParentValueID>
               <Value><![CDATA[]]></Value>
               <NewValue><![CDATA[]]></NewValue>
            </Value>
         </Values>
      </CustomField>
   </Parameters>
</SmarterU>
```

## CustomField Tag Group

The CustomField tag group is a container for the custom fields you want to edit and their values.

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

   <Values>
      <Value>
         <ValueAction></ValueAction>
         <ParentValueID></ParentValueID>
         <Value><![CDATA[]]></Value>
         <NewValue><![CDATA[]]></NewValue>
      </Value>
   </Values>
</CustomField>
```

The CustomField tag may contain the following.

### ID

The hierarchical custom field's system-generated identifier. This is the ID returned by the [listCustomFields](/v1/docs/api-listcustomfields) method. This tag is mutually exclusive with the Name tag.

### Name

The [hierarchical custom field's name](https://support.smarteru.com/docs/account-custom-user-fields#name). This tag is mutually exclusive with the ID tag.

### Values

The Values tag is a container for the updates you want to make to a [hierarchical custom user field](https://support.smarteru.com/docs/account-custom-user-fields#adding-levels-and-values-to-a-hierarchical-custom-user-fields). Refer to [Values Tag Group](/v1/docs/api-updatecustomfieldhierarchyvalue#values-tag-group).

## Values Tag Group

The Values tag group is a container for the updates you want to make to a hierarchical custom field.

```markup
<Values>
   <Value>
      <ValueAction></ValueAction>
      <ParentValueID></ParentValueID>
      <Value><![CDATA[]]></Value>
      <NewValue><![CDATA[]]></NewValue>
   </Value>
</Values>
```

The Values tag may contain the following.

### Value

The Value tag is a container for each change you want to make to a hierarchical custom field. Each change you want to make should be enclosed within a Value tag.

The Value tag may contain the following.

| Tag | Description |
| --- | --- |
| **ValueAction** | The type of change you want to make to a hierarchical custom field. Acceptable values are: - *Add* - Add a value to a hierarchical custom field level. - *Remove* - Remove a value from a hierarchical custom field level. - *Update* - Replace a value in a hierarchical custom field level. |
| **ParentValueID** | The system-generated identifier of the hierarchical custom field's parent. This is the ValueID returned by the [getCustomFieldHierarchy](/v1/docs/api-getcustomfieldhierarchy) method. If ValueAction is set to *Add* and no ParentValueID is specified, the value will be added to the top level. |
| **ValueID** | If ValueAction is set to *Update*, this is the system-generated ID of the hierarchical custom field that you want to update. This is the ValueID returned by the [getCustomFieldHierarchy](/v1/docs/api-getcustomfieldhierarchy) method. If ValueAction is set to *Remove* and ParentValueID is not specified, this is a required tag. This is the system-generated ID of the hierarchical custom field that you want to remove. This is the ValueID returned by the [getCustomFieldHierarchy](/v1/docs/api-getcustomfieldhierarchy) method. |
| **Value** | If ValueAction is set to *Add*, this is a required tag. This is the value to add to the hierarchical custom field. If ValueAction is set to *Remove* and the ParentValueID is specified, this is the value to remove. |
| **NewValue** | This tag is required if ValueAction is set to *Update*. The updated value for a hierarchical custom field. |

## Example API Calls

The examples below use the Location hierarchical custom field that has the following levels and values.

![Diagram - Hiearchical Custom Field Levels and Values 20220802(2)](https://cdn.document360.io/7efaadab-fef6-4186-806a-2ca14c9ce9ea/Images/Documentation/Diagram%20-%20Hiearchical%20Custom%20Field%20Levels%20and%20Values%2020220802(2).png)

### Adding a Value to a Level

The following example adds the city, Tampa, to the state, Florida.

```markup
<CustomField>
   <ID>1000</ID>
      - OR -
   <Name><![CDATA[Location]]></Name>

   <Value>
      <ValueAction>Add</ValueAction>
      <ParentValueID>1200</ParentValueID>
      <Value><![CDATA[Tampa]]></Value>
   </Value>
</CustomField>
```

### Adding a Value to the Top Level

The following example adds Canada to the Country level.

```markup
<CustomField>
   <Value>
      <ValueAction>Add</ValueAction>
      <Value><![CDATA[Canada]]></Value>
   </Value>
</CustomField>
```

### Removing a Value from a Level

The following example removes the city, Orlando, from the state, Florida.

```markup
<CustomField>
   <ID>1000</ID>
      - OR -
   <Name><![CDATA[Location]]></Name>

   <Value>
      <ValueAction>Remove</ValueAction>

      <ValueID>1210</ValueID>
         - OR - 
      <ParentValueID>1200</ParentValueID>
      <Value><![CDATA[Orlando]]></Value>

   </Value>
</CustomField>
```

### Updating a Value

The following example replaces the city, Eugene, in the state, Oregon with Bend.

```markup
<CustomField>
   <ID>1000</ID>
      - OR -
   <Name><![CDATA[Location]]></Name>

   <Value>
      <ValueAction>Update</ValueAction>

      <ValueID>1310</ValueID>
         - OR - 
      <ParentValueID>1300</ParentValueID>
      <Value><![CDATA[Eugene]]></Value>
      <NewValue><![CDATA[Bend]]></NewValue>

   </Value>
</CustomField>
```

## API Response XML Package

The [API response XML package](/v1/docs/api-response-xml-package) will always include a Result, Info, and [Errors](/v1/docs/api-updatecustomfieldhierarchyvalue#error-codes) tag.

```markup
<SmarterU>
   <Result></Result>
   <Info>
      <ID></ID>
      <CustomField></CustomField>
   </Info>

   <Errors>
      <ErrorID></ErrorID>
      <ErrorMessage></ErrorMessage>
   </Errors>
</SmarterU>
```

The response may also contain the following.

### ID

The hierarchical custom field's system-generated identifier.

### Name

The [hierarchical custom field's name](https://support.smarteru.com/docs/account-custom-user-fields#name).

### Example API Response XML Package

Below is an example of an API response XML package.

```markup
<SmarterU>
   <Result>Success</Result>
   <Info>
      <ID>1000</ID>
      <CustomField>Location</CustomField>
   </Info>

   <Errors>
      <ErrorID></ErrorID>
      <ErrorMessage></ErrorMessage>
   </Errors>
</SmarterU>
```

## Error Codes

| Error Code | Message |
| --- | --- |
| UCFHV:01 | The ID provided is not valid. |
| UCFHV:02 | The name provided is not valid. |
| UCFHV:03 | The required permissions are not met to call the updateCustomFieldHierarchyValue method. |
| UCFHV:04 | The custom hierarchy field requested does not exist. |
| UCFHV:05 | The custom hierarchy field requested has no levels. |
| UCFHV:06 | The value action provided is not valid. |
| UCFHV:07 | The value ID provided is not valid. |
| UCFHV:08 | The parent value ID provided is not valid. |
| UCFHV:09 | The parent value requested does not exist. |
| UCFHV:10 | The value provided is not valid. |
| UCHFV:11 | The value already exists under the parent. |
| UCHFV:12 | The value requested does not exist. |
| UCHFV:13 | The new value provided is not valid. |
| UCHFV:14 | The new value already exists under the parent. |

## Related

- [Account: Custom User Fields](/account-custom-user-fields.md)
- [API: getCustomFieldHierarchy](/api-getcustomfieldhierarchy.md)
- [API: listCustomFields](/api-listcustomfields.md)