Users API

Δημιουργήστε, ενημερώστε και διαχειριστείτε προφίλ χρηστών προγραμματιστικά.

Όλα τα endpoints αυτής της σελίδας είναι σχετικά ως προς το βασικό URL: https://api-eu1.joryio.com - δείτε Επισκόπηση API.

Έλεγχος ταυτότητας

Όλα τα αιτήματα απαιτούν έλεγχο ταυτότητας με κλειδί API:

Authorization: Bearer jry_live_your_api_key_here
Content-Type: application/json

Δημιουργία ή ενημέρωση χρήστη

Δημιουργήστε έναν νέο χρήστη ή ενημερώστε τα γνωρίσματα ενός υπάρχοντος.

Αυτό το endpoint δέχεται δύο μορφές σώματος: ένα μεμονωμένο αντικείμενο χρήστη (τεκμηριώνεται εδώ - επιστρέφει το πλήρες payload χρήστη με αναλυτικές συνόψεις ένταξης) ή έναν σκέτο πίνακα JSON με αντικείμενα χρηστών για μαζικές λειτουργίες (επιστρέφει συγκεντρωτική σύνοψη) - δείτε Μαζικές λειτουργίες (σώμα-πίνακας).

Endpoint

POST /users

Σώμα αιτήματος

Πεδίο	Τύπος	Απαιτείται	Περιγραφή
`externalId`	string	Ένα από `externalId` / `email`	Το δικό σας μοναδικό αναγνωριστικό χρήστη (μέγιστο 255 χαρακτήρες) - το κλειδί δημιουργίας-ή-ενημέρωσης
`email`	string	Ένα από `externalId` / `email`	Η διεύθυνση email του χρήστη
`userId`	string	Όχι	Το εσωτερικό αναγνωριστικό χρήστη του Joryio (24-hex, από τις αποκρίσεις του API) - μόνο ενημέρωση, δεν δημιουργεί ποτέ (δείτε τη σημείωση παρακάτω). Δεν επιτρέπεται μαζί με `externalId`
`phone`	string	Όχι	Ο αριθμός τηλεφώνου του χρήστη (μέγιστο 20 χαρακτήρες)
`attributes`	object	Όχι	Προσαρμοσμένα γνωρίσματα χρήστη (με όρια: μέγιστο 200 κλειδιά, 50KB, βάθος ένθεσης 5)
`subscriptions`	array	Όχι	Συμμετοχές σε λίστες συνδρομών που εφαρμόζονται στην ίδια κλήση (μέγιστο 100). Δείτε Ενσωματωμένες συνδρομές
`events`	array	Όχι	Συμβάντα προς εισαγωγή στην ίδια κλήση (μέγιστο 25). Δείτε Ενσωματωμένα συμβάντα

Το userId είναι το εσωτερικό αναγνωριστικό του Joryio - μόνο ενημέρωση

Τα userId και externalId δεν είναι συνώνυμα. Το userId είναι το εσωτερικό 24-hex id που δημιουργεί μόνο το Joryio (επιστρέφεται ως id / userId στις αποκρίσεις): η αποστολή του ενημερώνει ακριβώς αυτόν τον χρήστη, ή επιστρέφει 404 αν δεν υπάρχει - δεν δημιουργεί ποτέ χρήστη και δεν αντιστοιχίζεται ποτέ με externalId. Ένα userId που δεν είναι 24-hex απορρίπτεται με 400, και η αποστολή userId και externalId μαζί στο ίδιο σώμα απορρίπτεται με 400. Για δημιουργία ή ενημέρωση χρήστη με το δικό σας αναγνωριστικό - όποια μορφή κι αν έχει - χρησιμοποιήστε το externalId.

Ενσωματωμένες συνδρομές

Ένταξη με μία κλήση: αντί για ξεχωριστή κλήση POST /subscriptions/contacts/:userId/lists/:listId ανά λίστα, περάστε τις συμμετοχές απευθείας. Κάθε στοιχείο:

Πεδίο	Τύπος	Απαιτείται	Περιγραφή
`listId`	string	Ναι	Id λίστας συνδρομών
`channel`	string	Όχι	`email`, `sms`, `whatsapp`, `push` ή `viber`. Προεπιλογή `email`
`status`	string	Όχι	`subscribed` (προεπιλογή) ή `unsubscribed`

