Skip to main content

​
Attribute type

multiselect

​
Use it for

Multiple options from a configured list, such as tags, segments, or interests.

​
Request value

Send an array of option ID strings. 
{
  "fields": {
    "tags": [
      "field_option_vip",
      "field_option_partner"
    ]
  }
}

​
Returned shape

Returns an array of { "optionId", "value", "label", "color" } objects.

​
Example response

{
  "fields": {
    "tags": [
      {
        "optionId": "field_option_vip",
        "value": "vip",
        "label": "VIP",
        "color": "#F59E0B"
      },
      {
        "optionId": "field_option_partner",
        "value": "partner",
        "label": "Partner",
        "color": "#10B981"
      }
    ]
  }
}

​
Update behavior

When updating a multiselect field with records_update, the default behavior is append — provided options are added to any existing ones. To replace the entire set instead, pass "multiselectMode": "replace". 
{
  "fields": {
    "tags": [
      "field_option_vip"
    ]
  },
  "multiselectMode": "replace"
}
This replaces all existing tags with just VIP. Passing an empty array with "multiselectMode": "replace" clears the field.

​
Multiple values

Multi-select attributes always accept an array of option ID strings. 
{
  "fields": {
    "tags": [
      "field_option_vip",
      "field_option_partner"
    ]
  }
}
Returns an array of { "optionId", "value", "label", "color" } objects. 
{
  "fields": {
    "tags": [
      {
        "optionId": "field_option_vip",
        "value": "vip",
        "label": "VIP",
        "color": "#F59E0B"
      },
      {
        "optionId": "field_option_partner",
        "value": "partner",
        "label": "Partner",
        "color": "#10B981"
      }
    ]
  }
}