Tags, lists & segments
Group contacts three ways — labels, fixed lists and live rules — and describe them with custom attributes. Campaign audiences are built from these.
- GET
/v1/tags→ { data: [{ id, name, color, contacts }] }contacts:read - POST
/v1/tags{ name, color }contacts:write - PATCH
/v1/tags/{id}contacts:write - DELETE
/v1/tags/{id}contacts:write - GET
/v1/listscontacts:read - POST
/v1/lists{ name, description }contacts:write - PATCH
/v1/lists/{id}contacts:write - DELETE
/v1/lists/{id}contacts:write - POST
/v1/lists/{id}/members{ contact_ids } → { added }contacts:write - DELETE
/v1/lists/{id}/members{ contact_ids } → { removed }contacts:write - GET
/v1/segmentscontacts:read - POST
/v1/segments{ name, rules }contacts:write - GET
/v1/segments/{id}Includes a fresh contact countcontacts:read - PATCH
/v1/segments/{id}contacts:write - DELETE
/v1/segments/{id}contacts:write - POST
/v1/segments/preview{ rules } → { count }contacts:read - GET
/v1/contact-attributescontacts:read - POST
/v1/contact-attributes{ key, label, kind, options }contacts:write - PATCH
/v1/contact-attributes/{id}{ label, options }contacts:write - DELETE
/v1/contact-attributes/{id}contacts:write
Tags
Tags are labels such as VIP or Diwali-2026. Contacts can carry many. Add them by name when creating a contact (missing tags are created), or by id with POST /v1/contacts/{id}/tags and POST /v1/contacts/bulk. Adding and removing tags fires contact.tag_added and contact.tag_removed.
Lists
Lists are fixed groups you manage yourself — for example, everyone who attended an event. Add and remove members by contact id; the CSV import can also put every imported contact into a list.
Segments
Segments are saved rules evaluated whenever they're used, so a campaign to a segment always reaches whoever matches at send time. Try rules with POST /v1/segments/preview before saving.
{
"name": "Engaged VIPs in Bengaluru",
"rules": {
"op": "and",
"conditions": [
{ "field": "tag", "operator": "in", "value": ["7f3a…"] },
{ "field": "attribute.city", "operator": "eq", "value": "Bengaluru" },
{ "field": "last_inbound_at", "operator": "within_days", "value": 30 }
]
}
}Custom attributes
Define the extra fields your contacts carry — city, plan, last order value — and fill them through attributes on the contact, CSV import (attribute.<key>) or automations. Up to 100 per organization.
{
"key": "tier",
"label": "Loyalty tier",
"kind": "enum",
"options": ["silver", "gold", "platinum"]
}kind is text, number, date, boolean or enum. The key can't be changed later.