Segments API

יצירה וניהול של סגמנטים דינמיים בצורה תכנותית.

כל נקודות הקצה בעמוד זה יחסיות לכתובת הבסיס: https://api-eu1.joryio.com - ראו סקירת API.

אימות

כל הבקשות דורשות אימות עם מפתח API:

Authorization: Bearer jry_live_your_api_key_here
Content-Type: application/json

Create Segment

יצירת סגמנט משתמשים חדש עם מסננים.

Endpoint

POST /segments

גוף בקשה

שדה	סוג	חובה	תיאור
`name`	string	כן	שם הסגמנט (עד 255 תווים)
`description`	string	לא	תיאור הסגמנט (עד 1000 תווים)
`filterGroups`	array	כן	מערך קבוצות מסננים (עד 20)
`excludeFilterGroups`	array	לא	משתמשים שתואמים לאחת מהקבוצות האלו מוסרים (עד 20)
`groupOperator`	string	כן	איך לשלב קבוצות: `AND` או `OR`
`tags`	array	לא	שמות תגיות לארגון הסגמנטים

מבנה מסננים

כל קבוצת מסננים כוללת עד 50 מסננים:

{
  filters: [
    {
      type: 'attribute' | 'default_attribute' | 'event' | 'ecommerce'
          | 'behavioral' | 'segment' | 'canvas_execution'
          | 'list_membership' | 'channel_subscription' | 'app'
          | 'entity' | 'bounce_status' | 'wallet_pass',
      field?: string,           // For attribute filters
      operator: string,         // See Filter Operators below
      value?: any,              // Comparison value (also carries N for count operators)
      eventName?: string,       // For event filters
      withinDays?: number,      // Time window for event filters
      startDate?: string,       // Absolute window start (ISO 8601, event filters)
      endDate?: string,         // Absolute window end (ISO 8601, event filters)
      segmentId?: string,       // For segment filters
      listId?: string,          // For list_membership filters
      channel?: string          // For channel_subscription filters
    }
  ],
  operator: 'AND' | 'OR'
}

דוגמת בקשה - מסנן מאפיין פשוט

curl -X POST https://api-eu1.joryio.com/segments \
  -H "Authorization: Bearer jry_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Premium Users",
    "description": "Users on premium plan",
    "filterGroups": [
      {
        "filters": [
          {
            "type": "attribute",
            "field": "plan",
            "operator": "equals",
            "value": "premium"
          }
        ],
        "operator": "AND"
      }
    ],
    "groupOperator": "AND"
  }'

דוגמת בקשה - סגמנט התנהגותי

curl -X POST https://api-eu1.joryio.com/segments \
  -H "Authorization: Bearer jry_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Active Trial Users",
    "description": "Trial users active in last 7 days",
    "filterGroups": [
      {
        "filters": [
          {
            "type": "attribute",
            "field": "plan",
            "operator": "equals",
            "value": "trial"
          },
          {
            "type": "event",
            "eventName": "Session Started",
            "operator": "performed",
            "withinDays": 7
          }
        ],
        "operator": "AND"
      }
    ],
    "groupOperator": "AND"
  }'

דוגמת בקשה - סגמנט מורכב

curl -X POST https://api-eu1.joryio.com/segments \
  -H "Authorization: Bearer jry_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "High-Value At-Risk Users",
    "description": "Paid users with high LTV who haven'\''t logged in recently",
    "filterGroups": [
      {
        "filters": [
          {
            "type": "attribute",
            "field": "plan",
            "operator": "in",
            "value": ["premium", "enterprise"]
          },
          {
            "type": "attribute",
            "field": "lifetimeValue",
            "operator": "gte",
            "value": 500
          }
        ],
        "operator": "AND"
      },
      {
        "filters": [
          {
            "type": "event",
            "eventName": "Login",
            "operator": "not_performed",
            "withinDays": 14
          }
        ],
        "operator": "AND"
      }
    ],
    "groupOperator": "AND"
  }'

