Skip to main content
The Events API allows you to send real-time user interaction data to Topsort. This data powers campaign attribution, reporting, and optimization algorithms.

​
Event Types

Topsort tracks three core event types:
EventDescriptionWhen to Send
ImpressionUser views a promoted productWhen a sponsored product is rendered on screen
ClickUser clicks on a promoted productWhen a user clicks a sponsored product
PurchaseUser completes a transactionWhen an order is confirmed

​
Integration Options

Direct API

Send events directly to Topsort’s Events API for maximum control and flexibility.

Analytics.js

Use our JavaScript SDK for easy client-side event tracking.

Twilio Segment

Route events through Segment if you’re already using it for analytics.

RudderStack

Integrate via RudderStack for unified event routing.

​
Key Concepts

​
Resolved Bid ID

The resolvedBidId is a unique identifier returned from the Auctions API that links an event to a specific auction winner. This is required for impression and click events to enable proper attribution. 
{
  "impressions": [
    {
      "resolvedBidId": "WyJiX01mazE1IiwiMTJhNTU4MjgtOGVh...",
      "occurredAt": "2023-05-01T12:00:00Z"
    }
  ]
}

​
Event Attribution

Events are attributed to campaigns based on:
  • Direct attribution: User interacts with a promoted product and converts
  • Halo attribution: User views a promoted product but purchases a different product from the same vendor
Learn more about attribution models.

​
Implementation Steps

1

Store the Resolved Bid ID

When displaying auction winners, store the resolvedBidId from the auction response.
2

Track Impressions

Send an impression event when a sponsored product becomes visible to the user.
3

Track Clicks

Send a click event when a user clicks on a sponsored product.
4

Track Purchases

Send purchase events when orders are completed, including all purchased products.

​
Example: Sending Events

curl -X POST https://api.topsort.com/v2/events \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "impressions": [
      {
        "resolvedBidId": "WyJiX01mazE1IiwiMTJhNTU4...",
        "occurredAt": "2023-05-01T12:00:00Z"
      }
    ],
    "clicks": [
      {
        "resolvedBidId": "WyJiX01mazE1IiwiMTJhNTU4...",
        "occurredAt": "2023-05-01T12:00:05Z"
      }
    ]
  }'

​
Next Steps