איתור אדם

השתמשו ב־GET /users. הוא עונה על כל חיפוש, עם עימוד וסך־הכול.

# לפי המזהה שלכם
curl "https://api-eu1.joryio.com/api/users?externalId=user_123" \
  -H "Authorization: Bearer jry_live_your_api_key"

# לפי אימייל
curl "https://api-eu1.joryio.com/api/[email protected]" \
  -H "Authorization: Bearer jry_live_your_api_key"

# חלקי - כל מה שמתחיל ב־"jane", וגם התאמת טלפון ומזהה
curl "https://api-eu1.joryio.com/api/users?q=jane" \
  -H "Authorization: Bearer jry_live_your_api_key"

באיזה פרמטר

מה שיש לכם	השתמשו ב־	סוג ההתאמה
המזהה שלכם	?externalId=	מדויקת
כתובת אימייל	?email=	מדויקת, ללא תלות באותיות גדולות/קטנות
מזהה Joryio (24 תווים הקסדצימליים)	?userId=	מדויקת
חלק ממשהו - שם, תחילת אימייל, טלפון	?q=	תחילית באימייל, ב־externalId ובשם הפרטי ושם המשפחה; ספרות בכל מקום בטלפון; ערך מלא במזהה 24 תווים או ב־anonymousId בפורמט UUID

הפרמטרים המדויקים מצטרפים זה לזה (?email=…&externalId=… דורש את שניהם). הפרמטר q מתעלמים ממנו כשקיים פרמטר מדויק - "אימייל שווה ל־X" ו"שדה כלשהו מתחיל ב־Y" לא יכולים לצמצם יחד את אותה בקשה, ושילוב שקט שלהם היה עונה על שאלה שלא שאלתם.

כשלא נמצא דבר

עמוד ריק, לא שגיאת 404:

{ "data": [], "pagination": { "total": 0, "limit": 50, "offset": 0, "hasMore": false } }

סידור הרשימה כולה: sortBy (createdAt, updatedAt, email או name; ברירת המחדל updatedAt) ו-sortOrder (asc או desc; ברירת המחדל desc). הסדר יציב בין עמודים - אף שורה לא עוברת ביניהם.

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

פרמטר שאיננו מזהים

אם פרמטר נראה כמו שגיאת כתיב של פרמטר אמיתי, או אם אף אחד מהפרמטרים שלכם אינו מוכר, הבקשה נדחית:

{ "statusCode": 400,
  "message": "Unknown query parameter 'externalid'. Did you mean 'externalId'? Valid parameters: limit, offset, email, externalId, userId, q, bots, sortBy, sortOrder" }

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

פרמטרים שמגיעים בלי שבחרתם לשלוח אותם עדיין מתקבלים ומתעלמים מהם: _ ו־_* (מנטרל המטמון של jQuery), utm_*, gclid, fbclid, msclkid, וכן t / v / cb. כך ש־[email protected]&_=1724500000 עובד, וגם ?_=1724500000 לבדו.

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

שני המסלולים האחרים

שניהם עדיין עובדים. אף אחד מהם לא עושה משהו ש־GET /users לא יכול.

מסלול	עדיין שימושי כאשר
GET /users/by-user-id/:externalId	רוצים את הרשומה עצמה, לא עמוד שמכיל אותה - הוא מחזיר את אובייקט המשתמש ישירות
GET /users/search?query=	רוצים את המבנה הישן: מערך פשוט, מוגבל, בלי total

GET /users/:userId (המזהה הפנימי של Joryio) הוא המסלול הקנוני לרשומה בודדת והוא נשאר - זה מה ש־id בכל תשובה מפנה אליו.

אנשי קשר אנונימיים

מי שנרשם למעקב לפני שזוהה אין לו אימייל, טלפון או שם. הידית היחידה שיש לכם היא ה־anonymousId שה־SDK יצר, ו־?q= מתאים אותו כשהמונח בפורמט UUID:

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

כדי לצרף את היסטוריית הסשן הזה לאדם ידוע, ראו POST /users/identify.

קישורים

• Users API - התיעוד המלא
• Segments - עבור "כל מי ש…", ולא אדם בודד