דלג לתוכן הראשי

Segments API

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

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

אימות​

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

Authorization: Bearer jry_live_your_api_key_here
Content-Type: application/json

Create Segment​

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

Endpoint​

POST /segments

גוף בקשה​

שדהסוגחובהתיאור
namestringכןשם הסגמנט (עד 255 תווים)
descriptionstringלאתיאור הסגמנט (עד 1000 תווים)
filterGroupsarrayכןמערך קבוצות מסננים (עד 20)
excludeFilterGroupsarrayלאמשתמשים שתואמים לאחת מהקבוצות האלו מוסרים (עד 20)
groupOperatorstringכןאיך לשלב קבוצות: AND או OR
includeCrawlersbooleanלאלספור פרופילי סורקים (בוטים) כחברים. ברירת מחדל false - גם דף הקהל מסתיר אותם.
tagsarrayלאשמות תגיות לארגון הסגמנטים

מבנה מסננים​

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

{
  filters: [
    {
      type: 'attribute' | 'default_attribute' | 'event' | 'ecommerce'
          | 'behavioral' | 'segment' | 'canvas_execution'
          | 'list_membership' | 'channel_subscription' | 'app'
          | 'entity' | 'bounce_status' | 'wallet_pass'
          | 'warehouse_sync' | 'device' | 'random_bucket'
          | 'contact_import' | 'message_activity',
      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'
}

מסנן random_bucket משווה את מספר הדלי האקראי הקבוע של איש הקשר (0-9999, לעולם אינו משתנה לאותו אדם): operator הוא אחד מ-equals, not_equals, less_than, less_than_or_equal, greater_than, greater_than_or_equal, between; value הוא מספר שלם בין 0 ל-9999, או [from, to] עבור between (כולל שני הקצוות). כל ערך אחר נדחה עם 400. ראו Random bucket number.

מסנן contact_import ‏("הגיע מייבוא") מתאים אנשי קשר לפי ייבואי אנשי הקשר שיצרו או עדכנו אותם: operator הוא any_of או none_of, ו-value היא רשימה של 1 עד 100 מזהי ייבוא מ-GET /users/import/sources. none_of כולל אנשי קשר שאף ייבוא לא נגע בהם. רשימה ריקה נדחית עם 400. אנשי קשר שיובאו לפני שהיכולת הזו שוחררה אינם מסומנים, ולכן תואמים רק none_of. ראו הגיע מייבוא.

מסנן message_activity ‏("פעילות הודעות") מתאים אנשים לפי מה שקרה להודעות שנשלחו אליהם. operator הוא הפעולה: received (האירוע message.sent), delivered, opened, clicked, bounced, unsubscribed או failed. messageSource הוא campaign (עם campaignId), campaign_tag (עם tagIds), any_campaign, journey (עם canvasId), journey_step (עם canvasId ו-nodeId), journey_tag (עם tagIds) או any. messageChannel הוא any או אחד מ-email, sms, push, whatsapp, in_app, webhook, viber - רק ערוץ שמדווח על הפעולה (אין opened ל-sms, push או webhook; bounced רק ל-email). messageWindow הוא ever, in_last_days או not_in_last_days (value = ימים, 1 עד 3650), between_dates (startDate ו-endDate), at_least (value = פעמים, לפחות 1) או at_most (value = פעמים, 0 ומעלה). tagIds היא רשימת מזהי תגיות (מ-GET /tags), וכמה מזהים פירושם כל אחת מהתגיות; היא מתאימה לקמפיינים או למסעות שנושאים את התגית בזמן חישוב הקהל, ושינוי שם התגית לא משנה אותה. מסנן שנשמר עם שם תגית ב-tag עדיין עובד ונשמר לפי מזהה בשמירה הבאה; שם שאף תגית לא נושאת נדחה עם 400. כל ערך אחר נדחה עם 400. דוגמה: { "type": "message_activity", "operator": "opened", "messageSource": "any_campaign", "messageChannel": "email", "messageWindow": "in_last_days", "value": 30 }. ראו פעילות הודעות.

opened ב-email או ב-any פועל לפי כלל הפותח: הוא מתאים גם ללחיצה של אדם במייל, כי לחיצה מוכיחה שהמייל נפתח, ועם at_least / at_most הוא משווה את הגדולה מבין ספירת הפתיחות וספירת הלחיצות במייל. פתיחות של בוטים ולחיצות של סורקי קישורים לעולם אינן נספרות.

מסנן canvas_execution מקבל גם nodeId יחד עם canvasId אחד - הריצה של האדם הגיעה לשלב הזה במסע (כל סוג צומת) - ואת האופרטורים in_tagged_canvas / not_in_tagged_canvas עם tagIds במקום canvasId: נמצא (או לא נמצא) במסע כלשהו שנושא את התגית. עם nodeId, השדה stepWindow מגביל לפי הפעם האחרונה שהריצה נכנסה לשלב: ever (ברירת מחדל), in_last_days (withinDays, 1 עד 3650) או between_dates (startDate ו-endDate). אופרטור של מסע אחד (in_canvas, not_in_canvas, completed_canvas, exited_canvas) שנשמר בלי canvasId לא מתאים לאף אחד. ראו Canvas execution.

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

curl -X POST https://api-eu1.joryio.com/api/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/api/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/api/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

פרמטרי נתיב​

פרמטרסוגתיאור
idstringמזהה סגמנט

דוגמת בקשה​

curl -X GET https://api-eu1.joryio.com/api/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

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

פרמטרסוגברירת מחדלתיאור
limitnumber100תוצאות לעמוד (לכל היותר 100)
offsetnumber0מספר סגמנטים לדילוג
qstring-חיפוש טקסט חופשי בשם הסגמנט
statusstring-סינון לפי סטטוס: active או archived
tagsstring-שמות תגיות מופרדים בפסיקים
createdBystring-מזהי משתמשים יוצרים, מופרדים בפסיקים
editedBystring-מזהי עורכים אחרונים, מופרדים בפסיקים

דוגמת בקשה​

curl -X GET "https://api-eu1.joryio.com/api/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/api/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/api/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

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

פרמטרסוגברירת מחדלתיאור
limitnumber100מספר משתמשים להחזרה
offsetnumber0מספר משתמשים לדילוג

דוגמת בקשה​

curl -X GET "https://api-eu1.joryio.com/api/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": "[email protected]",
    "attributes": {
      "plan": "premium",
      "signupDate": "2024-01-15"
    }
  },
  {
    "_id": "665f1e2a9b3c4d5e6f7a8b9d",
    "externalId": "user_456",
    "email": "[email protected]",
    "attributes": {
      "plan": "premium",
      "signupDate": "2024-01-18"
    }
  }
]

