Skip to main content
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: 
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

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.
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: 
GET /api/v3/profiles?filter[tags.handle]=vip
To filter by multiple tags: 
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:
ObjectWhere to manage
ProfileCX Manager profile details tab, Clienteling edit profile, API
TransactionCX Manager transaction details, API
ProductCX Manager product details, API
InteractionAPI 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")