How to Bulk Edit Multi-Select Properties in HubSpot

Multi-select properties in HubSpot -- also called "multiple checkboxes" -- let you store multiple values on a single property. A contact can have "Interests" set to "Product A; Product B; Product C" simultaneously. An account can have "Compliance Certifications" set to "SOC 2; ISO 27001; HIPAA."

This flexibility makes multi-select properties popular for tagging, categorization, and tracking attributes that are not mutually exclusive. But that same flexibility makes them one of the hardest property types to edit in bulk. HubSpot's native bulk edit overwrites the entire selection, CSV imports require precise formatting, and the API demands you understand the semicolon-separated value format.

This guide explains how multi-select properties work internally and walks through every method for updating them across many records.

How multi-select values are stored

Internally, HubSpot stores multi-select property values as a semicolon-separated string. If a contact has three interests selected, the stored value looks like this:

product_a;product_b;product_c

Note that the stored value uses the internal value of each option, not the display label. If your option is labeled "Product A" in the UI, its internal value might be product_a or Product A depending on how it was created. You can check internal values by going to Settings > Properties, finding the property, and looking at the option list.

This semicolon-separated format has important implications:

• When you read a multi-select value via export or API, you get the full semicolon-separated string.
• When you write a value, you need to send the complete semicolon-separated string of all options you want selected. The API and import both use a replacement model, not an additive one.
• There is no native "add this option to the existing selection" or "remove this option from the existing selection" operation. You always set the complete list.

The challenge with bulk editing

Because multi-select properties use the replacement model, bulk editing them is tricky.

Adding an option. If you want to add "Product D" to every contact who currently has "Product A; Product B," you cannot simply say "add Product D." You need to read each contact's current value, append ";product_d" to it, and write the full new value back. Each contact might have a different starting set of options, so the result is different for each record.

Removing an option. Similarly, removing "Product B" from everyone who has it requires reading each contact's value, removing the "product_b" portion, and writing the updated string back.

Replacing an option. If an option is being renamed (say "product_beta" to "product_b_v2"), you need to find it in the semicolon-separated string and replace it without disturbing the other options.

HubSpot's native bulk edit cannot do any of these things selectively. It can only replace the entire multi-select value with a new set of options -- which is only useful if you want every selected record to have the exact same options.

Method 1: HubSpot native bulk edit (limited)

From the CRM index page, select records, click Edit, choose the multi-select property, and select the options you want.

When this works:

• You want to set the exact same combination of options on every selected record. For example, setting "Compliance Certifications" to "SOC 2; ISO 27001" for a batch of newly onboarded accounts.

When this does not work:

• You want to add an option to existing selections without removing what is already there.
• You want to remove a single option from records that have varying selections.
• You want to change one option to another across records with different overall selections.

Record limit: 250 per operation.

Method 2: CSV export, modify, re-import

This is the most common workaround, and it works -- but it requires careful spreadsheet work.

Step 1: Export. Export the records you need to update. Make sure to include the multi-select property and the record ID in the export.

Step 2: Understand the format. In the exported CSV, multi-select values appear as semicolon-separated strings:

Record ID, Interests
12345, "product_a;product_b;product_c"
12346, "product_a;product_d"
12347, "product_b"

Step 3: Modify in a spreadsheet.

To add an option to every record, use a formula. In Google Sheets:

=IF(ISNUMBER(SEARCH("product_d", B2)), B2, B2 & ";product_d")

This checks if "product_d" is already in the string; if not, it appends it.

To remove an option, use a substitution formula:

=SUBSTITUTE(SUBSTITUTE(B2, "product_b;", ""), ";product_b", "")

This removes "product_b" whether it appears at the beginning, middle, or end of the string. You may need to handle the edge case where it is the only option (no semicolons).

To replace an option:

=SUBSTITUTE(B2, "product_beta", "product_b_v2")

Step 4: Clean up. After applying formulas, check for:

• Leading or trailing semicolons (e.g., ";product_a;product_c" after removing the first option)
• Double semicolons (e.g., "product_a;;product_c" after removing a middle option)
• Empty values (if you removed the only selected option)

These artifacts will cause import errors or create records with blank option labels.

