Sign in

Search customers by event

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

Returns the audience (the list of customers) who have a recorded event in person_event of a given type, optionally narrowed by free-text terms and a date window. This is the generic, event-based audience search — the same engine behind the QON event filter, exposed as a simple GET.

Generic by type:

  • type=buy_product — customers who bought a product; terms[] match the product name (description), all terms ANDed (substring, case- and accent-insensitive). e.g. terms[]=tennis&terms[]=preto matches a customer who bought "calçado tennis nike 42 preto e branco".
  • type=membership_joined — customers who joined in the window; no terms (membership events have no description).
  • any future event type (abandoned_cart, app_open, …) works the same way.

from/to (YYYY-MM-DD) bound occurredAt (to is exclusive at the next day).

Scope: this endpoint resolves the event criteria only. Demographic/behavioral composition (gender, age, RFM, tag, tier) is the audience builder's responsibility via the QON event filter — see Internal › Services › Register › Audiência por evento.

Auth: service-to-service RSA signature (see Internal › Integração › Signature). Organization is taken from the request context.

Worked examples

Customers who bought a product whose name contains "tennis" AND "preto", in 2026:

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

Customers who joined membership in the same window (no terms):

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

Response (AudienceResult — paginated; entries=0 streams all rows):

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


Authentication

Token

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

Headers

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.

Query parameters

Name Type Description
type * string Event type recorded in `person_event` (e.g. `buy_product`, `membership_joined`).
terms array Free-text terms matched against the event `description` (the product name, for `buy_product`). All terms are ANDed (substring, case- and accent-insensitive). Use repeated `terms[]=a&terms[]=b`. Event types without a `description` (e.g. membership) ignore this.
from string Lower bound (inclusive) on `occurredAt` (`YYYY-MM-DD`).
to string Upper bound on `occurredAt`, exclusive at the next day (`YYYY-MM-DD`).
entries integer Page size. `0` returns all matches (streaming).
page integer Page number (1-based).

Responses

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