Segments

Create and manage user segments with include and exclude criteria for targeted campaigns

Segments allow you to create dynamic or static groups of users based on criteria such as tier, points, badges, custom fields, and more. Segments can be used in campaigns, rewards, and other loyalty mechanics to target specific user groups.

Overview

Segment Types:

• Dynamic: Automatically includes users matching criteria

• Static: Fixed list of user IDs

Key Features:

• Include AND Exclude clauses for precise targeting

• Support for multiple criteria (tier, points, badges, custom fields, dates)

• Used in campaigns, rewards, benefits, and quizzes

• Real-time segment evaluation

---

Endpoints

List Segments

GET /v1/segments

Retrieve all segments for your organization.

Query Parameters:

• limit (optional): Number of results (default: 50, max: 100)

• type (optional): Filter by type (static or dynamic)

Response:

{
  "success": true,
  "data": {
    "segments": [
      {
        "segmentId": "seg_abc123",
        "name": "VIP Gold Members",
        "description": "Gold tier users with 1000+ points, excluding test accounts",
        "type": "dynamic",
        "criteria": [
          {
            "field": "tier",
            "operator": "in",
            "value": ["gold", "platinum"]
          },
          {
            "field": "points",
            "operator": ">=",
            "value": 1000
          }
        ],
        "excludeCriteria": [
          {
            "field": "customFields.testAccount",
            "operator": "equals",
            "value": true
          },
          {
            "field": "badges",
            "operator": "contains",
            "value": ["banned", "suspended"]
          }
        ],
        "estimatedSize": 1250,
        "createdAt": "2025-10-01T10:00:00Z",
        "updatedAt": "2025-10-05T14:30:00Z"
      }
    ],
    "count": 1
  }
}

---

Create Segment

POST /v1/segments

Create a new user segment with include and exclude criteria.

Request Body:

{
  "name": "Engaged Users (Non-Test)",
  "description": "Active users with 500+ points, excluding test accounts and banned users",
  "type": "dynamic",
  "criteria": [
    {
      "field": "tier",
      "operator": "in",
      "value": ["silver", "gold", "platinum"]
    },
    {
      "field": "points",
      "operator": ">=",
      "value": 500
    },
    {
      "field": "customFields.emailVerified",
      "operator": "equals",
      "value": true
    }
  ],
  "excludeCriteria": [
    {
      "field": "customFields.testAccount",
      "operator": "equals",
      "value": true
    },
    {
      "field": "badges",
      "operator": "contains",
      "value": ["banned", "suspended", "inactive"]
    },
    {
      "field": "tier",
      "operator": "equals",
      "value": "bronze"
    }
  ],
  "url": "https://products.monterosa.co/experience/12345",
  "metadata": {
    "campaignId": "campaign_xyz",
    "description": "Segment for marketing campaign"
  }
}

Supported Operators:

• equals / not_equals

• in / not_in (for arrays)

• contains / not_contains (for string/array fields)

• >= / > / <= / < (for numeric fields)

• exists / not_exists (check field presence)

Common Fields:

• tier - User tier (bronze, silver, gold, platinum)

• points - Total points balance

• xp - Experience points

• coins - Coins balance

• badges - Array of badge IDs

• email - User email

• customFields.* - Any custom field (e.g., customFields.vip)

• createdAt - Account creation date

• updatedAt - Last profile update date

Optional Fields:

• url - Optional URL linking to external resource or campaign page (e.g., quiz, experience, landing page). This field is purely informational and not used in segment evaluation.

Response (201 Created):

{
  "success": true,
  "data": {
    "segmentId": "seg_abc123",
    "name": "Engaged Users (Non-Test)",
    "description": "Active users with 500+ points, excluding test accounts and banned users",
    "type": "dynamic",
    "criteria": [...],
    "excludeCriteria": [...],
    "url": "https://products.monterosa.co/experience/12345",
    "estimatedSize": 0,
    "createdAt": "2025-10-06T10:00:00Z",
    "updatedAt": "2025-10-06T10:00:00Z"
  }
}

---

Get Segment

GET /v1/segments/{segmentId}

Retrieve details of a specific segment.

Response:

{
  "success": true,
  "data": {
    "segmentId": "seg_abc123",
    "name": "VIP Gold Members",
    "description": "Gold tier users with 1000+ points",
    "type": "dynamic",
    "criteria": [...],
    "excludeCriteria": [...],
    "estimatedSize": 1250,
    "createdAt": "2025-10-01T10:00:00Z",
    "updatedAt": "2025-10-05T14:30:00Z",
    "metadata": {}
  }
}

---

Update Segment

PUT /v1/segments/{segmentId}

Update an existing segment's criteria, name, or description.

Request Body:

{
  "name": "Updated Segment Name",
  "description": "Updated description",
  "criteria": [...],
  "excludeCriteria": [...],
  "estimatedSize": 1500,
  "metadata": {
    "updated": true
  }
}

Response:

{
  "success": true,
  "data": {
    "segmentId": "seg_abc123",
    "name": "Updated Segment Name",
    ...
  }
}

---

Delete Segment

DELETE /v1/segments/{segmentId}

Delete a segment. Note: This will not affect campaigns or rules currently using this segment.

Response:

{
  "success": true,
  "data": {
    "message": "Segment deleted successfully"
  }
}

---

Using Segments in Campaigns

Segments can be referenced in campaign rules to target specific user groups.

Example Campaign with Segment:

{
  "name": "VIP Bonus Campaign",
  "rules": [
    {
      "trigger": "video_watched",
      "conditions": [
        {
          "type": "user_in_segment",
          "segmentId": "seg_abc123"
        }
      ],
      "effects": [
        {
          "type": "add_points",
          "amount": 100,
          "currency": "points"
        }
      ]
    }
  ]
}

---

Include vs Exclude Logic

Include Criteria (AND logic)

Users must match ALL include criteria to be in the segment.

Example: "Gold OR Platinum tier AND 1000+ points"

{
  "criteria": [
    { "field": "tier", "operator": "in", "value": ["gold", "platinum"] },
    { "field": "points", "operator": ">=", "value": 1000 }
  ]
}

Exclude Criteria (AND logic with NOT)

Users matching ANY exclude criteria are removed from the segment.

Example: "NOT bronze tier AND NOT banned"

{
  "excludeCriteria": [
    { "field": "tier", "operator": "equals", "value": "bronze" },
    { "field": "badges", "operator": "contains", "value": ["banned"] }
  ]
}

Combined Example

Segment: "Engaged VIPs (excluding test accounts)"

{
  "name": "Engaged VIPs",
  "type": "dynamic",
  "criteria": [
    {
      "field": "tier",
      "operator": "in",
      "value": ["gold", "platinum"]
    },
    {
      "field": "points",
      "operator": ">=",
      "value": 1000
    },
    {
      "field": "customFields.emailVerified",
      "operator": "equals",
      "value": true
    }
  ],
  "excludeCriteria": [
    {
      "field": "customFields.testAccount",
      "operator": "equals",
      "value": true
    },
    {
      "field": "customFields.isEmployee",
      "operator": "equals",
      "value": true
    },
    {
      "field": "badges",
      "operator": "contains",
      "value": ["banned", "suspended"]
    }
  ]
}

Logic: (Gold OR Platinum) AND (Points >= 1000) AND (Email Verified) AND NOT (Test Account) AND NOT (Employee) AND NOT (Banned or Suspended)

---

Common Use Cases

1. Reward High-Value Non-Test Users

{
  "name": "High Value Customers",
  "criteria": [
    { "field": "points", "operator": ">=", "value": 5000 }
  ],
  "excludeCriteria": [
    { "field": "customFields.testAccount", "operator": "equals", "value": true },
    { "field": "email", "operator": "contains", "value": "@test.com" }
  ]
}

2. Re-engagement Campaign (Inactive Users)

{
  "name": "Inactive Users",
  "criteria": [
    { "field": "tier", "operator": "in", "value": ["silver", "gold"] },
    { "field": "updatedAt", "operator": "<", "value": "2025-09-01T00:00:00Z" }
  ],
  "excludeCriteria": [
    { "field": "badges", "operator": "contains", "value": ["recently_active"] }
  ]
}

3. Quiz Eligibility (First-time Participants)

{
  "name": "Quiz First-Timers",
  "criteria": [
    { "field": "tier", "operator": "not_equals", "value": "bronze" }
  ],
  "excludeCriteria": [
    { "field": "customFields.completedQuiz", "operator": "equals", "value": true },
    { "field": "badges", "operator": "contains", "value": ["quiz_master"] }
  ]
}

4. Premium Benefits (Paid Members Only)

{
  "name": "Premium Members",
  "criteria": [
    { "field": "tier", "operator": "in", "value": ["gold", "platinum"] },
    { "field": "customFields.subscriptionActive", "operator": "equals", "value": true }
  ],
  "excludeCriteria": [
    { "field": "customFields.freeTrialUser", "operator": "equals", "value": true }
  ]
}

---

Segment Evaluation

Dynamic Segments

• Evaluated in real-time when used in campaigns/rules

• User membership can change as their profile updates

• No manual refresh required

Static Segments

• Fixed list of user IDs

• Must be manually updated via API

• Useful for one-time campaigns or manual selections

Estimated Size

The estimatedSize field represents an approximation of users matching the segment criteria:

• For Dynamic Segments: Calculated periodically (not real-time) by querying user profiles matching the criteria. This is an estimate and may not reflect the exact current count.

• For Static Segments: Equals the number of user IDs in the segment's fixed list.

• Initial Value: Set to 0 when a segment is first created. Updated during background processing.

• Update Frequency: Refreshed periodically (typically every few hours) for dynamic segments.

• Use Case: Useful for campaign planning and understanding segment reach, but should not be relied upon for exact counts.

Note: For real-time, exact user counts, use the Audience API's search endpoint with the same criteria.

Performance Considerations

• Segments with many criteria may take longer to evaluate

• Use indexed fields (tier, points, userId) when possible

• Limit to 10 criteria per segment for optimal performance

• Consider caching segment results for high-traffic campaigns

---

API Limits

Operation	Limit
Segments per organization	1,000
Criteria per segment	20
Exclude criteria per segment	20
Users per static segment	100,000

---

Error Responses

400 Bad Request:

{
  "success": false,
  "error": {
    "message": "Validation failed",
    "errors": [
      "criteria is required for dynamic segments",
      "Invalid operator for field 'tier': must be one of [equals, in, not_in]"
    ]
  }
}

404 Not Found:

{
  "success": false,
  "error": {
    "message": "Segment not found"
  }
}

---

Related APIs

• Campaigns API - Use segments in campaign targeting

• Rules API - Reference segments in rule conditions

• Audience API - Search users with include/exclude filters

---

Support

For questions about segments:

• Documentation: https://products.monterosa.co/mic/reference

• Support: [email protected]