Οι γραμμές συγκατάθεσης γράφονται μέσω της ίδιας ελεγχόμενης διαδρομής με το αυτόνομο endpoint εγγραφής, με source api. Δύο εγγυήσεις:

Ένα υπάρχον ρητό opt-out για αυτή τη λίστα/κανάλι δεν αναιρείται ποτέ σιωπηλά - το στοιχείο παραλείπεται και αναφέρεται. Η επανεγγραφή μιας απεγγραμμένης επαφής απαιτεί ρητή κλήση POST /subscriptions/contacts/:userId/lists/:listId.
Οι αποτυχίες ανά στοιχείο (για παράδειγμα άγνωστο listId) αναφέρονται στη σύνοψη της απόκρισης και δεν αναιρούν ποτέ το upsert του προφίλ.

Ενσωματωμένα συμβάντα

Κάθε στοιχείο εισάγεται μέσω της τυπικής γραμμής συμβάντων - τα εναύσματα journeys, τα τμήματα και τα αναλυτικά στοιχεία ενεργοποιούνται ακριβώς όπως στο POST /events/track:

Πεδίο	Τύπος	Απαιτείται	Περιγραφή
`name`	string	Ναι	Όνομα συμβάντος (μέγιστο 255 χαρακτήρες). Προτιμήστε κανονικά ονόματα όπως `Order Completed`
`properties`	object	Όχι	Ιδιότητες συμβάντος (ίδια όρια με το endpoint καταγραφής: μέγιστα κλειδιά, 50KB, περιορισμένη ένθεση)
`timestamp`	string ή number	Όχι	Συμβολοσειρά ISO 8601 ή epoch χιλιοστά. Προεπιλογή η τρέχουσα στιγμή

Παράδειγμα αιτήματος

curl -X POST https://api-eu1.joryio.com/users \
  -H "Authorization: Bearer jry_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "user_123",
    "email": "john.doe@example.com",
    "phone": "+1234567890",
    "attributes": {
      "firstName": "John",
      "lastName": "Doe",
      "plan": "premium",
      "signupDate": "2024-01-15T10:30:00Z",
      "customField": "value"
    },
    "subscriptions": [
      { "listId": "3f9d2c1e-7a54-4b2e-9c1d-8e6f5a4b3c2d", "channel": "email" },
      { "listId": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d", "channel": "sms" }
    ],
    "events": [
      {
        "name": "Order Completed",
        "properties": { "orderId": "ord_789", "total": 129.90, "currency": "USD" },
        "timestamp": "2024-01-15T10:29:45Z"
      },
      { "name": "Product Viewed", "properties": { "productId": "sku_42" } }
    ]
  }'

Απόκριση

Το αντικείμενο χρήστη επιστρέφεται απευθείας (χωρίς περιτύλιγμα-φάκελο). Τα id / userId είναι το εσωτερικό αναγνωριστικό του Joryio· το externalId που στείλατε επιστρέφεται όπως είναι:

{
  "id": "665f1e2a9b3c4d5e6f7a8b9c",
  "userId": "665f1e2a9b3c4d5e6f7a8b9c",
  "externalId": "user_123",
  "email": "john.doe@example.com",
  "phone": "+1234567890",
  "attributes": {
    "firstName": "John",
    "lastName": "Doe",
    "plan": "premium",
    "signupDate": "2024-01-15T10:30:00Z"
  },
  "segments": [],
  "createdAt": "2024-01-15T10:30:00.000Z",
  "updatedAt": "2024-01-15T10:30:00.000Z",
  "subscriptions": { "applied": 2, "skipped": [] },
  "events": { "accepted": 2, "rejected": [] }
}

Τα πεδία σύνοψης subscriptions και events εμφανίζονται μόνο όταν δόθηκαν οι αντίστοιχες είσοδοι. Οι παραλειφθείσες συνδρομές είναι αντικείμενα { listId, channel, reason }· τα απορριφθέντα συμβάντα είναι { name, reason }.

Σημειώσεις

