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

# Tags

> Adding, updating, filtering, and searching profile tags via the Omneo API.

Tags are flexible string arrays attached to profiles (and other Omneo objects like transactions, products, and interactions). They are invisible to end customers and are used to segment, filter, and annotate data for internal operational and integration purposes.

## Tag formatting

Omneo replaces spaces in tag values with hyphens. `"mobile app"` becomes `"mobile-app"`. Keep this in mind when writing tags programmatically or syncing them from an external system.

## Adding tags when creating a profile

Pass a `tags` array in the create profile request body:

```shell theme={null}
curl -X POST https://api.[tenant].getomneo.com/api/v3/profiles \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Jane",
    "last_name": "Smith",
    "email": "jane@example.com",
    "tags": ["vip", "in-store-only"]
  }'
```

## Updating tags on an existing profile

<Warning>
  Tags are replaced as a complete array. To add a tag, you must provide the full existing array plus the new tag. Sending only the new tag will overwrite all existing tags.
</Warning>

```shell theme={null}
curl -X PUT https://api.[tenant].getomneo.com/api/v3/profiles/{profileId} \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "tags": ["vip", "in-store-only", "mobile-app"]
  }'
```

## Filtering profiles by tag

Use the `filter[tags.handle]` query parameter on the browse profiles endpoint:

```shell theme={null}
GET /api/v3/profiles?filter[tags.handle]=vip
```

To filter by multiple tags:

```shell theme={null}
GET /api/v3/profiles?filter[tags.handle]=vip&filter[tags.handle]=mobile-app
```

## Tags on other objects

Tags work the same way on other Omneo objects:

| Object      | Where to manage                                               |
| ----------- | ------------------------------------------------------------- |
| Profile     | CX Manager profile details tab, Clienteling edit profile, API |
| Transaction | CX Manager transaction details, API                           |
| Product     | CX Manager product details, API                               |
| Interaction | API only (viewable in CX Manager)                             |

## Common use cases

* Flag profiles for manual review (`"handle-with-care"`)
* Mark acquisition channel (`"instagram-campaign-2025"`)
* Identify high-value customer segments (`"whale"`, `"stylist-client"`)
* Track operational states (`"pending-merge"`, `"opted-out-direct-mail"`)