Get Segment Size​

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

Endpoint​

GET /segments/:id/size

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

פרמטרסוגברירת מחדלתיאור
exactbooleanfalsetrue מחזיר ספירה מדויקת (איטי יותר בסביבות עבודה גדולות)

דוגמת בקשה​

curl -X GET https://api-eu1.joryio.com/api/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
אנשי קשר ללא ערך

איש קשר ללא ערך בשדה תואם את האופרטורים השליליים (not_equals, not_contains, not_in, not_exists) ואף אחד מהחיוביים (equals, contains, in, exists, gt, gte, lt, lte). ראו אנשי קשר ללא ערך.

מזהים מושווים בגמישות

email מושווה ללא תלות באותיות גדולות/קטנות על ידי equals, not_equals, in ו־not_in - [email protected] ו־[email protected] הן אותה כתובת. phone מושווה לפי הספרות שלו על ידי אותם ארבעה אופרטורים, ולכן +972501234567, 972501234567 ו־+972 50-123-4567 מתאימים כולם לאותו איש קשר. כל שדה אחר מושווה בדיוק כפי שהזנת אותו, כולל externalId - המזהים שלכם נשארים תלויי רישיות.

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

אופרטורתיאורדוגמה
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/api/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

שמירת פלח מוכן לדוחות​

דוחות אנליטיקה שמסננים לפי פלח חייבים תחילה לחשב מי נמצא בו, ולהעביר את רשימת האנשים למסד הנתונים האנליטי יחד עם השאילתה. הרשימה היא המגבלה: השוואת שימור מנתחת לכל היותר 50,000 חברים בפלח, ולוקחת מדגם אקראי כשהפלח גדול יותר.

מימוש (materialization) של פלח שומר את החברות שלו במסד הנתונים האנליטי, כך שהדוח מבצע JOIN ואף רשימה אינה עוברת. המגבלה נעלמת בכל גודל.

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

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

קבלת מצב המימוש​