Αν ο χρήστης υπάρχει, τα γνωρίσματα συγχωνεύονται (τα υπάρχοντα γνωρίσματα που δεν περιλαμβάνονται στο αίτημα διατηρούνται)
Ο ορισμός ενός γνωρίσματος σε null αποθηκεύει το null ως τιμή του - δεν διαγράφει το κλειδί
Το email και το τηλέφωνο μπαίνουν αυτόματα σε ευρετήριο για τμηματοποίηση
Τα ενσωματωμένα subscriptions / events εφαρμόζονται μετά το upsert του προφίλ· οι αποτυχίες ανά στοιχείο αναφέρονται στα πεδία σύνοψης και δεν αποτυγχάνουν ποτέ την κλήση ούτε αναιρούν τον χρήστη

Λήψη χρήστη βάσει ID

Ανακτήστε το προφίλ και τα γνωρίσματα ενός χρήστη. Υπάρχουν δύο διαδρομές αναζήτησης:

GET /users/by-user-id/:userId - αναζήτηση με το δικό σας αναγνωριστικό (το externalId με το οποίο δημιουργήσατε τον χρήστη). Είναι η προτεινόμενη διαδρομή για ενσωματώσεις.
GET /users/:userId - αναζήτηση με το εσωτερικό ID του Joryio (το 24-hex id που επιστρέφεται στις αποκρίσεις).

Endpoint

GET /users/by-user-id/:userId

Παράμετροι διαδρομής

Παράμετρος	Τύπος	Περιγραφή
`userId`	string	Το εξωτερικό σας αναγνωριστικό (`externalId`)

Παράδειγμα αιτήματος

curl -X GET https://api-eu1.joryio.com/users/by-user-id/user_123 \
  -H "Authorization: Bearer jry_live_your_api_key"

Απόκριση

{
  "id": "665f1e2a9b3c4d5e6f7a8b9c",
  "userId": "665f1e2a9b3c4d5e6f7a8b9c",
  "externalId": "user_123",
  "email": "john.doe@example.com",
  "phone": "+1234567890",
  "attributes": {
    "firstName": "John",
    "lastName": "Doe",
    "plan": "premium",
    "lifetimeValue": 1250.50
  },
  "segments": [],
  "createdAt": "2024-01-15T10:30:00.000Z",
  "updatedAt": "2024-01-20T14:20:00.000Z"
}

Λίστα χρηστών

Λίστα όλων των χρηστών με σελιδοποίηση. Τα αποτελέσματα ταξινομούνται με πρώτους τους πιο πρόσφατα ενημερωμένους - δεν υπάρχει σύνταξη query για φίλτρα γνωρισμάτων ή ταξινόμηση σε αυτό το endpoint (χρησιμοποιήστε τα Τμήματα για τμηματοποίηση βάσει γνωρισμάτων, ή το GET /users/search?query=... για αναζήτηση βάσει ονόματος/email/τηλεφώνου/ID).

Endpoint

GET /users

Παράμετροι query

Παράμετρος	Τύπος	Προεπιλογή	Περιγραφή
`limit`	number	50	Αποτελέσματα ανά σελίδα (μέγιστο 200)
`offset`	number	0	Πλήθος χρηστών που παραλείπονται

Παράδειγμα αιτήματος

curl -X GET "https://api-eu1.joryio.com/users?limit=50&offset=0" \
  -H "Authorization: Bearer jry_live_your_api_key"

Απόκριση

{
  "data": [
    {
      "id": "665f1e2a9b3c4d5e6f7a8b9c",
      "userId": "665f1e2a9b3c4d5e6f7a8b9c",
      "externalId": "user_123",
      "email": "user1@example.com",
      "attributes": {
        "plan": "premium"
      }
    },
    {
      "id": "665f1e2a9b3c4d5e6f7a8b9d",
      "userId": "665f1e2a9b3c4d5e6f7a8b9d",
      "externalId": "user_456",
      "email": "user2@example.com",
      "attributes": {
        "plan": "premium"
      }
    }
  ],
  "pagination": {
    "total": 156,
    "limit": 50,
    "offset": 0,
    "hasMore": true
  }
}

Ενημέρωση χρήστη

