Skip to main content

​
CDS - Engagement Events

Send real-time user interaction data to Sequen’s Large Event Models (LEMs) via the Engagement Events endpoint. This data is crucial for training models and enabling in-session personalization.

​
Endpoint

POST /catalog/engagement

​
Request Body

The request body should be a JSON object representing a single event, OR a JSON array containing multiple event objects for bulk submission. Single Event:
FieldTypeRequiredDescription
typeStringYesType of event (e.g., view, click, purchase, add_to_cart, search).
userIdStringYesUnique identifier for the user performing the action.
sessionIdStringYesUnique identifier for the user’s current session.
timestampStringYesISO 8601 formatted timestamp of when the event occurred (UTC recommended).
propertiesObjectYesA JSON object containing contextual details about the event.
Bulk Events: Send a JSON array where each element is a complete event object as described above.
Bulk Request Structure
[
  { "type": "...", "userId": "...", ... },
  { "type": "...", "userId": "...", ... },
  ...
]

​
Properties Object

The properties object can contain any relevant key-value pairs. Include as much context as possible, even unstructured data. Examples:
  • item_id: Identifier of the item involved (e.g., product SKU).
  • item_list_id: Identifier for a list the item appeared in (e.g., category page, search results ID).
  • page_type: Type of page where the event occurred (e.g., product_detail, category, checkout).
  • query: The search query used (for search or click events from search).
  • order_id: Identifier for a purchase event.
  • total_value: Total value of an order.
  • currency: Currency code (e.g., USD).
  • Custom attributes: color, size, category_path, device information, etc.

​
Example Requests

Example Body
{
  "type": "add_to_cart",
  "userId": "user_f9b3d",
  "sessionId": "session_k2p0a",
  "timestamp": "2024-07-27T10:30:00Z",
  "properties": {
    "item_id": "SKU-12345-BLK-L",
    "page_type": "product_detail",
    "quantity": 1,
    "price": 59.99,
    "currency": "USD",
    "category_path": "Apparel > Tops > T-Shirts",
    "color": "Black",
    "size": "L"
  }
}

​
Responses

  • 202 Accepted: The event was successfully received and queued for processing.
  • 400 Bad Request: The request body is malformed or missing required fields. The response body will contain details.
  • 401 Unauthorized: Invalid or missing API key.
  • 429 Too Many Requests: Rate limit exceeded.
  • 5xx Server Error: An internal error occurred.
Sending rich, timely event data is critical to Sequen’s performance. Ensure you track all relevant user interactions.