Step 5: Re-import. Import the modified CSV, mapping the record ID for matching and the multi-select column to the correct property. HubSpot will overwrite the existing multi-select values with the values in your file.

Risks:

• Encoding issues can corrupt semicolons and option values. Excel is particularly problematic here -- it sometimes wraps semicolons in quotes or interprets them as delimiters.
• If someone updated a record's multi-select value between your export and import, your import will overwrite their change.
• No preview and no undo.

Method 3: Workflows

Workflows can set multi-select property values, but with the same limitation as bulk edit: they set the complete value, not individual options.

There is one useful workflow pattern for multi-select properties:

Adding an option based on criteria. You can use a workflow with a "Copy property" or "Set property" action combined with the "Format data" action (HubSpot Data Hub, formerly Operations Hub, Professional+) to append a value. The Format data action can concatenate strings, which lets you build a new multi-select value from the existing value plus a new option.

However, this is complex to set up, fragile if the existing value format is not exactly what you expect, and has no preview or rollback.

Method 4: HubSpot API

The API gives you full control but requires coding.

Reading current values:

GET /crm/v3/objects/contacts/{contactId}?properties=interests

Returns the current semicolon-separated value.

Updating values:

PATCH /crm/v3/objects/contacts/{contactId}
{
  "properties": {
    "interests": "product_a;product_b;product_d"
  }
}

A script to add an option to all records would:

1. Fetch all records with the property value
2. For each record, parse the semicolon-separated string
3. Add the new option if not already present
4. Write the updated string back

A script to remove an option would:

1. Fetch records where the property contains the target option (use a search filter with CONTAINS_TOKEN)
2. For each record, parse the string, remove the target option, rejoin
3. Write the updated string back

This works reliably but requires handling pagination, rate limiting, and edge cases (empty strings, duplicate options, whitespace).

Method 5: Search-and-replace

Because multi-select values are stored as semicolon-separated strings, a text-based search-and-replace can modify them directly.

Adding an option: You cannot purely "add" via search-and-replace since you need to target specific records. However, if you want to add an option to every record that has a specific existing option, you can search for that option and replace it with itself plus the new option:

• Search: product_a
• Replace: product_a;product_d

This works if "product_a" only appears as a complete option value (not as a substring of another option). Use exact-match or regex word boundaries to be precise.

Removing an option:

• Search (regex): product_b;? or ;?product_b
• Replace: (empty)

This removes the option and its adjacent semicolon. Regex gives you the precision to handle the option appearing at the beginning, middle, or end of the string.

Renaming an option:

• Search: product_beta
• Replace: product_b_v2

This is the simplest case. A substring search-and-replace on the property value handles the rename regardless of what other options are selected.

The advantage of using a search-and-replace tool for multi-select edits is that you can preview the before-and-after for every record. You see exactly how the semicolon-separated string will change, which lets you catch edge cases (like substring matches or formatting artifacts) before they are applied.

Best practices for multi-select properties

Use internal values that are distinct. If your options are "product_a", "product_ab", and "product_abc", substring operations become risky because "product_a" is a substring of the other two. Use distinct internal values that do not overlap.

Keep option lists manageable. Multi-select properties with 50+ options are hard to maintain and hard to use. If you find yourself with a massive option list, consider splitting the property into multiple more focused properties.

Document option values. Maintain a reference document that maps display labels to internal values. When you need to do a bulk edit, you will need the internal values, and they are not always obvious from the labels.

Validate after bulk changes. After any bulk update to multi-select properties, spot-check a sample of records in the HubSpot UI. Verify that the selections display correctly and that no artifacts (empty options, double semicolons) were introduced.

Consider the property settings. In the property settings, check whether the options list has been locked (preventing new options from being created via API or import). If locked, make sure any values you write match existing options exactly -- otherwise the update will fail silently or create unexpected behavior.

---

Multi-select properties are one of the most powerful property types in HubSpot and one of the most finicky to manage at scale. Understanding the semicolon-separated storage format and the replacement-only update model is the key to editing them successfully in bulk. Whether you use spreadsheets, API scripts, or a search-and-replace tool, always preview your changes and validate the results.