Segments

Create segment

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
Email open tracking consent: emailOpenTrackingConsent (equals / notEquals with given, declined or unknown)
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.

<details id="example-combining-contact-and-event-conditions-and-logic"> <summary>Example: Combining contact and event conditions (AND logic)</summary> <br> <div style="padding-left: 1.5em;">

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. <br>

{
  "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.

</div> </details>

<details id="example-multiple-event-conditions-in-a-single-group"> <summary>Example: Multiple event conditions in a single group</summary> <br> <div style="padding-left: 1.5em;">

Multiple event conditions within the same group, with an OR junction on filters within one condition. <br>

{
  "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.

</div> </details>

<details id="example-multiple-condition-groups-or-logic"> <summary>Example: Multiple condition groups (OR logic)</summary> <br> <div style="padding-left: 1.5em;">

Demonstrates the OR relationship between different conditionGroups. A contact is included if they match any of the groups. <br>

{
  "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).

</div> </details>

<details id="example-filtering-by-contact-properties"> <summary>Example: Filtering by contact properties</summary> <br> <div style="padding-left: 1.5em;">

Common contact property filters, including text matching, subscription status, and location. <br>

{
  "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.

</div> </details>

<details id="example-filtering-by-birthday"> <summary>Example: Filtering by birthday</summary> <br> <div style="padding-left: 1.5em;">

Date-based filtering for birthdays, including date ranges, upcoming anniversaries, and month matching. <br>

{
  "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.

</div> </details>

<details id="example-lifecycle-stages-and-computed-metrics"> <summary>Example: Lifecycle stages and computed metrics</summary> <br> <div style="padding-left: 1.5em;">

Filtering contacts based on their RFM lifecycle stage and financial metrics like average order value. <br>

{
  "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.

</div> </details>

<details id="example-filtering-by-custom-fields"> <summary>Example: Filtering by custom fields</summary> <br> <div style="padding-left: 1.5em;">

Filtering by user-defined custom fields, which require an explicit valueType. <br>

{
  "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.

</div> </details>

<details id="example-behavioral-events-engagement"> <summary>Example: Behavioral events (engagement)</summary> <br> <div style="padding-left: 1.5em;">

Behavioral segmentation based on message engagement (clicks, opens) and page views. <br>

{
  "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).

</div> </details>

<details id="example-platform-event-property-filters"> <summary>Example: Platform event property filters</summary> <br> <div style="padding-left: 1.5em;">

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.
<br>

{
  "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.

</div> </details>

<details id="example-custom-event-property-filters"> <summary>Example: Custom event property filters</summary> <br> <div style="padding-left: 1.5em;">

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.
<br>

{
  "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.

</div> </details>

<details id="example-filtering-events-by-date-range"> <summary>Example: Filtering events by date range</summary> <br> <div style="padding-left: 1.5em;">

Filtering events using a specific date range with the between period operator. Uses valueFrom and valueTo to define the time window. <br>

{
  "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.

</div> </details>

<details id="example-filtering-events-by-exact-date"> <summary>Example: Filtering events by exact date</summary> <br> <div style="padding-left: 1.5em;">

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

{
  "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.

</div> </details>

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

post/segments

Request

Base URL
https://api.omnisend.com/api
URL
https://api.omnisend.com/api/segments
Auth
- OAuth 2
  Client credentials
  Token URL: https://app.omnisend.com/oauth2/token scopes: segments.write
- or API key in header Authorization

Headers

Omnisend-Versionstring required

API version that specifies the response format and behaviour (e.g., 2026-preview)

Request body

namestring required

Name of the segment

Example request

{
  "conditionGroups": [
    {
      "conditions": [
        {
          "entity": "contact",
          "junction": "and"
        }
      ]
    }
  ],
  "name": "My Segment"
}

Response

Created

archivedAtstring nullable

Segment archival timestamp, null if not archived (read-only)

createdAtstring

Segment creation timestamp (read-only)

isStarredboolean

Whether the segment is marked as a favourite

namestring

Segment name

segmentIDstring

Segment unique identifier (read-only)

status'ready' | 'building' | 'archived'

Segment processing status (read-only)

updatedAtstring

Segment last update timestamp (read-only)

Example response

{
  "archivedAt": "2026-06-01T00:00:00Z",
  "conditionGroups": [
    {
      "conditions": [
        {
          "entity": "contact",
          "junction": "and"
        }
      ]
    }
  ],
  "createdAt": "2026-01-15T10:30:00Z",
  "name": "VIP Customers",
  "segmentID": "000000000000000000000001",
  "status": "ready",
  "updatedAt": "2026-01-20T14:45:00Z"
}

Changes

No recorded changes to this operation across all 1 revision of this API.

Create segment

Segmentation examples

Event filter fields reference

Period operators

Relative periods

Absolute periods

Contact filter properties reference

Request

Headers

Request body

Example request

Response 201Created

Example response

Changes

Response