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

# Multi-Select

> Use multiselect attributes in the Breakcold API.

## 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.

```json theme={null}
{
  "fields": {
    "tags": [
      "field_option_vip",
      "field_option_partner"
    ]
  }
}
```

## Returned shape

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

## Example response

```json theme={null}
{
  "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"`.

```json theme={null}
{
  "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.

```json theme={null}
{
  "fields": {
    "tags": [
      "field_option_vip",
      "field_option_partner"
    ]
  }
}
```

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

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