תגובה

אובייקט הסגמנט מוחזר ישירות (בלי מעטפת). מזהי סגמנטים הם UUIDs. ספירת חברים אינה נשמרת על הסגמנט - השתמשו ב־GET /segments/:id/size:

{
  "id": "3f9d2c1e-7a54-4b2e-9c1d-8e6f5a4b3c2d",
  "name": "Premium Users",
  "description": "Users on premium plan",
  "filterGroups": [
    {
      "filters": [
        {
          "type": "attribute",
          "field": "plan",
          "operator": "equals",
          "value": "premium"
        }
      ],
      "operator": "AND"
    }
  ],
  "excludeFilterGroups": [],
  "groupOperator": "AND",
  "tags": [],
  "status": "active",
  "createdAt": "2024-01-20T10:30:00.000Z",
  "updatedAt": "2024-01-20T10:30:00.000Z"
}

Get Segment

שליפת פרטי סגמנט.

Endpoint

GET /segments/:id

פרמטרי נתיב

פרמטר	סוג	תיאור
`id`	string	מזהה סגמנט

דוגמת בקשה

curl -X GET https://api-eu1.joryio.com/segments/3f9d2c1e-7a54-4b2e-9c1d-8e6f5a4b3c2d \
  -H "Authorization: Bearer jry_live_your_api_key"

תגובה

אובייקט הסגמנט, מוחזר ישירות (לספירת חברים עדכנית קראו ל־GET /segments/:id/size):

{
  "id": "3f9d2c1e-7a54-4b2e-9c1d-8e6f5a4b3c2d",
  "name": "Premium Users",
  "description": "Users on premium plan",
  "filterGroups": [...],
  "excludeFilterGroups": [],
  "groupOperator": "AND",
  "tags": [],
  "status": "active",
  "createdAt": "2024-01-20T10:30:00.000Z",
  "updatedAt": "2024-01-20T10:30:00.000Z"
}

List Segments

קבלת כל הסגמנטים עם עימוד.

Endpoint

GET /segments

פרמטרי שאילתה

פרמטר	סוג	ברירת מחדל	תיאור
`limit`	number	100	תוצאות לעמוד (לכל היותר 100)
`offset`	number	0	מספר סגמנטים לדילוג
`q`	string	-	חיפוש טקסט חופשי בשם הסגמנט
`status`	string	-	סינון לפי סטטוס: `active` או `archived`
`tags`	string	-	שמות תגיות מופרדים בפסיקים
`createdBy`	string	-	מזהי משתמשים יוצרים, מופרדים בפסיקים
`editedBy`	string	-	מזהי עורכים אחרונים, מופרדים בפסיקים

דוגמת בקשה

curl -X GET "https://api-eu1.joryio.com/segments?limit=50&status=active" \
  -H "Authorization: Bearer jry_live_your_api_key"

תגובה

{
  "data": [
    {
      "id": "3f9d2c1e-7a54-4b2e-9c1d-8e6f5a4b3c2d",
      "name": "Premium Users",
      "status": "active",
      "createdAt": "2024-01-20T10:30:00.000Z"
    },
    {
      "id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
      "name": "Trial Users",
      "status": "active",
      "createdAt": "2024-01-19T09:15:00.000Z"
    }
  ],
  "pagination": {
    "total": 23,
    "page": 1,
    "limit": 50,
    "offset": 0,
    "totalPages": 1,
    "hasMore": false
  }
}

Update Segment

עדכון שם, תיאור או מסננים של סגמנט. משתמשים ב־PUT (אין מסלול PATCH); שדות שלא נשלחים נשארים ללא שינוי.

Endpoint

PUT /segments/:id

גוף בקשה

{
  "name": "Updated Name",
  "description": "Updated description",
  "filterGroups": [...]
}

דוגמת בקשה