Ενημερώστε το email, το τηλέφωνο ή τα γνωρίσματα ενός χρήστη χωρίς να αντικαταστήσετε ολόκληρο το προφίλ. Τα γνωρίσματα συγχωνεύονται ανά κλειδί. Χρησιμοποιεί PUT (δεν υπάρχει διαδρομή PATCH):

PUT /users/by-user-id/:userId - ενημέρωση με το δικό σας αναγνωριστικό.
PUT /users/:userId - ενημέρωση με το εσωτερικό ID του Joryio.

Endpoint

PUT /users/by-user-id/:userId

Σώμα αιτήματος

Πεδίο	Τύπος	Απαιτείται	Περιγραφή
`email`	string	Όχι	Νέα διεύθυνση email
`phone`	string	Όχι	Νέος αριθμός τηλεφώνου
`attributes`	object	Όχι	Γνωρίσματα προς συγχώνευση (ενημέρωση ανά κλειδί)

Παράδειγμα αιτήματος

curl -X PUT https://api-eu1.joryio.com/users/by-user-id/user_123 \
  -H "Authorization: Bearer jry_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "attributes": {
      "plan": "enterprise",
      "mrr": 499
    }
  }'

Απόκριση

Το ενημερωμένο αντικείμενο χρήστη επιστρέφεται απευθείας:

{
  "id": "665f1e2a9b3c4d5e6f7a8b9c",
  "userId": "665f1e2a9b3c4d5e6f7a8b9c",
  "externalId": "user_123",
  "attributes": {
    "firstName": "John",
    "plan": "enterprise",
    "mrr": 499,
    "signupDate": "2024-01-15T10:30:00Z"
  },
  "updatedAt": "2024-01-20T15:30:00.000Z"
}

Διαγραφή χρήστη

Διαγράψτε έναν χρήστη. Ο χρήστης μεταφέρεται σε έναν κάδο ανακύκλωσης (αρχειοθετείται με έλεγχο-ιστορικό) και μπορεί να επαναφερθεί - δεν διαγράφεται οριστικά.

Endpoint

DELETE /users/:userId

Η παράμετρος διαδρομής είναι το εσωτερικό ID χρήστη του Joryio. Απαιτεί το scope users:delete. Περάστε ένα προαιρετικό ?reason= για να καταγράψετε τον λόγο, στο έλεγχο-ιστορικό της διαγραφής.

Παράδειγμα αιτήματος

curl -X DELETE "https://api-eu1.joryio.com/users/665f1e2a9b3c4d5e6f7a8b9c?reason=duplicate" \
  -H "Authorization: Bearer jry_live_your_api_key"

Απόκριση

204 No Content - το σώμα της απόκρισης είναι κενό.

Σημειώσεις

Ο χρήστης μεταφέρεται σε έναν κάδο ανακύκλωσης και μπορεί να επαναφερθεί - δείτε Λίστα διαγραμμένων χρηστών. Κάθε διαγραφή καταγράφεται με έλεγχο-ιστορικό ποιος / πότε / πώς / γιατί. (Η επαναφορά εκτελείται προς το παρόν μέσω εσωτερικού endpoint - επικοινωνήστε με την υποστήριξη για να επαναφέρετε μια διαγραμμένη επαφή.)
Ο χρήστης αφαιρείται από τα τμήματα και οι ενεργές καμπάνιες παύουν αμέσως να τον στοχεύουν.
Το ιστορικό συμβάντων διατηρείται, οπότε ένας χρήστης που επαναφέρεται διατηρεί όλο το ιστορικό του.
Για να διαγράψετε οριστικά έναν χρήστη και όλα τα δεδομένα του (δικαίωμα διαγραφής κατά GDPR), χρησιμοποιήστε αντ' αυτού τη ροή διαγραφής δεδομένων (DSR) - αυτή είναι μη αναστρέψιμη και αποτελεί διαφορετική λειτουργία.

Λίστα διαγραμμένων χρηστών

Λίστα του κάδου ανακύκλωσης - χρήστες που διαγράφηκαν, με το έλεγχο-ιστορικό της διαγραφής (ποιος, πότε, πώς, γιατί).

Endpoint

GET /users/deleted

Απαιτεί το scope users:read.

Παράμετροι query

