Segments

Intro

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

Segments allow you to group contacts based on specific criteria such as contact properties, behaviors, or events.

Segment Status

When retrieving a segment, the status field indicates its current state.

Note: Updating a segment's conditions triggers an automatic rebuild — the status changes to building until the new contact set is calculated.

Segment Structure

Segments use a hierarchical condition structure:

Segment
└── conditionGroups[]      (OR logic between groups)
    └── conditions[]       (AND logic within a group)
        └── filters[]      (conditions for matching)

Multiple condition groups are combined with OR logic. Within a single group, conditions are combined with AND logic.

Entity Types

Each condition targets a specific entity type.

Junction Values

The junction field controls how filters within a condition are combined.

Operators

For event conditions, use has (event occurred) or hasNot (event did not occur).

Note: The between operator requires both valueFrom and valueTo. Date slider operators (inTheLast, notInTheLast, anniversaryIsInTheNext) require both value and unit.

Value Types

Date Units

For time-based operators (inTheLast, notInTheLast, anniversaryIsInTheNext), specify a unit:

Contact Properties

Common properties for contact entity conditions:

Note: When using custom property, specify the custom property name in the name field and the value type in valueType. The name field is required even when using exists or doesNotExist.

Subscription Status Values

When filtering by subscriptionStatus, use the equals or notEquals operator and combine with channels to specify which communication channels:

Channels

Customer Lifecycle Stages

When filtering by customerLifecycleStage (RFM segments):

Event Conditions

Event conditions filter contacts based on their activity. Use the has or hasNot operator in the filter.

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.

Note: You can only segment on events that have been recorded at least once for your brand.

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

Absolute periods

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

Limits

Examples

For complete segment creation examples, see the Create segment endpoint documentation:

• Combining contact and event conditions (AND logic)
• Multiple event conditions in a single group
• Multiple condition groups (OR logic)
• Filtering by contact properties
• Filtering by birthday
• Lifecycle stages and computed metrics
• Filtering by custom fields
• Behavioral events (engagement)
• Platform event property filters
• Custom event property filters
• Filtering events by date range
• Filtering events by exact date

See Also

• Errors & responses
• Pagination
• Sorting