GET /segments/:id/materialization
curl -X GET https://api-eu1.joryio.com/api/segments/3f9d2c1e-7a54-4b2e-9c1d-8e6f5a4b3c2d/materialization \
  -H "Authorization: Bearer jry_live_your_api_key"
{
  "materialized": true,
  "refreshedAt": "2026-09-03T03:00:00.000Z",
  "memberCount": 482103,
  "error": null,
  "used": 4,
  "quota": 20
}

refreshedAt הוא null עד שהבנייה הראשונה מסתיימת. error מכיל את הסיבה לכישלון הבנייה האחרונה, כך שתמונת מצב ישנה יכולה לומר מדוע היא ישנה; החברות הקודמת ממשיכה לשרת בינתיים במקום שהפלח יתרוקן. quota בערך -1 פירושו ללא הגבלה.

רשימת כל הפלחים הממומשים בארגון​

GET /segments/materialization/usage

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

{
  "quota": 20,
  "used": 2,
  "segments": [
    {
      "id": "3f9d2c1e-7a54-4b2e-9c1d-8e6f5a4b3c2d",
      "name": "Champions",
      "workspaceId": "8c1f0b2a-91d4-4a77-9a3e-2d6f7b5c1e40",
      "refreshedAt": "2026-09-03T03:00:00.000Z",
      "memberCount": 1200,
      "error": null
    }
  ]
}

הפעלה​

POST /segments/:id/materialization

הבנייה הראשונה רצה מיד ולא ממתינה ללילה. מחזיר את אותו אובייקט מצב.

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

כיבוי​

DELETE /segments/:id/materialization

מוחק את החברות השמורה ומפנה את המקום.

בנייה מחדש עכשיו​

POST /segments/:id/materialization/refresh

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

בדיקת מסננים לפני שמשתמשים בהם​

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

תצוגה מקדימה של קהל​

POST /segments/preview

כמה אנשי קשר תואמים לקבוצת מסננים, בלי לשמור מקטע.

{ "count": 4820 }

דגימת המשתמשים התואמים​

POST /segments/preview-users

אותה שאילתה, מחזירה דגימה של אנשי הקשר עצמם כדי שתוכלו לראות אם אלה האנשים שהתכוונתם אליהם.

בדיקת משתמש בודד​

POST /segments/check-user

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

תגובה:

{ "userId": "user_123", "matches": true }

פילוח לפי ערוץ​

POST /segments/channel-breakdown

כמה מאנשי הקשר התואמים באמת ניתנים להשגה בכל ערוץ. מקטע של 10,000 עם 400 מספרי טלפון אינו קהל SMS של 10,000, וכאן זה נעשה גלוי לפני שמתזמנים את המשלוח.

תגובה:

{
  "email": 9210,
  "sms": 400,
  "push": 3110,
  "whatsapp": 280,
  "viber": 95,
  "matched": 10000,
  "capped": false
}

matched הוא האוכלוסייה שממנה ספירות הערוצים הן תת-קבוצה, ו-capped הוא true כשהפילוח היה גדול מכדי להיפתר במדויק (הספירות אז מתייחסות למדגם שנפתר). ספירת ערוץ היא מה שנתיב השליחה יכול להגיע אליו בפועל: איש קשר מנוי ללא כתובת, ללא טלפון או ללא מכשיר רשום אינו נספר. יומן ה-STOP הטלפוני ורשימות חסימת הכתובות נבדקים שוב בזמן השליחה, כך ששליחה אמיתית יכולה רק להיות קטנה יותר.

יצירה בכמות וייצוא​

POST /segments/bulk
GET /segments/exports

POST /segments/bulk יוצר כמה מקטעים בקריאה אחת - להקמת מרחב עבודה מתוך התצורה שלכם במקום קליקים בממשק. GET /segments/exports מציג את עבודות הייצוא עם הסטטוס שלהן וכתובת ההורדה החתומה מראש כשהן מסתיימות.

צעדים הבאים​

מחיקה מול העברה לארכיון​

POST   /segments/{segmentId}/archive
DELETE /segments/{segmentId}

ארכיון הוא ברירת המחדל. מקטע בארכיון מפסיק להופיע בבוררים ובבדיקות שיוך, וכל קמפיין או מסע שכבר מצביע עליו ממשיך לעבוד. לביטול: POST /segments/{segmentId}/unarchive.

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

GET /users/{userId}/segments מעריך כל מקטע פעיל מול איש הקשר, ולכן מרחב עבודה שצובר מקטעים משלם עליהם בכל בדיקת שיוך. העברה לארכיון או מחיקה של מה שאינכם משתמשים בו היא הפתרון.