Creates a new segment.
Scopes:
segments.write
Rate Limiting: This endpoint is rate limited to 15 requests per minute.
Segmentation examples
This section provides a deeper technical reference for building complex segments using the API segment model.
Example: Combining contact and event conditions (AND logic)
Shows how to combine different entity types (contact and event) within a single group. AND logic is automatically inferred between multiple conditions inside the conditions array.
{
"name": "Combining Contact and Event Conditions",
"conditionGroups": [
{
"conditions": [
{
"entity": "contact",
"junction": "and",
"filters": [
{ "operator": "anyOf", "property": "country", "value": ["US"] },
{
"channels": ["email"],
"operator": "equals",
"property": "subscriptionStatus",
"value": "subscribed"
}
]
},
{
"entity": "event",
"junction": "and",
"filters": [
{
"count": "atLeast",
"name": "opened message",
"operator": "has",
"origin": "omnisend",
"period": { "operator": "inTheLast", "unit": "days", "value": 7 },
"value": 1
}
]
}
]
}
]
}Target audience: Contacts who are from the US and subscribed to the email channel, AND who have opened at least one message in the last 7 days.
Example: Multiple event conditions in a single group
Multiple event conditions within the same group, with an OR junction on filters within one condition.
{
"name": "Multiple Event Conditions in a Group",
"conditionGroups": [
{
"conditions": [
{
"entity": "event",
"junction": "and",
"filters": [
{
"count": "atLeast",
"name": "opened message",
"operator": "has",
"origin": "omnisend",
"period": { "operator": "inTheLast", "unit": "days", "value": 7 },
"value": 1
}
]
},
{
"entity": "event",
"junction": "or",
"filters": [
{
"count": "atLeast",
"name": "clicked message",
"operator": "has",
"origin": "omnisend",
"value": 1
},
{
"count": "equals",
"name": "marked message as spam",
"operator": "has",
"origin": "omnisend",
"value": 0
}
]
},
{
"entity": "contact",
"junction": "and",
"filters": [
{ "operator": "anyOf", "property": "country", "value": ["US"] }
]
}
]
}
]
}Target audience: Contacts from the US who have opened a message in the last 7 days, AND who have either clicked a message OR have never marked a message as spam.
Example: Multiple condition groups (OR logic)
Demonstrates the OR relationship between different conditionGroups. A contact is included if they match any of the groups.
{
"name": "Multiple Condition Groups",
"conditionGroups": [
{
"conditions": [
{
"entity": "contact",
"junction": "and",
"filters": [
{ "operator": "anyOf", "property": "tags", "value": ["vip"] }
]
},
{
"entity": "event",
"junction": "and",
"filters": [
{
"count": "atLeast",
"name": "placed order",
"operator": "has",
"origin": "shopify",
"value": 1
}
]
}
]
},
{
"conditions": [
{
"entity": "contact",
"junction": "or",
"filters": [
{ "operator": "anyOf", "property": "country", "value": ["US"] },
{
"channels": ["email"],
"operator": "equals",
"property": "subscriptionStatus",
"value": "subscribed"
}
]
}
]
}
]
}Target audience: Contacts who are either (tagged as "vip" AND have placed at least one Shopify order) OR (are from the US OR are subscribed to the email channel).
Example: Filtering by contact properties
Common contact property filters, including text matching, subscription status, and location.
{
"name": "Contact Property Filters",
"conditionGroups": [
{
"conditions": [
{
"entity": "contact",
"junction": "and",
"filters": [
{ "operator": "anyOf", "property": "firstName", "value": ["Jane", "John"] },
{ "operator": "contains", "property": "lastName", "value": ["Smith"] },
{
"channels": ["email", "browserPush", "sms"],
"operator": "equals",
"property": "subscriptionStatus",
"value": "subscribed"
},
{ "operator": "anyOf", "property": "tags", "value": ["vip"] },
{ "operator": "noneOf", "property": "tags", "value": ["excluded"] },
{ "operator": "anyOf", "property": "country", "value": ["US"] },
{ "operator": "doesNotExist", "property": "postalCode" }
]
},
{
"entity": "contact",
"junction": "or",
"filters": [
{ "operator": "anyOf", "property": "gender", "value": ["f"] },
{ "operator": "anyOf", "property": "lastDetectedCity", "value": ["New York"] }
]
}
]
}
]
}Target audience: Contacts who match all the primary criteria (named Jane/John Smith, subscribed on all channels, tagged "vip", not tagged "excluded", from US, no zip code) AND who are also either female OR located in New York.
Example: Filtering by birthday
Date-based filtering for birthdays, including date ranges, upcoming anniversaries, and month matching.
{
"name": "Birthday Filters",
"conditionGroups": [
{
"conditions": [
{
"entity": "contact",
"junction": "or",
"filters": [
{
"operator": "between",
"property": "birthday",
"valueFrom": "2000-01-01",
"valueTo": "2005-01-15",
"valueType": "date"
},
{
"operator": "anniversaryIsInTheNext",
"property": "birthday",
"unit": "days",
"value": 7,
"valueType": "date"
},
{
"operator": "contains",
"property": "birthday",
"value": ["-05-"],
"valueType": "text"
}
]
}
]
}
]
}Target audience: Contacts whose birth date falls between January 1, 2000 and January 15, 2005, OR whose birthday anniversary is in the next 7 days, OR whose birthday is in the month of May.
Example: Lifecycle stages and computed metrics
Filtering contacts based on their RFM lifecycle stage and financial metrics like average order value.
{
"name": "Lifecycle and Metrics",
"conditionGroups": [
{
"conditions": [
{
"entity": "contact",
"junction": "and",
"filters": [
{
"property": "customerLifecycleStage",
"operator": "anyOf",
"value": ["champions", "loyalists", "highPotential"]
},
{ "operator": "moreThan", "property": "averageOrderValue", "value": 50 },
{ "operator": "between", "property": "totalSpent", "valueFrom": 100, "valueTo": 500 }
]
}
]
}
]
}Target audience: High-value contacts (Champions, Loyalists, or High Potential) with an average order value over 50 and a total lifetime spend between 100 and 500.
Example: Filtering by custom fields
Filtering by user-defined custom fields, which require an explicit valueType.
{
"name": "Custom Field Filters",
"conditionGroups": [
{
"conditions": [
{
"entity": "contact",
"junction": "and",
"filters": [
{ "name": "is_vip", "operator": "equals", "property": "custom", "value": true, "valueType": "bool" },
{ "name": "favorite_category", "operator": "anyOf", "property": "custom", "value": ["Electronics"], "valueType": "text" },
{ "name": "lifetime_orders", "operator": "moreThan", "property": "custom", "value": 5, "valueType": "number" },
{
"name": "first_purchase_date",
"operator": "inTheLast",
"property": "custom",
"unit": "days",
"value": 30,
"valueType": "date"
}
]
}
]
}
]
}Target audience: Contacts who are marked as VIP in custom fields, whose favorite category is Electronics, who have more than 5 lifetime orders, and who made their first purchase in the last 30 days.
Example: Behavioral events (engagement)
Behavioral segmentation based on message engagement (clicks, opens) and page views.
{
"name": "Behavioral Engagement",
"conditionGroups": [
{
"conditions": [
{
"entity": "event",
"junction": "and",
"filters": [
{
"count": "atLeast",
"name": "clicked message",
"operator": "has",
"origin": "omnisend",
"value": 1
},
{
"count": "atLeast",
"name": "opened message",
"operator": "has",
"origin": "omnisend",
"period": { "operator": "inTheLast", "unit": "days", "value": 7 },
"value": 1
},
{
"count": "equals",
"name": "marked message as spam",
"operator": "has",
"origin": "omnisend",
"period": { "operator": "before", "value": "2026-01-13" },
"value": 0
},
{
"count": "atLeast",
"name": "viewed page",
"origin": "omnisend",
"operator": "has",
"period": { "operator": "inTheLast", "unit": "months", "value": 1 },
"value": 1
}
]
}
]
}
]
}Target audience: Contacts who have clicked a message, opened a message in the last 7 days, viewed a page in the last month, AND have never marked a message as spam (prior to Jan 13, 2026).
Example: Platform event property filters
Deep filtering on properties of platform-defined events, such as Shopify order details.
Note: Use the
[]wildcard syntax to match any element within an array. This can be chained for nested arrays; for example,raw.fulfillments.[].line_items.[].titlematches any line item title within any fulfillment in the order.
Important: When using events defined by other platforms (e.g., Shopify, Omnisend), you must use predefined event names and their specific properties. Filter values must strictly match the predefined
valueTypefor each property.
{
"name": "Platform Event Filters",
"conditionGroups": [
{
"conditions": [
{
"entity": "event",
"junction": "and",
"filters": [
{
"count": "atLeast",
"name": "placed order",
"operator": "has",
"origin": "shopify",
"value": 1,
"filters": [
{ "operator": "moreThan", "property": "raw._total_price", "value": 50 },
{ "operator": "contains", "property": "raw.fulfillments.[].line_items.[].title", "value": ["Book"] }
],
"junction": "and"
}
]
}
]
}
]
}Target audience: Contacts who have placed at least one Shopify order where the total price was over 50 AND the order contained an item with "Book" in the title.
Example: Custom event property filters
Filtering custom events based on their specific properties.
Important: Mandatory
valueTypemust be provided for every property filter (e.g.,text,number). The event and its properties must have been sent at least once before they can be used in a segment filter.
{
"name": "Custom Event Filters",
"conditionGroups": [
{
"conditions": [
{
"entity": "event",
"junction": "and",
"filters": [
{
"count": "atLeast",
"name": "app_feature_used",
"origin": "my_mobile_app",
"operator": "has",
"value": 5,
"junction": "and",
"filters": [
{
"operator": "equals",
"property": "feature_name",
"value": ["dark_mode_toggle"],
"valueType": "text"
},
{
"operator": "moreThan",
"property": "session_duration",
"value": 120,
"valueType": "number"
}
]
}
]
}
]
}
]
}Target audience: Contacts who have used the "dark_mode_toggle" feature in the custom "my_mobile_app" at least 5 times, where the session duration was greater than 120 seconds.
Example: Filtering events by date range
Filtering events using a specific date range with the between period operator. Uses valueFrom and valueTo to define the time window.
{
"name": "Shopify Orders in Date Range",
"conditionGroups": [
{
"conditions": [
{
"entity": "event",
"junction": "and",
"filters": [
{
"count": "atLeast",
"name": "placed order",
"operator": "has",
"origin": "shopify",
"value": 1,
"period": {
"operator": "between",
"valueFrom": "2025-01-01",
"valueTo": "2025-01-31"
},
"filters": [
{
"operator": "contains",
"property": "raw.line_items.[].title",
"value": ["Summer T-Shirt"],
"valueType": "text"
}
],
"junction": "and"
}
]
}
]
}
]
}Target audience: Contacts who placed at least one Shopify order between January 1 and January 31, 2025, where the order contained an item with "Summer T-Shirt" in the title.
- Events and Properties Reference — Explore available event names and properties to build powerful segment filters.