Entrar

Buscar clientes por evento

GET https://{organization}.myguper.com/api/register/event/search

Devuelve la audiencia (la lista de clientes) que tienen un evento registrado en person_event de un type dado, opcionalmente acotado por términos de texto libre y una ventana de fechas. Es la búsqueda de audiencia genérica por evento — el mismo motor del filtro QON event, expuesto como un GET simple.

Genérico por type:

  • type=buy_product — clientes que compraron un producto; terms[] coinciden con el nombre del producto (description), todos los términos con AND (subcadena, insensible a mayúsculas y acentos). Ej.: terms[]=tennis&terms[]=preto coincide con quien compró "calçado tennis nike 42 preto e branco".
  • type=membership_joined — clientes que se inscribieron en la ventana; sin terms (los eventos de membership no tienen description).
  • cualquier tipo futuro (abandoned_cart, app_open, …) funciona igual.

from/to (YYYY-MM-DD) acotan occurredAt (to es exclusivo al día siguiente).

Alcance: este endpoint resuelve solo el criterio de evento. La composición demográfica/conductual (género, edad, RFM, tag, tier) es responsabilidad del audience builder vía el filtro QON event — ver Internal › Services › Register › Audiência por evento.

Auth: signature RSA servicio-a-servicio (ver Internal › Integração › Signature). La organización se toma del contexto de la petición.

Ejemplos prácticos

Clientes que compraron un producto cuyo nombre contiene "tennis" Y "preto", en 2026:

GET /api/register/event/search?type=buy_product&terms[]=tennis&terms[]=preto&from=2026-01-01&to=2026-07-01

Clientes que se inscribieron (membership) en la misma ventana (sin términos):

GET /api/register/event/search?type=membership_joined&from=2026-01-01&to=2026-07-01

Respuesta (AudienceResult — paginado; entries=0 hace streaming de todo):

{
    "total": 144262,
    "data": [
        { "id": 4293432, "name": "John Doe", "email": "j@x.com", "gender": "male" }
    ],
    "pagination": { "entries": 50, "totalPages": 2886, "currentPage": 1, "isInitial": true, "isEnd": false }
}

Try-it values populated from environment ACME (Demo)


Autenticación

Token

Send your user token in the x-guper-authorization header.

Encabezados

Name Type Description
x-guper-authorization * string User token issued by Guper.
Content-Type * string Always `application/json` for endpoints that accept a JSON body.

Parámetros de query

Name Type Description
type * string Tipo de evento registrado en `person_event` (ej.: `buy_product`, `membership_joined`).
terms array Términos de texto libre comparados contra el `description` del evento (el nombre del producto, en `buy_product`). Todos los términos con AND (subcadena, insensible a mayúsculas/acentos). Use repetido `terms[]=a&terms[]=b`. Los tipos sin `description` (ej.: membership) lo ignoran.
from string Límite inferior (inclusivo) de `occurredAt` (`YYYY-MM-DD`).
to string Límite superior de `occurredAt`, exclusivo al día siguiente (`YYYY-MM-DD`).
entries integer Tamaño de página (default 50). `0` devuelve todos (streaming).
page integer Número de página (empieza en 1).

Respuestas

{
    "total": 144262,
    "data": [
        { "id": 4293432, "name": "John Doe", "email": "j@x.com", "gender": "male" }
    ],
    "pagination": { "entries": 50, "totalPages": 2886, "currentPage": 1, "isInitial": true, "isEnd": false }
}
Copied to clipboard