curl -X PUT https://api-eu1.joryio.com/segments/3f9d2c1e-7a54-4b2e-9c1d-8e6f5a4b3c2d \
  -H "Authorization: Bearer jry_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Premium users who have made at least one purchase"
  }'

תגובה

אובייקט הסגמנט המעודכן, מוחזר ישירות:

{
  "id": "3f9d2c1e-7a54-4b2e-9c1d-8e6f5a4b3c2d",
  "name": "Premium Users",
  "description": "Premium users who have made at least one purchase",
  "status": "active",
  "updatedAt": "2024-01-21T14:30:00.000Z"
}

Archive Segment

סגמנטים אינם ניתנים למחיקה קשיחה - קמפיינים ומסעות מחזיקים הפניות לסגמנטים, ולכן ההסרה היא ארכוב בלבד. סגמנט בארכיון מפסיק להופיע ברשימות פעילות וניתן לשחזרו בכל עת.

Endpoints

POST /segments/:id/archive
POST /segments/:id/unarchive

דוגמת בקשה

curl -X POST https://api-eu1.joryio.com/segments/3f9d2c1e-7a54-4b2e-9c1d-8e6f5a4b3c2d/archive \
  -H "Authorization: Bearer jry_live_your_api_key"

תגובה

אובייקט הסגמנט עם הסטטוס החדש:

{
  "id": "3f9d2c1e-7a54-4b2e-9c1d-8e6f5a4b3c2d",
  "name": "Premium Users",
  "status": "archived",
  "updatedAt": "2024-01-21T14:30:00.000Z"
}

הערות

ארכוב סגמנט לא מוחק את המשתמשים שבו
קמפיינים פעילים שמשתמשים בסגמנט יושפעו
השתמשו ב־POST /segments/:id/unarchive לשחזור

Get Segment Users

קבלת רשימת משתמשים בסגמנט.

Endpoint

GET /segments/:id/users

פרמטרי שאילתה

פרמטר	סוג	ברירת מחדל	תיאור
`limit`	number	100	מספר משתמשים להחזרה
`offset`	number	0	מספר משתמשים לדילוג

דוגמת בקשה

curl -X GET "https://api-eu1.joryio.com/segments/3f9d2c1e-7a54-4b2e-9c1d-8e6f5a4b3c2d/users?limit=100" \
  -H "Authorization: Bearer jry_live_your_api_key"

תגובה

מערך JSON חשוף של מסמכי משתמשים (בלי מעטפת עימוד - בצעו עימוד באמצעות limit / offset):

[
  {
    "_id": "665f1e2a9b3c4d5e6f7a8b9c",
    "externalId": "user_123",
    "email": "user1@example.com",
    "attributes": {
      "plan": "premium",
      "signupDate": "2024-01-15"
    }
  },
  {
    "_id": "665f1e2a9b3c4d5e6f7a8b9d",
    "externalId": "user_456",
    "email": "user2@example.com",
    "attributes": {
      "plan": "premium",
      "signupDate": "2024-01-18"
    }
  }
]

Get Segment Size

קבלת מספר המשתמשים הנוכחי בסגמנט. כברירת מחדל זהו אומדן מהיר מקורב; העבירו ?exact=true לספירה מדויקת. רק המספר עצמו עשוי להיות מקורב - החברות בפועל והשליחות תמיד מדויקות.

Endpoint

GET /segments/:id/size

פרמטרי שאילתה

פרמטר	סוג	ברירת מחדל	תיאור
`exact`	boolean	false	`true` מחזיר ספירה מדויקת (איטי יותר בסביבות עבודה גדולות)

דוגמת בקשה

curl -X GET https://api-eu1.joryio.com/segments/3f9d2c1e-7a54-4b2e-9c1d-8e6f5a4b3c2d/size \
  -H "Authorization: Bearer jry_live_your_api_key"

תגובה