Παράμετρος	Τύπος	Προεπιλογή	Περιγραφή
`query`	string	-	Προαιρετικό. Αντιστοίχιση βάσει προθέματος email/externalId, τηλεφώνου ή αρχικού ID χρήστη.
`limit`	number	50	Μέγιστα αποτελέσματα, προεπιλογή 50, μέγιστο 200
`offset`	number	0	Πλήθος που παραλείπεται, προεπιλογή 0

Παράδειγμα αιτήματος

curl -X GET "https://api-eu1.joryio.com/users/deleted?limit=50" \
  -H "Authorization: Bearer jry_live_your_api_key"

Απόκριση

{
  "total": 1,
  "items": [
    {
      "originalId": "665f1e2a9b3c4d5e6f7a8b9c",
      "email": "sarah@example.com",
      "phone": "+15551234567",
      "externalId": "usr_1001",
      "deletedAt": "2026-08-09T03:00:30.000Z",
      "deletedBy": "you@example.com",
      "deletedVia": "api",
      "deletedReason": "duplicate",
      "restoredAt": null
    }
  ]
}

Μαζικές λειτουργίες (σώμα-πίνακας)

Δεν υπάρχει ξεχωριστό endpoint μαζικών λειτουργιών: το POST /users δέχεται είτε ένα μεμονωμένο αντικείμενο χρήστη είτε έναν σκέτο πίνακα JSON με αντικείμενα χρηστών (χωρίς αντικείμενο-περιτύλιγμα). Η μορφή πίνακα δημιουργεί ή ενημερώνει έως 1000 χρήστες σε ένα αίτημα.

Endpoint

POST /users
Content-Type: application/json

[ { ...user }, { ...user } ]

Σώμα αιτήματος

Ένας πίνακας JSON (μέγιστο 1000 στοιχεία). Κάθε στοιχείο ακολουθεί την ίδια μορφή με τη μορφή μεμονωμένου αντικειμένου, συμπεριλαμβανομένων των προαιρετικών ενσωματωμένων πεδίων subscriptions και events. Τα όρια ισχύουν ανά στοιχείο: μέγιστο 100 συνδρομές και μέγιστο 25 συμβάντα το καθένα (οπότε ένα αίτημα 1000 στοιχείων μπορεί να μεταφέρει το πολύ 25 συμβάντα ανά στοιχείο - το όριο δεν πολλαπλασιάζεται με την ομαδοποίηση).

Κάθε στοιχείο περνά από πλήρη επικύρωση. Ένα μη έγκυρο στοιχείο αναφέρεται στο failed με τον δείκτη του στον πίνακα - δεν γίνεται ποτέ σιωπηλά αποδεκτό - και τα υπόλοιπα έγκυρα στοιχεία εξακολουθούν να επεξεργάζονται.

Παράδειγμα αιτήματος

curl -X POST https://api-eu1.joryio.com/users \
  -H "Authorization: Bearer jry_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "externalId": "user_001",
      "email": "user1@example.com",
      "attributes": { "firstName": "John", "plan": "free" },
      "subscriptions": [
        { "listId": "3f9d2c1e-7a54-4b2e-9c1d-8e6f5a4b3c2d", "channel": "email" }
      ],
      "events": [
        { "name": "Order Completed", "properties": { "orderId": "ord_789", "total": 129.90 } }
      ]
    },
    {
      "externalId": "user_002",
      "email": "user2@example.com",
      "attributes": { "firstName": "Jane", "plan": "premium" }
    }
  ]'

Απόκριση

Σε αντίθεση με τη μορφή αντικειμένου (που επιστρέφει το πλήρες payload χρήστη με αναλυτικές συνόψεις ένταξης), η μορφή πίνακα επιστρέφει μια συγκεντρωτική σύνοψη:

{
  "processed": 2,
  "created": 1,
  "updated": 1,
  "failed": [],
  "subscriptions": { "applied": 1, "skipped": 0 },
  "events": { "accepted": 1, "rejected": 0 }
}

Απόκριση με αποτυχίες

{
  "processed": 2,
  "created": 1,
  "updated": 1,
  "failed": [
    {
      "index": 2,
      "userId": "user_003",
      "reason": "property hacker should not exist"
    }
  ],
  "subscriptions": { "applied": 0, "skipped": 0 },
  "events": { "accepted": 0, "rejected": 0 }
}

