Segments API
Δημιουργήστε και διαχειριστείτε δυναμικά τμήματα χρηστών προγραμματιστικά.
Όλα τα endpoints αυτής της σελίδας είναι σχετικά ως προς το βασικό URL: https://api-eu1.joryio.com - δείτε Επισκόπηση API.
Έλεγχος ταυτότητας
Όλα τα αιτήματα απαιτούν έλεγχο ταυτότητας με κλειδί API:
Authorization: Bearer jry_live_your_api_key_here
Content-Type: application/json
Δημιουργία τμήματος
Δημιουργήστε ένα νέο τμήμα χρηστών με φίλτρα.
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"
}'
Απόκριση
Το αντικείμενο του τμήματος επιστρέφεται απευθείας (χωρίς περιτύλιγμα-φάκελο). Τα IDs τμημάτων είναι UUID. Το πλήθος μελών δεν αποθηκεύεται στο τμήμα - χρησιμοποιήστε το 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"
}
Λήψη τμήματος
Ανάκτηση των λεπτομερειών ενός τμήματος.
Endpoint
GET /segments/:id
Παράμετροι διαδρομής
| Παράμετρος | Τύπος | Περιγραφή |
|---|---|---|
id | string | ID τμήματος |
Παράδειγμα αιτήματος
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"
}
Λίστα τμημάτων
Λήψη όλων των τμημάτων με σελιδοποίηση.
Endpoint
GET /segments
Παράμετροι query
| Παράμετρος | Τύπος | Προεπιλογή | Περιγραφή |
|---|---|---|---|
limit | number | 100 | Αποτελέσματα ανά σελίδα (μέγιστο 100) |
offset | number | 0 | Πλήθος τμημάτων που παραλείπονται |
q | string | - | Αναζήτηση ελεύθερου κειμένου στο όνομα του τμήματος |
status | string | - | Φιλτράρισμα βάσει κατάστασης: active ή archived |
tags | string | - | Ονόματα ετικετών χωρισμένα με κόμμα |
createdBy | string | - | IDs χρηστών-δημιουργών χωρισμένα με κόμμα |
editedBy | string | - | IDs χρηστών-τελευταίων συντακτών χωρισμένα με κόμμα |
Παράδειγμα αιτήματος
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
}
}
Ενημέρωση τμήματος
Ενημερώστε το όνομα, την περιγραφή ή τα φίλτρα του τμήματος. Χρησιμοποιεί 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"
}
Αρχειοθέτηση τμήματος
Τα τμήματα δεν μπορούν να διαγραφούν οριστικά - καμπάνιες και journeys διατηρούν αναφορές σε τμήματα, οπότε η αφαίρεση γίνεται μόνο με αρχειοθέτηση. Τα αρχειοθετημένα τμήματα παύουν να εμφανίζονται στις ενεργές λίστες και μπορούν να επαναφερθούν οποιαδήποτε στιγμή.
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για επαναφορά
Λήψη χρηστών τμήματος
Λήψη της λίστας χρηστών ενός τμήματος.
Endpoint
GET /segments/:id/users
Παράμετροι query
| Παράμετρος | Τύπος | Προεπιλογή | Περιγραφή |
|---|---|---|---|
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"
}
}
]
Λήψη μεγέθους τμήματος
Λήψη του τρέχοντος πλήθους χρηστών ενός τμήματος. Από προεπιλογή είναι μια γρήγορη προσεγγιστική εκτίμηση· περάστε ?exact=true για ακριβή μέτρηση. Το μόνο που είναι ποτέ προσεγγιστικό είναι ο αριθμός του μεγέθους - η πραγματική συμμετοχή και οι αποστολές είναι πάντα ακριβείς.
Endpoint
GET /segments/:id/size
Παράμετροι query
| Παράμετρος | Τύπος | Προεπιλογή | Περιγραφή |
|---|---|---|---|
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"
}
Δυναμικές ενημερώσεις
Τα τμήματα είναι δυναμικά: η συμμετοχή δεν είναι αποθηκευμένη λίστα - τα φίλτρα του τμήματος αξιολογούνται πάνω στα τρέχοντα δεδομένα προφίλ και συμβάντων κάθε φορά που το τμήμα χρησιμοποιείται (στόχευση καμπανιών, πύλες journeys, έλεγχοι συμμετοχής). Δεν υπάρχει τίποτα προς ανανέωση ή επανυπολογισμό μέσω του 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 - Μη έγκυρο φίλτρο
{
"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 δεν έχει σήμερα σταθερά όρια ρυθμού ανά endpoint - δείτε Επισκόπηση 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