Creating and using Tags
What are tags?
Tags are a flexible array kept against many Omneo features such as (but not limited to) Profiles, Transactions, Benefits, Rewards, Products and Locations.
Technically, tags are an array of strings stores within the object. They can be modified however you see fit.
Tags cannot be seen by end users, and provide a flexible way to search and identify data in Omneo.
Tags can be easily maintained via your CX Manager, for more info refer to our Helpcenter Creating and using tags
As developers, tags can be modified via the Omneo API directly utilising the API endpoint that handles your object. Tags can be added at the time of creation, and modified as part of the update method.
Tag Examples
| Type | Description |
|---|---|
| Customer Profiles | Can be used to assign a shared term or attribute to a profile. e.g."handle with care" or "likes green". Add, remove and view in CX manager profile details tab or in Clienteling "Edit Profile" tab. Read about Omneo Profiles here. |
| Transaction | Add tags to a transaction to assign a shared term or attribute to it. e.g. "American Express" or "late payment" or "fraudulent". Add, remove and view in CX managers transaction details. |
| Products | Add, remove and View tags for a product on its CX manager details page. e.g. "summer collection" |
| Product Variant | Add, remove and view Product variant level tags at API level only e.g. "size12" |
| Interaction | Add and remove interaction tags at API level - viewable in CX manager. e.g. "followup" |
Tag formatting.
Blank spaces in our tags are replaced with hyphens "-"
meaning "no shorts" becomes "no-shorts", and "mobile app" becomes "mobile-app"
Keep this in mind when setting tags.
A quick example using tags
In this example, we will be creating a new profile, and adding the tag "no-shorts"
We will then be updating the existing profile, and adding another tag "mobile-app"
This example customer, does not like shorts, and uses the brands mobile app.
these tags could be used at the storefront to give staff an insight into the customer to improve the customers experience.
This process can be summarised into the below steps:
- Create the customer profile (with tags)
- Modify the customer profile (add a new tag)
- Review the customer profile. (optional)
Create the customer profile.
We will be creating the profile just like any profile, using the Add Profile ](ref:profiles-1) endpoint.
Enter a similar payload to the below:
Tags are formatted in an array, for your example you can add as many tags as you like
{
"email": "[email protected]",
"first_name": "John",
"last_name": "Smithy",
"title": "Mr",
"gender": "male",
"mobile_phone": "+61401231331",
"tags": [
"no-shorts"
]
}
You've just created a profile with a single tag "no-shorts"
note down the profile_id returned in your response, you'll need it for the next step.
Modify the customer profile.
Using the Edit Profile endpoint we can update the existing profile, adding in the new tag
Be careful modifying tags!
When modifying the
tagsarray, you'll need to replace the entire array on the profile.
In our example, if we want to add a tag "mobile app", we need to provide the entire array
["no-shorts", "mobile-app"]for it to be replaced.
Providing just the new tag["mobile app"]will replace the tags array with one tag only.
Providing your profile_id to the endpoint, enter a similar payload to the below to modify your tags array.
{
"tags": [
"no-shorts",
"mobile-app"
]
}
After executing, your response will return the updated profile.
Review the customer profile.
The updated customer profile is already returned as part of the response in step 2.
This step is usually unnecessary. To finish up this process, we can read the profile to retrieve the profile in its final state using the Read Profile Attributes (Comms) endpoint.
Using the profile_id obtained in the previous steps, provide it to the endpoint, and read the profile.
This will display the latest profile data reflecting your new tags in Omneo.
{
"data": {
"id": "92e7e622-cf4e-4325-bd65-1feae955163d",
"external_id": null,
"title": "Mr",
"first_name": "John",
"last_name": "Smithy",
"full_name": "John Smithy",
"email": "[email protected]",
"gender": "male",
"currency": null,
"joined_at": "2021-03-08 00:00:00",
"mobile_phone": "+61401231331",
"mobile_phone_country": 61,
"mobile_phone_national": "401231331",
"mobile_phone_national_prefix": "0401231331",
"mobile_phone_e164": "+61401231331",
"secondary_phone": null,
"birth_year": null,
"birth_month": null,
"birth_day": null,
"company": null,
"occupation": null,
"avatar_url": null,
"preferred_location_id": null,
"joined_location_id": null,
"joined_location": null,
"preferred_location": null,
"tier_handle": "tier-1",
"tier": {
"id": 5,
"profile_id": "92e7e622-cf4e-4325-bd65-1feae955163d",
"name": "Tier 1",
"handle": "tier-1",
"anniversary_at": "2022-03-08 23:59:59",
"assigned_at": null,
"achieved_at": "2021-03-08 00:00:00"
},
"birth_date": null,
"birth_days": null,
"birth_days_past": null,
"next_birthday": null,
"identities": [],
"tags": [
"mobile-app",
"no-shorts"
],
"attributes": {
"comms": {
"profile_id": "92e7e622-cf4e-4325-bd65-1feae955163d",
"email_optout": false,
"push_optout": false,
"sms_optout": false,
"phone_optout": false,
"post_optout": false,
"email_bounced": false,
"push_bounced": false,
"sms_bounced": false,
"phone_bounced": false,
"post_bounced": false,
"sms_promo": false,
"push_promo": true,
"email_promo": true,
"phone_promo": false,
"post_promo": false,
"email_discover": true,
"email_benefits": true,
"email_reminders": true,
"email_account": true,
"email_bookings": true,
"email_feedback": true,
"email_location": false,
"email_service": true,
"sms_discover": false,
"sms_benefits": false,
"sms_reminders": true,
"sms_account": false,
"sms_bookings": true,
"sms_feedback": false,
"sms_location": false,
"sms_service": true,
"push_discover": true,
"push_benefits": true,
"push_reminders": true,
"push_account": true,
"push_bookings": true,
"push_feedback": true,
"push_location": true,
"push_service": true,
"phone_discover": true,
"phone_benefits": true,
"phone_reminders": true,
"phone_account": true,
"phone_bookings": true,
"phone_feedback": true,
"phone_location": true,
"phone_service": true,
"post_discover": true,
"post_benefits": true,
"post_reminders": true,
"post_account": true,
"post_bookings": true,
"post_feedback": true,
"post_location": true,
"post_service": true,
"email_verification": "not_sent",
"sms_verification": "not_sent",
"phone_verification": "not_sent",
"post_verification": "not_sent",
"terms_accepted_at": null,
"terms_accepted_version": null,
"created_at": "2021-03-08 23:42:41",
"updated_at": "2021-03-08 23:42:41"
},
"appearance": {
"profile_id": "92e7e622-cf4e-4325-bd65-1feae955163d",
"hair_colour": null,
"hair_length": null,
"shape_body": null,
"shape_face": null,
"size_cup": null,
"size_hat": null,
"size_formal_jacket": null,
"size_formal_jacket_length": null,
"size_formal_shirt": null,
"size_formal_shirt_fit": null,
"size_formal_trouser": null,
"size_formal_trouser_drop": null,
"size_formal_trouser_leg": null,
"size_jacket": null,
"size_pant": null,
"size_shoe": null,
"size_type_age": null,
"size_type_region": null,
"size_top": null,
"skin_type": null,
"measurement_arm": null,
"measurement_arm_inside": null,
"measurement_bust": null,
"measurement_chest": null,
"measurement_foot_length": null,
"measurement_head": null,
"measurement_height": null,
"measurement_hip": null,
"measurement_leg_inside": null,
"measurement_leg_outside": null,
"measurement_neck": null,
"measurement_neck_to_wrist": null,
"measurement_shoulders": null,
"measurement_waist": null,
"measurement_weight": null,
"created_at": "2021-03-08 23:42:41",
"updated_at": "2021-03-08 23:42:41"
},
"dates": []
},
"statuses": [],
"custom_attributes": [],
"address": null,
"addresses": [],
"created_at": "2021-03-08 23:42:41",
"updated_at": "2021-03-08 23:50:41",
"profile_type": null
}
}
Filtering using tags.
Did you know you can further refine the data returned in Browse Profiles?
by using the browse endpoint, append ?filter[tags.handle]=no-shorts to your url
this will only return profiles with tags matching "no-shorts"
{{baseUrl}}/profiles?filter[tags.handle]=no-shorts
To search multiple tags, keep appending additional filter:
?filter[tags.handle]=no-shorts&filter[tags.handle]=mobile-app
Gotchas
1. Replacing the entire array with a single tag.
As our tag updates replace the full array, the full replacement array must be provided when updating.
2. Tag not found?
If you sync tags between databases and Omneo, you may find some of your tags cannot be found.
This may occur if your tags contain spaces in your client system. Omneo uses hyphens instead of blank spaces. If you've used a blank space in a tag, check the tag as it sits in Omneo, or query the tag with a "-" instead of a space.
Updated about 3 years ago