Όρια

Μέγιστο 1000 χρήστες ανά αίτημα
Κάθε στοιχείο περνά από την ίδια επικύρωση με τη μορφή μεμονωμένου αντικειμένου (συμπεριλαμβανομένων των ένθετων subscriptions / events)
Όρια ανά στοιχείο: 100 συνδρομές, 25 συμβάντα
Συνολικά όρια ανά αίτημα: το πολύ 500 ενσωματωμένα συμβάντα και 1000 ενσωματωμένες συνδρομές αθροιστικά σε ολόκληρο τον πίνακα - πέρα από αυτό, στείλτε τα συμβάντα στο POST /events/track (σώμα-πίνακας) και τις συμμετοχές σε λίστες στο μαζικό endpoint μελών λίστας συνδρομών
Η επεξεργασία γίνεται σε παράλληλες παρτίδες των 10 για βέλτιστη απόδοση
Επιτρέπονται μερικές αποτυχίες - τα έγκυρα στοιχεία επεξεργάζονται ακόμη κι αν κάποια αποτύχουν, και το failed αναλύει κάθε αποτυχία με τον δείκτη της στον πίνακα
Τα αποτελέσματα ένταξης (subscriptions / events) συγκεντρώνονται ως μετρητές· χρησιμοποιήστε τη μορφή μεμονωμένου αντικειμένου όταν χρειάζεστε αναλυτικούς λόγους παράλειψης/απόρριψης

Η μορφή πίνακα προορίζεται για προγραμματιστικές παρτίδες από το backend σας. Για αρχεία και πλήρεις μεταβάσεις, μη φτιάχνετε δικούς σας βρόχους ομαδοποίησης - χρησιμοποιήστε τη Μαζική εισαγωγή στο dashboard (CSV/JSON με αντιστοίχιση στηλών, απαλοιφή διπλοτύπων, κανόνες συγκατάθεσης και αναφορά σφαλμάτων) ή το Warehouse sync για επαναλαμβανόμενες φορτώσεις.

Συμβάντα χρήστη

Λήψη των συμβάντων ενός χρήστη

Ανακτήστε όλα τα συμβάντα ενός συγκεκριμένου χρήστη.

Endpoint

GET /users/:userId/events

Η παράμετρος διαδρομής είναι το εσωτερικό ID χρήστη του Joryio.

Παράμετροι query

Παράμετρος	Τύπος	Προεπιλογή	Περιγραφή
`limit`	number	50	Πλήθος συμβάντων που επιστρέφονται (μέγιστο 1000)
`offset`	number	0	Μετατόπιση σελιδοποίησης
`startDate`	string	-	Φιλτράρισμα συμβάντων μετά από αυτή την ημερομηνία (ISO 8601)
`endDate`	string	-	Φιλτράρισμα συμβάντων πριν από αυτή την ημερομηνία (ISO 8601)
`eventName`	string	-	Φιλτράρισμα βάσει ονόματος συμβάντος
`groupBySession`	boolean	false	Επιστρέφει επιπλέον τα συμβάντα ομαδοποιημένα ανά συνεδρία

Παράδειγμα αιτήματος

curl -X GET "https://api-eu1.joryio.com/users/665f1e2a9b3c4d5e6f7a8b9c/events?limit=20" \
  -H "Authorization: Bearer jry_live_your_api_key"

Απόκριση

Τα πεδία των συμβάντων χρησιμοποιούν snake_case (προέρχονται από το analytics store):

{
  "data": [
    {
      "event_id": "9b2f6c1e-4a8d-4f0b-9c3d-2e1f5a6b7c8d",
      "event_name": "Order Completed",
      "properties": {
        "orderId": "order_456",
        "total": 99.99
      },
      "timestamp": "2024-01-20 14:30:00"
    },
    {
      "event_id": "1c3e5a7b-9d2f-4b6c-8e0a-3f5d7b9c1e2a",
      "event_name": "Page Viewed",
      "properties": {
        "page": "/pricing"
      },
      "timestamp": "2024-01-20 14:25:00"
    }
  ],
  "total": 156,
  "limit": 20,
  "offset": 0
}

