Skip to content
Toposort Logo
ad-server

Events API

Tracking interaction (impressions, clicks, purchases) with our Events API is essential to the auction engine to optimize bids accordingly, and for metrics and performance reporting. Topsort does not collect personal data and only uses the Opaque User IDs provided by the marketplace.

Topsort tracks three main types of events:

  • Pageviews: triggered when a page is viewed by the end user
  • Impressions: triggered when an ad is visible to the end user.
  • Clicks: triggered when the end user clicks on the ad.
  • Purchases: triggered when the user completes a purchase with the promoted item. The purchase can include multiple products, and should always include the Opaque User ID for proper attribution.

Events with a resolvedBidId will be tied to a campaign. If it’s not provided, the event will be registered as an organic event. The marketplace can decide to send organic events to Topsort to enable the calculation of incrementality.

Link Users

Topsort allows linking two different opaque user IDs together, often used for attributing activity across logged-out and logged-in sessions.

Attribution Engine

Purchases are matched against events for attribution purposes, based on the Opaque User ID and the parameters defined for the marketplace. For example, if you have in place a “Last Click” strategy in place, with an attribution window of 14 days, purchases made by Opaque User IDs that clicked the ad will be attributed to the last registered click inside the 14 days window. Check our knowledge base for more details on attribution.

Reporting

Events and metrics are calculated and retrievable using:

  1. Topsort’s UI
  2. Our Reporting API
  3. The Data Room - An advanced analytics tool designed to centralize all data sources and to allow the creation of queries, reports and dashboards.

Handling errors

On successful event requests, you will receive a 204 No Content response. If there is an error, you will receive a 4xx or 5xx response. Pay attention to the response body for more information on the error.

We only store events that return 2xx responses. Please note that if you send an array of 200 events and one fails, none will be recorded.