Saltar al contenido principal

Encontrar a una persona

Usa GET /users. Responde a cualquier búsqueda, con paginación y total.

# por tu propio identificador
curl "https://api-eu1.joryio.com/api/users?externalId=user_123" \
  -H "Authorization: Bearer jry_live_your_api_key"

# por email
curl "https://api-eu1.joryio.com/api/[email protected]" \
  -H "Authorization: Bearer jry_live_your_api_key"

# parcial - cualquier cosa que empiece por "jane", más coincidencia de teléfono e id
curl "https://api-eu1.joryio.com/api/users?q=jane" \
  -H "Authorization: Bearer jry_live_your_api_key"

Qué parámetro​

Lo que tienesUsaCoincidencia
Tu propio id?externalId=exacta
Una dirección de email?email=exacta, sin distinguir mayúsculas
El id interno de Joryio (24 hex)?userId=exacta
Parte de algo: un nombre, el inicio de un email, un teléfono?q=prefijo en email, externalId, nombre y apellidos; dígitos en cualquier parte del teléfono; valor completo para un id de 24 hex o un anonymousId con forma de UUID

Los parámetros exactos se combinan (?email=…&externalId=… exige ambos). q se ignora cuando hay un parámetro exacto: "email igual a X" y "algún campo empieza por Y" no pueden acotar a la vez la misma petición, y combinarlos en silencio respondería a una pregunta que no hiciste.

Cuando no se encuentra nada​

Una página vacía, no un 404:

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

Ordena toda la lista con sortBy (createdAt, updatedAt, email o name; por defecto updatedAt) y sortOrder (asc o desc; por defecto desc). El orden es estable entre páginas: ninguna fila se mueve entre ellas.

Un userId que no tenga 24 caracteres hex devuelve esa misma página vacía en lugar de un error: un id mal formado es una búsqueda que no coincide con nadie, no una petición rota.

Un parámetro que no reconocemos​

Si un parámetro parece una errata de uno real, o si ninguno de tus parámetros se reconoce, la petición se rechaza:

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

Antes esto era un 200 silencioso con la página completa sin filtrar, y así una errata le costó un día a un integrador: un filtro que no hace nada se ve exactamente igual que un filtro que lo encontró todo.

Los parámetros que llegan sin que tú los envíes se siguen aceptando e ignorando: _ y _* (el cache-buster de jQuery), utm_*, gclid, fbclid, msclkid, y t / v / cb. Así que [email protected]&_=1724500000 funciona, y ?_=1724500000 por sí solo también.

Un parámetro desconocido que no se parece a ninguno de los nuestros - por ejemplo el correlation id de una pasarela - también se acepta, siempre que haya al menos un parámetro que entendamos. La regla no es "rechaza lo desconocido", sino "rechaza una petición que no pudo hacer lo que querías".

Las otras dos rutas​

Ambas siguen funcionando. Ninguna hace nada que GET /users no pueda.

RutaSigue siendo útil cuando
GET /users/by-user-id/:externalIdquieres el registro en sí, no una página que lo contiene: devuelve el objeto de usuario directamente
GET /users/search?query=quieres el formato antiguo: un array simple, limitado, sin total

GET /users/:userId (el id interno de Joryio) es la ruta canónica para un único registro y se queda: es a lo que se refiere id en cada respuesta.

Contactos anónimos​

Alguien registrado antes de identificarse no tiene email, ni teléfono, ni nombre. El único asidero que tienes es el anonymousId que generó el SDK, y ?q= lo encuentra cuando el término tiene forma de UUID:

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

Para asociar el historial de esa sesión a una persona conocida, consulta POST /users/identify.

Relacionado​