Create Segment

Create a new dynamic segment using MongoDB-style filter conditions.

Use Cases:

• Build audience segments for targeted campaigns
• Create customer cohorts based on behavior
• Segment by demographics or properties
• Identify high-value or at-risk contacts
• Automate audience targeting rules

Behavior:

• Segments are dynamic - membership updates automatically as contact data changes
• Conditions use MongoDB query syntax for flexible filtering
• Contact count is calculated and cached (updates periodically)
• Supports complex nested conditions with $and, $or, $not
• Can filter on any contact property (default or custom)
• Conditions are validated against property schemas

Required Scope: write:segments

Condition Operators:

• Comparison: $eq, $ne, $gt, $gte, $lt, $lte
• Arrays: $in, $nin
• Logical: $and, $or, $not
• Existence: $exists
• Text: $regex (for pattern matching)

Example Conditions:

{
  "$and": [
    { "country": { "$eq": "US" } },
    { "lifetime_value": { "$gte": 100 } },
    { "last_purchase_date": { "$gte": "2024-01-01" } }
  ]
}

Best Practices:

• Test conditions with /v1/contacts/search first
• Keep conditions simple for better performance
• Use indexed properties when possible
• Document segment purpose in description