Συνήθη γνωρίσματα

Ειδικά πεδία και γνωρίσματα

Τα email και phone είναι πεδία προφίλ ανώτατου επιπέδου (όχι γνωρίσματα) - στείλτε τα στο ανώτατο επίπεδο του σώματος του αιτήματος.

Τα παρακάτω γνωρίσματα έχουν ειδική σημασία στο Joryio:

Γνώρισμα	Τύπος	Περιγραφή
`firstName`	string	Το όνομα του χρήστη (χρησιμοποιείται στην αναζήτηση και στην εμφάνιση)
`lastName`	string	Το επώνυμο του χρήστη (χρησιμοποιείται στην αναζήτηση και στην εμφάνιση)
`language`	string	Προτιμώμενη γλώσσα (ορίζεται αυτόματα από τα SDK όταν είναι διαθέσιμη)
`timezone`	string	Η ζώνη ώρας του χρήστη, σε μορφή IANA (καθορίζει τις ώρες ησυχίας και την παράδοση journeys σε τοπική ώρα)
`country`	string	Κωδικός χώρας (σε ευρετήριο για τμηματοποίηση)

Προσαρμοσμένα γνωρίσματα

Μπορείτε να προσθέσετε απεριόριστα προσαρμοσμένα γνωρίσματα:

{
  "attributes": {
    "plan": "premium",
    "mrr": 99,
    "signupSource": "google_ads",
    "lifetimeValue": 1250.50,
    "tags": ["vip", "early-adopter"],
    "preferences": {
      "emailNotifications": true,
      "smsNotifications": false
    }
  }
}

Υποστηριζόμενοι τύποι δεδομένων

String: "premium"
Number: 99.99
Boolean: true / false
Date: "2024-01-15T10:30:00Z" (ISO 8601)
Array: ["tag1", "tag2"]
Object: { "nested": "value" }

Αποκρίσεις σφαλμάτων

Όλα τα σφάλματα χρησιμοποιούν το τυπικό σώμα σφάλματος - δείτε Επισκόπηση API: Απόκριση σφάλματος.

400 Bad Request

{
  "statusCode": 400,
  "message": "Cannot create or update a user without a valid identifier (externalId or email to create; userId only updates an existing user)",
  "timestamp": "2026-01-15T10:30:00.000Z",
  "path": "/users"
}

401 Unauthorized

{
  "statusCode": 401,
  "message": "Invalid or expired API key",
  "timestamp": "2026-01-15T10:30:00.000Z",
  "path": "/users"
}

404 Not Found

{
  "statusCode": 404,
  "message": "User with userId 'user_123' not found",
  "timestamp": "2026-01-15T10:30:00.000Z",
  "path": "/users/by-user-id/user_123"
}

Καλές πρακτικές

1. Οι επαναλήψεις είναι ασφαλείς - το POST /users είναι upsert

Το POST /users έχει κλειδί το δικό σας userId - η επανάληψη του ίδιου αιτήματος ενημερώνει το ίδιο προφίλ αντί να δημιουργήσει διπλότυπο. Δεν υπάρχει κεφαλίδα Idempotency-Key· απλώς επαναλάβετε το αίτημα ως έχει σε αποτυχίες δικτύου:

curl -X POST https://api-eu1.joryio.com/users \
  -H "Authorization: Bearer jry_live_your_api_key" \
  -d '{...}'

2. Ονομασία γνωρισμάτων

Χρησιμοποιείτε συνεπή, περιγραφικά ονόματα γνωρισμάτων:

Σωστό:

{
  "signupDate": "2024-01-15",
  "lifetimeValue": 1250.50,
  "plan": "premium"
}

Λάθος:

{
  "sd": "2024-01-15",
  "ltv": 1250.50,
  "p": "premium"
}

3. Μορφή αριθμού τηλεφώνου

Χρησιμοποιείτε πάντα τη μορφή E.164 για αριθμούς τηλεφώνου:

Σωστό: "+1234567890" Λάθος: "(123) 456-7890", "123-456-7890"

Όρια ρυθμού

