Create segment

post

https://api.omnisend.com/api/segments

Creates a new segment.

Scopes:
segments.write

Rate Limiting:
This endpoint is rate limited to 15 requests per minute.

Segmentation examples

Event filter fields reference

For entity: "event" conditions, each filter in the filters array supports the following fields:

Field	Required	Description
`name`	Yes	Event name (e.g., `"placed order"`, `"opened message"`)
`operator`	Yes	`has` or `hasNot`
`count`	Yes	`atLeast` or `equals`
`value`	Yes	Integer threshold (e.g., `1`)
`origin`	No	Event source (e.g., `"shopify"`, `"omnisend"`). See the `origin` note below.
`period`	No	Time window — see period operators below
`filters`	No	Array of property sub-filters on the event payload
`junction`	No	`and` or `or` — logical operator for `filters`

origin is usually optional. Most events belong to a single origin, so the API resolves it for you.
You only need to specify origin when an event exists under multiple origins — otherwise the API returns an error with the list of valid values to choose from.

Period operators

The period object is optional on every event filter. When omitted, the filter matches across all time.

Relative periods

Use value (positive integer) + unit (days | weeks | months | years).

`operator`	Meaning	Example JSON
`inTheLast`	Event occurred within the last N units	`{ "operator": "inTheLast", "unit": "days", "value": 7 }`
`notInTheLast`	Event did not occur within the last N units	`{ "operator": "notInTheLast", "unit": "months", "value": 3 }`

Absolute periods

Use ISO 8601 date strings (YYYY-MM-DD).

`operator`	Meaning	Example JSON
`equals`	Event occurred on an exact date	`{ "operator": "equals", "value": "2026-01-13" }`
`before`	Event occurred before a date (exclusive)	`{ "operator": "before", "value": "2026-01-13" }`
`after`	Event occurred after a date (exclusive)	`{ "operator": "after", "value": "2026-04-01" }`
`between`	Event occurred within a date range (inclusive)	`{ "operator": "between", "valueFrom": "2025-01-01", "valueTo": "2025-01-31" }`

Contact filter properties reference

For entity: "contact" conditions, valid property values are:

Text: email, phoneNumber, firstName, lastName, gender, country, state, city, address, postalCode, lastDetectedCity, lastDetectedCountry, customerLifecycleStage
List: tags, consent
Number: averageOrderValue, totalSpent
Date: dateAdded
Subscription status: subscriptionStatus
Variadic: birthday (valueType can be date or text), custom (valueType can be text, number, bool, or date)

Important:

Use tags (plural), not tag.

When property is custom, provide both name and valueType.

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", "Canada"] },
            {
              "channels": ["email"],
              "operator": "equals",
              "property": "subscriptionStatus",
              "value": "subscribed"
            }
          ]
        },
        {
          "entity": "event",
          "junction": "and",
          "filters": [
            {
              "count": "atLeast",
              "name": "opened message",
              "operator": "has",
              "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",
              "period": { "operator": "inTheLast", "unit": "days", "value": 7 },
              "value": 1
            }
          ]
        },
        {
          "entity": "event",
          "junction": "or",
          "filters": [
            {
              "count": "atLeast",
              "name": "clicked message",
              "operator": "has",
              "value": 1
            },
            {
              "count": "equals",
              "name": "marked message as spam",
              "operator": "has",
              "value": 0
            }
          ]
        },
        {
          "entity": "contact",
          "junction": "and",
          "filters": [
            { "operator": "anyOf", "property": "country", "value": ["US", "Mexico"] }
          ]
        }
      ]
    }
  ]
}

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", "imported"] }
          ]
        },
        {
          "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", "Canada"] },
            {
              "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", "Canada"] },
            { "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",
              "value": 1
            },
            {
              "count": "atLeast",
              "name": "opened message",
              "operator": "has",
              "period": { "operator": "inTheLast", "unit": "days", "value": 7 },
              "value": 1
            },
            {
              "count": "equals",
              "name": "marked message as spam",
              "operator": "has",
              "period": { "operator": "before", "value": "2026-01-13" },
              "value": 0
            }
          ]
        }
      ]
    }
  ]
}

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.[].title matches 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 valueType for 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 valueType must 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.

Example: Filtering events by exact date

Filtering contacts who did not view a page on a specific date using the equals period operator.

{
  "name": "Did Not View Page on April 13",
  "conditionGroups": [
    {
      "conditions": [
        {
          "entity": "event",
          "junction": "and",
          "filters": [
            {
              "count": "atLeast",
              "name": "viewed page",
              "operator": "hasNot",
              "value": 1,
              "period": {
                "operator": "equals",
                "value": "2026-04-13"
              }
            }
          ]
        }
      ]
    }
  ]
}

Target audience: Contacts who did not view a page on April 13, 2026.

Events and Properties Reference — Explore available event names and properties to build powerful segment filters.

Responses

201Created

400Invalid request body or validation failed

401Authentication is missing or invalid

403Insufficient permissions for this operation

410API version has been retired

429Rate limit exceeded

500Unexpected error occurred