Events

Report events

Use the /events endpoint to report user interactions and activity in on a marketplace:

Impressions — a user viewed an asset.
Clicks — a user clicked on an asset.
Purchases — a user created an order.

Interactions require either a resolvedBidId from the /v2/auctions response or an entity that describes the entity to attribute.

For analytics purposes, you can use the placement field to differentiate different listings or banners. For example, on a product page with a carousel of products, you can track impressions and clicks related to the carousel by including /carousel at the end of the path field in the placement object. This allows you to monitor the performance of carousel products in the Data Room.

POST

events

curl --request POST \
  --url https://api.topsort.com/v2/events \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "impressions": [
    {
      "id": "eb874c98-bf4d-40a9-ae6d-fcf4cecb535c",
      "occurredAt": "2019-01-01T12:59:59-05:00",
      "opaqueUserId": "71303ce0-de89-496d-8270-6434589615e8",
      "placement": {
        "path": "/categories/dairy",
        "position": 1,
        "page": 1,
        "pageSize": 15,
        "categoryId": "9BLIe"
      },
      "resolvedBidId": "WyJiX01mazE1IiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0="
    }
  ],
  "clicks": [
    {
      "id": "b39d39ed-ea0e-4059-9d15-4990b39c85a2",
      "occurredAt": "2019-01-01T13:01:42-05:00",
      "opaqueUserId": "71303ce0-de89-496d-8270-6434589615e8",
      "placement": {
        "path": "/categories/dairy",
        "position": 1,
        "page": 1,
        "pageSize": 15,
        "categoryId": "9BLIe"
      },
      "resolvedBidId": "WyJiX01mazE1IiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0="
    }
  ],
  "purchases": [
    {
      "id": "0e06c899-b2cd-4e0d-b0de-8aefb4b6d0a0",
      "items": [
        {
          "productId": "p_SA0238",
          "unitPrice": 12.95,
          "quantity": 2,
          "vendorId": "v_8fj2D"
        },
        {
          "productId": "p_oajf2D",
          "unitPrice": 1.49
        }
      ],
      "occurredAt": "2019-01-01T12:59:59-05:00",
      "opaqueUserId": "71303ce0-de89-496d-8270-6434589615e8"
    }
  ]
}'

This response does not have an example.

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

impressions

object[]

An impression means a promotable has become visible to the consumer. For promoted entities, include the resolvedBidId field from the /v2/auctions response. For unpromoted entities, include the entity field to describe what was seen. In case you cannot send an impression when the product becomes visible, send us an impression event when the product was rendered in the HTML or, if that's also not possible, when your API returns the results. It is important to select the most specific event so that your vendors have more accurate CTR metrics, which will allow them to better predict their campaigns.

impressions.occurredAt

string

required

RFC3339 formatted timestamp including UTC offset.

Example:

"2009-01-01T12:59:59-05:00"

impressions.opaqueUserId

string

required

The opaque user ID is an anonymized unique identifier that maps to the original user ID without revealing the original value. This identifier allows Topsort to correlate user activity between auctions and user interactions, independent of the user's logged-in status. For apps or sites where users might interact while logged out, we recommend generating a random identifier (UUIDv7) on the first load, storing it on local storage (cookie, local storage, etc), and letting it live for at least a year. Otherwise, if your users are always logged in for interactions, you may use a hash of your customer ID. Correct purchase attribution requires long-lived opaque user IDs consistent between auction and event requests.

Example:

"71303ce0-de89-496d-8270-6434589615e8"

impressions.id

string

required

The marketplace's unique ID for the impression. This field ensures the event reporting is idempotent in case there is a network issue and the request is retried. If there is no impression model on the marketplace side, generate a unique string that does not change if the event is resent.

Minimum length: 1

Example:

"eb874c98-bf4d-40a9-ae6d-fcf4cecb535c"

impressions.resolvedBidId

string

If the impression is over an ad promotion, this is the resolvedBidId field received from the /auctions request. In most situations, especially when reporting a sponsored interaction, you'll want to fill in this field.

Example:

"WyJiX01mazE1IiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0="

impressions.entity

object

Entity is meant for reporting organic events, not sponsored or promoted products. It refers to the object involved in the organic interaction. But, in most cases, you won't need to fill in this object. Be aware that if resolvedBidId has any value, entity will be disregarded.

impressions.placement

object

impressions.additionalAttribution

object

