Send the search event every time:
A user performs a new search.
The user changes the sorting option.
The user applies or removes a filter (facet).
The user navigates to a different page (pagination).
Step 1: Build the payload
For the complete list of all fields (including optional ones), where to get each value, refer to the Common Properties article.
All fields:
Field | Value | Notes |
|---|---|---|
eventType | “search” | Required. Always "search" |
source | search-popup or search-listing | Required. Where the search happens |
query | User's search text | Required. Must not be empty or whitespace-only |
userId | Unique user ID | Required. No spaces. Defaults to "default" if empty |
platform | desktop-web, mobile-web, tablet-web, ios, android, other | Required |
integrationType | “api” | Required. Use "api" for direct API integration |
traceId | Unique trace ID per query | Required. No spaces. Primary identifier for the current query |
searchSessionId | Unique session ID | Optional. Deprecated → use traceId instead. Falls back bidirectionally with traceId. |
sorting | "Relevancy", "PriceAsc", "PriceDesc", etc. | Required |
resultCount | Total results count | Required (unless no results). Min: 1. Set to 0 for no results |
itemsPerPage | Items per page | Required (unless no results). Min: 1 |
totalPages | Total number of pages | Required (unless no results). Min: 1 |
currentPage | Current page number | Required (unless no results). Min: 1 |
products | Array of products | Required (unless no results) |
referrer | Source URL | Required. Must be a valid URL |
createdAt | RFC 3339 timestamp | Optional. e.g. "2025-11-25T10:30:00Z". Defaults to the current time if omitted |
campId | Campaign ID (integer) | Optional. Defaults to 999999 |
variationId | Variation ID (integer) | Optional. Defaults to 999999 |
sessionId | Browser/app session ID | Optional. No spaces |
strategyId | Strategy identifier | Optional. No spaces |
facets | List of facets | Optional. Required if any facet is selected |
Refer to Common Properties for further details.
All product fields (each item in the products array):
Field | Required | Notes |
|---|---|---|
id | Yes | Product identifier. No spaces |
groupCode | No | Variant group code. Needed for group-level analytics |
price | Yes | Min: 0 |
convertedPrice | No | Converted price. Falls back to price if not provided |
currency | Yes | ISO 4217 code (e.g., "USD", "TRY"). No spaces |
preferredCurrency | No | Falls back to currency if not provided |
position | No | Legacy position field. Used as fallback if neither searchPosition nor displayPosition is set |
searchPosition | No | Original search position in results. Falls back to displayPosition, then position |
displayPosition | Yes | Position on the page (1-indexed, min: 1). Falls back to searchPosition chain if not set |
isMerchandisedItem | No | true if positioned by merchandising rules. Defaults to false |
Step 2: Send the Request
curl --location --request POST 'https://eurekaevent.api.useinsider.com/api/v1/events' \
--header 'x-auth-token: YOUR_AUTH_TOKEN' \
--header 'x-partner-config-key: YOUR_PARTNERID-YOUR_LOCALE' \
--header 'Content-Type: application/json' \
--data-raw '{
"eventType": "search",
"source": "search-listing",
"query": "queryA",
"userId": "user-123",
"platform": "desktop-web",
"searchSessionId": "sess-abc-123",
"sorting": "Relevancy",
"integrationType": "api",
"referrer": "https://example.com/search",
"resultCount": 25,
"itemsPerPage": 10,
"totalPages": 3,
"currentPage": 1,
"products": [
{
"id": "product-001",
"groupCode": "group-1",
"price": 999.99,
"currency": "USD",
"displayPosition": 1
},
{
"id": "product-002",
"groupCode": "group-2",
"price": 1299.99,
"currency": "USD",
"displayPosition": 2
}
]
}'No Results Request
When the search returns no results, send resultCount: 0 without products:
curl --location --request POST 'https://eurekaevent.api.useinsider.com/api/v1/events' \
--header 'x-auth-token: YOUR_AUTH_TOKEN' \
--header 'x-partner-config-key: YOUR_PARTNERID-YOUR_LOCALE' \
--header 'Content-Type: application/json' \
--data-raw '{
"eventType": "search",
"source": "search-listing",
"query": "xyznonexistent",
"userId": "user-123",
"platform": "desktop-web",
"searchSessionId": "sess-def-456",
"sorting": "Relevancy",
"integrationType": "api",
"referrer": "https://example.com/search",
"resultCount": 0
}'Step 3: Validate the Response
Success:
{ "status": "Success", "code": 200 }Validation Error:
{
"status": "ValidationException",
"code": 400,
"message": "Validation Error Occurred",
"validations": [
"Key: 'Search.SearchSessionId' Error:Field validation for 'SearchSessionId' failed on the 'required' tag"
]
}Product Deduplication Rule
For the same traceId, a product must be sent only once. Even if the user changes sorting, pagination, or filters, do not resend the same product under the same traceId.
Example:
User searches "queryA" → traceId "x123" → Products A, B, C sent
User changes sorting → still traceId "x123" → Products A, D, E returned
Only send D and E (A was already sent for "x123")