In HubSpot, a "property" is a field or an area where a value can be input for a certain attribute of a record.  For instance, a Contact might have a "Birthday" property, and a specific Contact would have his or her own Birthday value.  These properties can have different formats, which govern what kind of data they can store.  This article will discuss using and maintaining properties of the various multiple-option formats, both in common usage, and with regards to integrations.

When editing properties in HubSpot, it is important to know what effects these changes may have on your data.  Property formats with multiple options will have both Label values and Internal values as part of a number of choices.  The Label value is shown to users as they navigate HubSpot data, but the Internal value is usually invisible.  The Internal value is the value that is actually stored in the record in these cases, and this is an important distinction.

HubSpot requires that each item inside a multiple choice property have both a unique Label, and a unique Internal value.  Other systems such as Dynamics CRM do not have this requirement, so an integration may need additional work to help determine how data needs to be translated between systems.  

For our integrations, we offer the ability to automatically manage your properties with multiple item choices.  We do this by attempting to match first based on the Label, and then on the Internal value of items in a property.  If we find no matches in either case when a given record syncs, we create a new option in the HubSpot property to match the incoming data from your other system.  However, there may be cases where this requires intervention (such as the above case of duplicate Labels), or there may be cases where another system in your integration relies on a different set of Internal values, and these must exist in HubSpot to make effective matches in data.  Alternatively, you may have reasons for not wishing us to handle your multiple choice properties automatically.  In such cases, you may need to adjust the Internal values of properties in HubSpot manually to ensure there will be matches across your data.

When updating an existing item in a Dropdown property, changing the Label of an item will take effect almost immediately, and will not modify data on existing records.  It simply updates the visual representation of the choice for that property's values shown to users across all areas of HubSpot.  In general, your integration should not rely on Labels for matching synced data, since Labels can be so easily (and often) changed.

Conversely, changing the Internal value of an existing item with cause a background job to run that automatically updates all records with the old Internal value to the changed value.  After changing an item's Internal value and saving the change, your data should begin to update within seconds.  However, this has further implications for automation and reporting, because while HubSpot will update existing record values, it will not update any Active List, Workflows, Lead Scoring Rules, etc. to use the new values.

For example, if you have a Contact property called "Cake preference", one of the options may have had a Label of "Chocolate" and an Internal value of "CHOCCAKE".  Let's say you had this value chosen on a Contact called John Smith:

Let's say you also had an Active List that selects all members who like Chocolate cake:

Now let's say you needed to change the Internal value for "Chocolate" to "1234" to support an ID from another system in your integration:

After saving this update, and returning to your List, notice that even though John Smith technically still prefers Chocolate cake, he no longer appears on the List as a member:

(Also notice that the filter on the List has changed to the old Internal value of "CHOCCAKE".  This is one of the few times you will see the Internal value in common usage, and is an indicator that something needs to be updated.)

For the above reasons, LyntonWeb recommends the following course of action whenever making updates to an existing option inside a multiple-choice HubSpot property:

  1. If performed during working hours, notify your users that Active Lists, Forms, Views, Reports, Workflows or other automation may be temporarily inaccurate
  2. Update the Internal values on relevant HubSpot properties (this should cause the "Records with this value" number to reset to zero)
  3. Check all associated Active Lists, Forms, Views, etc. and correct them to use the updated value as necessary
  4. Wait for HubSpot to complete updating all records (when the "Records with this value" number returns to the previously seen number) and verify that data appears updated and correct in all areas