Το Users API δεν έχει σήμερα σταθερά όρια ρυθμού ανά endpoint - δείτε Επισκόπηση API: Όρια ρυθμού για τη συμπεριφορά σε επίπεδο πλατφόρμας και τον χειρισμό των αποκρίσεων 429.

Έλεγχος ταυτότητας​

Δημιουργία ή ενημέρωση χρήστη​

Endpoint​

Σώμα αιτήματος​

Ενσωματωμένες συνδρομές​

Ενσωματωμένα συμβάντα​

Παράδειγμα αιτήματος​

Απόκριση​

Σημειώσεις​

Λήψη χρήστη βάσει ID​

Endpoint​

Παράμετροι διαδρομής​

Παράδειγμα αιτήματος​

Απόκριση​

Λίστα χρηστών​

Endpoint​

Παράμετροι query​

Παράδειγμα αιτήματος​

Απόκριση​

Ενημέρωση χρήστη​

Endpoint​

Σώμα αιτήματος​

Παράδειγμα αιτήματος​

Απόκριση​

Διαγραφή χρήστη​

Endpoint​

Παράδειγμα αιτήματος​

Απόκριση​

Σημειώσεις​

Λίστα διαγραμμένων χρηστών​

Endpoint​

Παράμετροι query​

Παράδειγμα αιτήματος​

Απόκριση​

Μαζικές λειτουργίες (σώμα-πίνακας)​

Endpoint​

Σώμα αιτήματος​

Παράδειγμα αιτήματος​

Απόκριση​

Απόκριση με αποτυχίες​

Όρια​

Συμβάντα χρήστη​

Λήψη των συμβάντων ενός χρήστη​

Endpoint​

Παράμετροι query​

Παράδειγμα αιτήματος​

Απόκριση​

Συνήθη γνωρίσματα​

Ειδικά πεδία και γνωρίσματα​

Προσαρμοσμένα γνωρίσματα​

Υποστηριζόμενοι τύποι δεδομένων​

Αποκρίσεις σφαλμάτων​

400 Bad Request​

401 Unauthorized​

404 Not Found​

Καλές πρακτικές​

1. Οι επαναλήψεις είναι ασφαλείς - το POST /users είναι upsert​

2. Ονομασία γνωρισμάτων​

3. Μορφή αριθμού τηλεφώνου​

Όρια ρυθμού​

Επόμενα βήματα​

Έλεγχος ταυτότητας

Δημιουργία ή ενημέρωση χρήστη

Endpoint

Σώμα αιτήματος

Ενσωματωμένες συνδρομές

Ενσωματωμένα συμβάντα

Παράδειγμα αιτήματος

Απόκριση

Σημειώσεις

Λήψη χρήστη βάσει ID

Endpoint

Παράμετροι διαδρομής

Παράδειγμα αιτήματος

Απόκριση

Λίστα χρηστών

Endpoint

Παράμετροι query

Παράδειγμα αιτήματος

Απόκριση

Ενημέρωση χρήστη

Endpoint

Σώμα αιτήματος

Παράδειγμα αιτήματος

Απόκριση

Διαγραφή χρήστη

Endpoint

Παράδειγμα αιτήματος

Απόκριση

Σημειώσεις

Λίστα διαγραμμένων χρηστών

Endpoint

Παράμετροι query

Παράδειγμα αιτήματος

Απόκριση

Μαζικές λειτουργίες (σώμα-πίνακας)

Endpoint

Σώμα αιτήματος

Παράδειγμα αιτήματος

Απόκριση

Απόκριση με αποτυχίες

Όρια

Συμβάντα χρήστη

Λήψη των συμβάντων ενός χρήστη

Endpoint

Παράμετροι query

Παράδειγμα αιτήματος

Απόκριση

Συνήθη γνωρίσματα

Ειδικά πεδία και γνωρίσματα

Προσαρμοσμένα γνωρίσματα

Υποστηριζόμενοι τύποι δεδομένων

Αποκρίσεις σφαλμάτων

400 Bad Request

401 Unauthorized

404 Not Found

Καλές πρακτικές

1. Οι επαναλήψεις είναι ασφαλείς - το POST /users είναι upsert

2. Ονομασία γνωρισμάτων

3. Μορφή αριθμού τηλεφώνου

Όρια ρυθμού

Επόμενα βήματα