Entrar

Buscar clientes por evento

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

Retorna a audiência (a lista de clientes) que têm um evento registrado em person_event de um dado type, opcionalmente filtrado por termos de texto livre e uma janela de data. É a busca de audiência genérica por evento — o mesmo motor do filtro QON event, exposto como um GET simples.

Genérico por type:

  • type=buy_product — clientes que compraram um produto; terms[] casam o nome do produto (description), todos os termos com AND (substring, insensível a caixa e acento). Ex.: terms[]=tennis&terms[]=preto casa quem comprou "calçado tennis nike 42 preto e branco".
  • type=membership_joined — clientes que se inscreveram na janela; sem terms (eventos de membership não têm description).
  • qualquer tipo futuro (abandoned_cart, app_open, …) funciona igual.

from/to (YYYY-MM-DD) limitam occurredAt (to é exclusivo no dia seguinte).

Escopo: este endpoint resolve só o critério de evento. A composição demográfica/comportamental (gênero, idade, RFM, tag, tier) é responsabilidade do audience builder via o filtro QON event — ver Internal › Services › Register › Audiência por evento.

Auth: signature RSA serviço-a-serviço (ver Internal › Integração › Signature). A organização vem do contexto da requisição.

Exemplos na prática

Clientes que compraram um produto cujo nome contém "tennis" E "preto", em 2026:

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

Clientes que se inscreveram (membership) na mesma janela (sem termos):

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

Resposta (AudienceResult — paginado; entries=0 faz streaming de tudo):

{
    "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)


Autenticação

Token

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

Cabeçalhos

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 em `person_event` (ex.: `buy_product`, `membership_joined`).
terms array Termos de texto livre casados contra o `description` do evento (o nome do produto, no `buy_product`). Todos os termos com AND (substring, insensível a caixa/acento). Use repetido `terms[]=a&terms[]=b`. Tipos sem `description` (ex.: membership) ignoram.
from string Limite inferior (inclusivo) de `occurredAt` (`YYYY-MM-DD`).
to string Limite superior de `occurredAt`, exclusivo no dia seguinte (`YYYY-MM-DD`).
entries integer Tamanho da página (default 50). `0` retorna todos (streaming).
page integer Número da página (começa em 1).

Respostas

{
    "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