---
title: "Create segment"
method: POST
path: "/segments"
tags: ["Segments"]
---
# Create segment
`POST /segments`
## Request
- Base URL: `https://api.omnisend.com/api`
- URL: `https://api.omnisend.com/api/segments`
- Auth: one of:
- OAuth 2
- Client credentials
- Token URL: `https://app.omnisend.com/oauth2/token` scopes: `segments.write`
- API key in header `Authorization`
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.
---
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.
```json
{
"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.
```json
{
"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.
```json
{
"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.
```json
{
"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.
```json
{
"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.
```json
{
"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`.
```json
{
"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.
```json
{
"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.
```json
{
"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.
```json
{
"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.
```json
{
"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.
```json
{
"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](/docs/segments-events-properties) — Explore available event names and properties to build powerful segment filters.
## Headers
- `Omnisend-Version` string, required
## Request body
- CreateSegmentRequest: Request body for creating a new segment.
- `conditionGroups` SegmentConditionGroup[], required: Condition groups defining the segment rules
- `conditions` SegmentCondition[]: List of conditions in this group
- `entity` string: Entity type this condition applies to
- `filters` unknown[], required: List of filter criteria. Must contain at least one item.
- unknown
- `junction` string: Logical operator combining the filters within this condition
- `name` string, required: Name of the segment
## Response `201`
Created
- GetSegmentResponse: Segment resource representation.
- `archivedAt` string, nullable: Segment archival timestamp, null if not archived (read-only)
- `conditionGroups` SegmentConditionGroup[]: Condition groups defining the segment rules
- `conditions` SegmentCondition[]: List of conditions in this group
- `entity` string: Entity type this condition applies to
- `filters` unknown[], required: List of filter criteria. Must contain at least one item.
- unknown
- `junction` string: Logical operator combining the filters within this condition
- `createdAt` string: Segment creation timestamp (read-only)
- `isStarred` boolean: Whether the segment is marked as a favourite
- `name` string: Segment name
- `segmentID` string: Segment unique identifier (read-only)
- `status` 'ready' | 'building' | 'archived': Segment processing status (read-only)
- `updatedAt` string: Segment last update timestamp (read-only)
## Other responses
- `400`: Invalid request body or validation failed
- `401`: Authentication is missing or invalid
- `403`: Insufficient permissions for this operation
- `410`: API version has been retired
- `429`: Rate limit exceeded
- `500`: Unexpected error occurred
---
[API](https://skmtc.dev/omnisend/apis/segments-api.md) - [All operations](https://skmtc.dev/omnisend/apis/segments-api/llms.txt) - [OpenAPI document](https://skmtc.dev/omnisend/apis/segments-api/revisions/5d5cfb339623?raw)