{
  "segmentId": "3f9d2c1e-7a54-4b2e-9c1d-8e6f5a4b3c2d",
  "size": 1234,
  "approximate": true
}

אופרטורים למסננים

אופרטורים למאפיינים

אופרטור	תיאור	דוגמה
`equals`	התאמה מדויקת	`plan equals "premium"`
`not_equals`	לא שווה	`plan not_equals "free"`
`in`	ערך ברשימה	`plan in ["premium", "enterprise"]`
`not_in`	ערך לא ברשימה	`plan not_in ["free", "trial"]`
`contains`	מכיל מחרוזת	`email contains "@company.com"`
`not_contains`	לא מכיל מחרוזת	`email not_contains "@competitor.com"`
`gt`	גדול מ	`lifetimeValue > 1000`
`gte`	גדול או שווה	`age >= 18`
`lt`	קטן מ	`loginCount < 5`
`lte`	קטן או שווה	`mrr <= 99`
`exists`	שדה קיים	`phone exists`
`not_exists`	שדה לא קיים	`referralCode not_exists`
`within_next_days`	תאריך בתוך N ימים קדימה	`trialEndsDate within_next_days 7`

אופרטורים לאירועים

אופרטור	תיאור	דוגמה
`performed`	המשתמש ביצע אירוע	`Performed "Order Completed"`
`not_performed`	המשתמש לא ביצע אירוע	`Not performed "Onboarding Completed"`
`performed_count_gte`	ספירת אירועים גדולה או שווה (N בשדה `value`)	`Performed "Login" >= 10 times`
`performed_count_lte`	ספירת אירועים קטנה או שווה (N בשדה `value`)	`Performed "Login" <= 5 times`
`performed_in_last_days`	בוצע ב־N הימים האחרונים (N בשדה `value`)	`Performed "Login" in last 7 days`
`not_performed_in_last_days`	לא בוצע ב־N הימים האחרונים (N בשדה `value`)	`No "Login" in last 14 days`

דוגמאות למסננים

מסננים למאפיינים

// String matching
{
  "type": "attribute",
  "field": "email",
  "operator": "contains",
  "value": "@company.com"
}

// Numeric comparison
{
  "type": "attribute",
  "field": "lifetimeValue",
  "operator": "gte",
  "value": 500
}

// Multiple values
{
  "type": "attribute",
  "field": "plan",
  "operator": "in",
  "value": ["premium", "enterprise"]
}

// Field exists
{
  "type": "attribute",
  "field": "phone",
  "operator": "exists"
}

// Date within next N days (future dates)
{
  "type": "attribute",
  "field": "trialEndsDate",
  "operator": "within_next_days",
  "value": 7
}

מסננים לאירועים

// Event performed within timeframe
{
  "type": "event",
  "eventName": "Order Completed",
  "operator": "performed",
  "withinDays": 30
}

// Event not performed
{
  "type": "event",
  "eventName": "Onboarding Completed",
  "operator": "not_performed"
}

// Event count (N goes in `value`)
{
  "type": "event",
  "eventName": "Login",
  "operator": "performed_count_gte",
  "value": 10,
  "withinDays": 30
}

מסננים לסגמנטים

// User in another segment
{
  "type": "segment",
  "segmentId": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
  "operator": "in_segment"
}

// User not in another segment
{
  "type": "segment",
  "segmentId": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
  "operator": "not_in_segment"
}

דוגמאות סגמנטים נפוצים

הזדמנות להמרת טרייל

{
  "name": "Trial Expiring Soon",
  "description": "Users whose trial ends in the next 3 days and haven't purchased",
  "filterGroups": [
    {
      "filters": [
        {
          "type": "attribute",
          "field": "plan",
          "operator": "equals",
          "value": "trial"
        },
        {
          "type": "attribute",
          "field": "trialEndsDate",
          "operator": "within_next_days",
          "value": 3
        },
        {
          "type": "event",
          "eventName": "Order Completed",
          "operator": "not_performed"
        }
      ],
      "operator": "AND"
    }
  ],
  "groupOperator": "AND"
}