If the marketplace wants to attribute an impression to an additional entity, they can use the additionalAttribution field. When using this field, the resolvedBidId must also exist in the event body.

clicks

object[]

A click is sent to Topsort when the consumer has clicked on a promotable. For promoted entities, include the resolvedBidId field from the /v2/auctions response. For unpromoted entities, include the entity field to describe what was clicked. Topsort charges the vendor and pays the marketplace for clicks on ads in promoted placements on the marketplace app.

clicks.occurredAt

string

required

RFC3339 formatted timestamp including UTC offset.

Example:

"2009-01-01T12:59:59-05:00"

clicks.opaqueUserId

string

required

Example:

"71303ce0-de89-496d-8270-6434589615e8"

clicks.id

string

required

The marketplace's unique ID for the click. This field ensures the event reporting is idempotent in case there is a network issue and the request is retried. If there is no click model on the marketplace side, generate a unique string that does not change if the event is resent.

Minimum length: 1

Example:

"b39d39ed-ea0e-4059-9d15-4990b39c85a2"

clicks.resolvedBidId

string

If the click is over an ad promotion, this is the resolvedBidId field received from the /auctions request. In most situations, especially when reporting a sponsored interaction, you'll want to fill in this field.

Example:

"WyJiX01mazE1IiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0="

clicks.entity

object

clicks.placement

object

clicks.additionalAttribution

object

If the marketplace wants to attribute a click to an additional entity, they can use the additionalAttribution field. When using this field, the resolvedBidId must also exist in the event body.

purchases

object[]

A purchase is sent to Topsort once a marketplace customer places an order. These events are used to measure the effectiveness of an ad campaign.

purchases.occurredAt

string

required

RFC3339 formatted timestamp, including UTC offset, of the instant in which the order was placed. Please note that purchases will NOT be attributed to an auction that happened after.

Example:

"2021-10-12T07:20:50.52Z"

purchases.opaqueUserId

string

required

Example:

"71303ce0-de89-496d-8270-6434589615e8"

purchases.items

object[]

required

Items purchased.

purchases.id

string

required

The marketplace unique ID for the order. This field ensures the event reporting is idempotent in case there is a network issue and the request is retried. If there is no unique ID for orders on the marketplace side, generate a unique string that does not change if the event needs to be resent.

Minimum length: 1

Example:

"0e06c899-b2cd-4e0d-b0de-8aefb4b6d0a0"

Response

204

_mintlify/placeholder

All events were reported successfully.

Create travel auctions [Beta] Report Link Users

curl --request POST \
  --url https://api.topsort.com/v2/events \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "impressions": [
    {
      "id": "eb874c98-bf4d-40a9-ae6d-fcf4cecb535c",
      "occurredAt": "2019-01-01T12:59:59-05:00",
      "opaqueUserId": "71303ce0-de89-496d-8270-6434589615e8",
      "placement": {
        "path": "/categories/dairy",
        "position": 1,
        "page": 1,
        "pageSize": 15,
        "categoryId": "9BLIe"
      },
      "resolvedBidId": "WyJiX01mazE1IiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0="
    }
  ],
  "clicks": [
    {
      "id": "b39d39ed-ea0e-4059-9d15-4990b39c85a2",
      "occurredAt": "2019-01-01T13:01:42-05:00",
      "opaqueUserId": "71303ce0-de89-496d-8270-6434589615e8",
      "placement": {
        "path": "/categories/dairy",
        "position": 1,
        "page": 1,
        "pageSize": 15,
        "categoryId": "9BLIe"
      },
      "resolvedBidId": "WyJiX01mazE1IiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0="
    }
  ],
  "purchases": [
    {
      "id": "0e06c899-b2cd-4e0d-b0de-8aefb4b6d0a0",
      "items": [
        {
          "productId": "p_SA0238",
          "unitPrice": 12.95,
          "quantity": 2,
          "vendorId": "v_8fj2D"
        },
        {
          "productId": "p_oajf2D",
          "unitPrice": 1.49
        }
      ],
      "occurredAt": "2019-01-01T12:59:59-05:00",
      "opaqueUserId": "71303ce0-de89-496d-8270-6434589615e8"
    }
  ]
}'

This response does not have an example.

General

Auction examples

Asset examples

Webhook examples

Auctions

Events

Toptimize

Assets API

Billing API

Campaign API

Catalog API

Invitation API

Modal API

Reporting API

Segments Service

Toppie API

User API

Webhooks API

Report events

Authorizations

Body

Response