Power Users

{
  "name": "Power Users",
  "filterGroups": [
    {
      "filters": [
        {
          "type": "event",
          "eventName": "Login",
          "operator": "performed_count_gte",
          "value": 20,
          "withinDays": 30
        },
        {
          "type": "event",
          "eventName": "Feature Used",
          "operator": "performed_count_gte",
          "value": 50,
          "withinDays": 30
        }
      ],
      "operator": "AND"
    }
  ],
  "groupOperator": "AND"
}

לקוחות בסיכון

{
  "name": "At-Risk Premium Users",
  "filterGroups": [
    {
      "filters": [
        {
          "type": "attribute",
          "field": "plan",
          "operator": "in",
          "value": ["premium", "enterprise"]
        },
        {
          "type": "attribute",
          "field": "lifetimeValue",
          "operator": "gte",
          "value": 500
        }
      ],
      "operator": "AND"
    },
    {
      "filters": [
        {
          "type": "event",
          "eventName": "Login",
          "operator": "not_performed",
          "withinDays": 14
        }
      ],
      "operator": "AND"
    }
  ],
  "groupOperator": "AND"
}

עדכונים דינמיים

סגמנטים הם דינמיים: החברות אינה רשימה שמורה - המסננים של הסגמנט מוערכים מול נתוני הפרופילים והאירועים העדכניים בכל פעם שהסגמנט בשימוש (מיקוד קמפיינים, שערים במסעות, בדיקות חברות). אין מה לרענן או לחשב מחדש דרך ה־API.

בדיקת גודל הסגמנט

# Get current size (approximate by default; add ?exact=true for a precise count)
curl -X GET https://api-eu1.joryio.com/segments/3f9d2c1e-7a54-4b2e-9c1d-8e6f5a4b3c2d/size \
  -H "Authorization: Bearer jry_live_your_api_key"

תגובות שגיאה

כל השגיאות משתמשות בגוף השגיאה הסטנדרטי - ראו סקירת API: תגובת שגיאה.

400 Bad Request - Invalid Filter

{
  "statusCode": 400,
  "message": "Bad Request Exception",
  "timestamp": "2026-01-15T10:30:00.000Z",
  "path": "/segments",
  "errors": [
    "filterGroups.0.filters.0.operator must be one of the following values: equals, not_equals, contains, ..."
  ]
}

404 Not Found

{
  "statusCode": 404,
  "message": "Segment with ID 3f9d2c1e-7a54-4b2e-9c1d-8e6f5a4b3c2d not found",
  "timestamp": "2026-01-15T10:30:00.000Z",
  "path": "/segments/3f9d2c1e-7a54-4b2e-9c1d-8e6f5a4b3c2d"
}

מגבלות קצב

ל־Segments API אין כיום מגבלות קצב קבועות לכל נקודת קצה - ראו סקירת API: מגבלות קצב.

שיטות עבודה מומלצות

1. שמרו על סגמנטים ממוקדים

טוב: סגמנטים ספציפיים וממוקדים

{
  "name": "Premium US Users - Active Last 7 Days",
  "filters": [...]
}

לא טוב: סגמנטים רחבים מדי

{
  "name": "All Users",
  "filters": []
}

2. שמות תיאוריים

טוב: שמות מובנים מאליהם

"Trial Users - Expiring This Week"
"High-Value At-Risk Customers"
"New Signups - Not Onboarded"

לא טוב: שמות לא ברורים

"Segment 1"
"Test"
"Users ABC"

3. שילוב מסננים באופן לוגי

השתמשו ב־AND לצמצום ו־OR להרחבה:

// AND: Premium users who are active
{
  "filters": [
    { "field": "plan", "operator": "equals", "value": "premium" },
    { "eventName": "Login", "operator": "performed", "withinDays": 7 }
  ],
  "operator": "AND"
}

// OR: Users on any paid plan
{
  "filters": [
    { "field": "plan", "operator": "equals", "value": "premium" },
    { "field": "plan", "operator": "equals", "value": "enterprise" }
  ],
  "operator": "OR"
}

4. עקבו אחרי גודל הסגמנט

עקבו אחרי הגודל לאורך זמן:

// Poll segment size
setInterval(async () => {
  const { size, approximate } = await fetch(`/segments/${segmentId}/size`).then(r => r.json());
  console.log(`Segment size: ${approximate ? '≈' : ''}${size}`);
}, 60000); // Every minute

אימות​

Create Segment​

Endpoint​

גוף בקשה​

מבנה מסננים​

דוגמת בקשה - מסנן מאפיין פשוט​

דוגמת בקשה - סגמנט התנהגותי​

דוגמת בקשה - סגמנט מורכב​

תגובה​

Get Segment​

Endpoint​

פרמטרי נתיב​

דוגמת בקשה​

תגובה​

List Segments​

Endpoint​

פרמטרי שאילתה​

דוגמת בקשה​

תגובה​

Update Segment​

Endpoint​

גוף בקשה​

דוגמת בקשה​

תגובה​

Archive Segment​

Endpoints​

דוגמת בקשה​

תגובה​

הערות​

Get Segment Users​

Endpoint​

פרמטרי שאילתה​

דוגמת בקשה​

תגובה​

Get Segment Size​

Endpoint​

פרמטרי שאילתה​

דוגמת בקשה​

תגובה​

אופרטורים למסננים​

אופרטורים למאפיינים​

אופרטורים לאירועים​

דוגמאות למסננים​

מסננים למאפיינים​

מסננים לאירועים​

מסננים לסגמנטים​

דוגמאות סגמנטים נפוצים​

הזדמנות להמרת טרייל​

Power Users​

לקוחות בסיכון​

עדכונים דינמיים​

בדיקת גודל הסגמנט​

תגובות שגיאה​

400 Bad Request - Invalid Filter​

404 Not Found​

מגבלות קצב​

שיטות עבודה מומלצות​

1. שמרו על סגמנטים ממוקדים​

2. שמות תיאוריים​

3. שילוב מסננים באופן לוגי​

4. עקבו אחרי גודל הסגמנט​

צעדים הבאים​

אימות

Create Segment

Endpoint

גוף בקשה

מבנה מסננים

דוגמת בקשה - מסנן מאפיין פשוט

דוגמת בקשה - סגמנט התנהגותי

דוגמת בקשה - סגמנט מורכב

תגובה

Get Segment

Endpoint

פרמטרי נתיב

דוגמת בקשה

תגובה

List Segments

Endpoint

פרמטרי שאילתה

דוגמת בקשה

תגובה

Update Segment

Endpoint

גוף בקשה

דוגמת בקשה

תגובה

Archive Segment

Endpoints

דוגמת בקשה

תגובה

הערות

Get Segment Users

Endpoint

פרמטרי שאילתה

דוגמת בקשה

תגובה

Get Segment Size

Endpoint

פרמטרי שאילתה

דוגמת בקשה

תגובה

אופרטורים למסננים

אופרטורים למאפיינים

אופרטורים לאירועים

דוגמאות למסננים

מסננים למאפיינים

מסננים לאירועים

מסננים לסגמנטים

דוגמאות סגמנטים נפוצים

הזדמנות להמרת טרייל

Power Users

לקוחות בסיכון

עדכונים דינמיים

בדיקת גודל הסגמנט

תגובות שגיאה

400 Bad Request - Invalid Filter

404 Not Found

מגבלות קצב

שיטות עבודה מומלצות

1. שמרו על סגמנטים ממוקדים

2. שמות תיאוריים

3. שילוב מסננים באופן לוגי

4. עקבו אחרי גודל הסגמנט

צעדים הבאים