Report events

curl --request POST \
  --url https://api.topsort.com/v2/events \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "impressions": [
    {
      "occurredAt": "2023-11-07T05:31:56Z",
      "opaqueUserId": "<string>",
      "id": "<string>",
      "resolvedBidId": "<string>",
      "entity": {
        "id": "<string>",
        "type": "product"
      },
      "placement": {
        "path": "<string>",
        "position": 2,
        "page": 2,
        "pageSize": 2,
        "productId": "<string>",
        "categoryIds": [
          "<string>"
        ],
        "searchQuery": "<string>"
      },
      "additionalAttribution": {
        "id": "<string>",
        "type": "product"
      },
      "page": {
        "type": "home",
        "pageId": "<string>",
        "value": "electronics"
      },
      "object": {
        "type": "listing",
        "assetId": "<string>",
        "clickType": "product"
      },
      "externalCampaignId": "<string>",
      "externalVendorId": "<string>",
      "deviceType": "desktop",
      "channel": "onsite"
    }
  ],
  "clicks": [
    {
      "occurredAt": "2023-11-07T05:31:56Z",
      "opaqueUserId": "<string>",
      "id": "<string>",
      "resolvedBidId": "<string>",
      "entity": {
        "id": "<string>",
        "type": "product"
      },
      "placement": {
        "path": "<string>",
        "position": 2,
        "page": 2,
        "pageSize": 2,
        "productId": "<string>",
        "categoryIds": [
          "<string>"
        ],
        "searchQuery": "<string>"
      },
      "additionalAttribution": {
        "id": "<string>",
        "type": "product"
      },
      "page": {
        "type": "home",
        "pageId": "<string>",
        "value": "electronics"
      },
      "object": {
        "type": "listing",
        "assetId": "<string>",
        "clickType": "product"
      },
      "clickType": "product",
      "externalCampaignId": "<string>",
      "externalVendorId": "<string>",
      "deviceType": "desktop",
      "channel": "onsite"
    }
  ],
  "purchases": [
    {
      "occurredAt": "2023-11-07T05:31:56Z",
      "opaqueUserId": "<string>",
      "items": [
        {
          "productId": "<string>",
          "unitPrice": 123,
          "quantity": 1,
          "vendorId": "<string>"
        }
      ],
      "id": "<string>",
      "deviceType": "desktop",
      "channel": "onsite"
    }
  ],
  "pageviews": [
    {
      "page": {
        "type": "home",
        "pageId": "<string>",
        "value": "electronics"
      },
      "occurredAt": "2023-11-07T05:31:56Z",
      "opaqueUserId": "<string>",
      "id": "<string>",
      "deviceType": "desktop",
      "channel": "onsite"
    }
  ]
}
'

{
  "errCode": "bad_request",
  "docUrl": "<string>",
  "message": "<string>"
}

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.
Page views — a user visited a page.

Interactions require either a resolvedBidId, for sponsored events coming from the /v2/auctions response, or an entity that describes the entity that was interacted with, in the case of organic or non-sponsored events. 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

Report events

curl --request POST \
  --url https://api.topsort.com/v2/events \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "impressions": [
    {
      "occurredAt": "2023-11-07T05:31:56Z",
      "opaqueUserId": "<string>",
      "id": "<string>",
      "resolvedBidId": "<string>",
      "entity": {
        "id": "<string>",
        "type": "product"
      },
      "placement": {
        "path": "<string>",
        "position": 2,
        "page": 2,
        "pageSize": 2,
        "productId": "<string>",
        "categoryIds": [
          "<string>"
        ],
        "searchQuery": "<string>"
      },
      "additionalAttribution": {
        "id": "<string>",
        "type": "product"
      },
      "page": {
        "type": "home",
        "pageId": "<string>",
        "value": "electronics"
      },
      "object": {
        "type": "listing",
        "assetId": "<string>",
        "clickType": "product"
      },
      "externalCampaignId": "<string>",
      "externalVendorId": "<string>",
      "deviceType": "desktop",
      "channel": "onsite"
    }
  ],
  "clicks": [
    {
      "occurredAt": "2023-11-07T05:31:56Z",
      "opaqueUserId": "<string>",
      "id": "<string>",
      "resolvedBidId": "<string>",
      "entity": {
        "id": "<string>",
        "type": "product"
      },
      "placement": {
        "path": "<string>",
        "position": 2,
        "page": 2,
        "pageSize": 2,
        "productId": "<string>",
        "categoryIds": [
          "<string>"
        ],
        "searchQuery": "<string>"
      },
      "additionalAttribution": {
        "id": "<string>",
        "type": "product"
      },
      "page": {
        "type": "home",
        "pageId": "<string>",
        "value": "electronics"
      },
      "object": {
        "type": "listing",
        "assetId": "<string>",
        "clickType": "product"
      },
      "clickType": "product",
      "externalCampaignId": "<string>",
      "externalVendorId": "<string>",
      "deviceType": "desktop",
      "channel": "onsite"
    }
  ],
  "purchases": [
    {
      "occurredAt": "2023-11-07T05:31:56Z",
      "opaqueUserId": "<string>",
      "items": [
        {
          "productId": "<string>",
          "unitPrice": 123,
          "quantity": 1,
          "vendorId": "<string>"
        }
      ],
      "id": "<string>",
      "deviceType": "desktop",
      "channel": "onsite"
    }
  ],
  "pageviews": [
    {
      "page": {
        "type": "home",
        "pageId": "<string>",
        "value": "electronics"
      },
      "occurredAt": "2023-11-07T05:31:56Z",
      "opaqueUserId": "<string>",
      "id": "<string>",
      "deviceType": "desktop",
      "channel": "onsite"
    }
  ]
}
'

{
  "errCode": "bad_request",
  "docUrl": "<string>",
  "message": "<string>"
}

Authorizations

Authorization

string

header

required

A valid API key generated in Topsort's UI.

Body

application/json

Event data including impressions, clicks, purchases, and page views.

A batch request containing multiple events to be reported to Topsort.

impressions

Impression · object[]

An array of impression events

Maximum array length: 50

Show child attributes

impressions.occurredAt

string<date-time>

required

A RFC3339 formatted timestamp including UTC offset.

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.

impressions.id

string

required

A unique identifier for the request. 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 string length: 1

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.

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.

Show child attributes

impressions.entity.id

string

required

The marketplace's ID of the entity associated with the interaction.

Minimum string length: 1

impressions.entity.type

enum<string>

required

The type of entity associated with the interaction.

Available options:

product,

vendor

impressions.placement

object

Information about where an ad or product is placed on a page.

Show child attributes

impressions.placement.path

string

required

URL path of the page triggering the event. For web apps, this can be obtained in JS using window.location.pathname. For mobile apps, use the deep link for the current view, if available. Otherwise, encode the view from which the event occurred in your app as a path-like string (e.g. /root/categories/:categoryId).

Minimum string length: 1

impressions.placement.position

integer

For components with multiple items (i.e. search results, similar products, etc), this should indicate the index of a given item within that list.

Required range: x >= 1

impressions.placement.page

integer

For paginated pages, this should indicate which page number triggered the event.

Required range: x >= 1

impressions.placement.pageSize

integer

For paginated pages this should indicate how many items are in each result page.

Required range: x >= 1

impressions.placement.productId

string

The ID of the product associated to the page in which this event occurred, if applicable. This ID must match the ID provided through the catalog service.

Minimum string length: 1

impressions.placement.categoryIds

string[]

An array of IDs of the categories associated to the page in which this event occurred, if applicable. These IDs must match the IDs provided through the catalog service.

Minimum array length: 1

A category ID.

Minimum string length: 1

impressions.placement.searchQuery

string

The search string provided by the user in the page where this event occurred, if applicable. This search string must match the searchQuery field that was provided in the auction request (if provided).

Minimum string length: 1

impressions.additionalAttribution

object

Show child attributes

impressions.additionalAttribution.id

string

required

The marketplace's ID of the entity associated with the interaction.

Minimum string length: 1

impressions.additionalAttribution.type

enum<string>

required

The type of entity associated with the interaction.

Available options:

product,

vendor

impressions.page

Page · object

Information about the page where an auction or event occurs.

Show child attributes

impressions.page.type

enum<string>

required

Type of page.

Available options:

home,

category,

PDP,

search,

cart,

other

impressions.page.pageId

string

required

Identifies the page

impressions.page.value

Detail of the page, depending on the type

Example:

"electronics"

impressions.object

object

Information regarding an organic or non-sponsored event.

Show child attributes

impressions.object.type

enum<string>

required

The type of object that is being reported on the interaction.

Available options:

listing,

banner

impressions.object.assetId

string

When type is banner, signals the ID of the asset of the banner

impressions.object.clickType

enum<string>

When type is listing, signals the specific interaction flavor with the listing.

Available options:

product,

like,

add-to-cart

impressions.externalCampaignId

string

Marketplace provided ID for a campaign

impressions.externalVendorId

string

Marketplace provided ID for a vendor

impressions.deviceType

enum<string>

The device the user is on.

Available options:

desktop,

mobile

impressions.channel

enum<string>

Optional. The channel where the event occurred.

Available options:

onsite,

offsite,

instore

clicks

Click · object[]

An array of click events

Maximum array length: 50

Show child attributes

clicks.occurredAt

string<date-time>

required

A RFC3339 formatted timestamp including UTC offset.

clicks.opaqueUserId

string

required

clicks.id

string

required

Minimum string length: 1

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.

clicks.entity

object

Show child attributes

clicks.entity.id

string

required

The marketplace's ID of the entity associated with the interaction.

Minimum string length: 1

clicks.entity.type

enum<string>

required

The type of entity associated with the interaction.

Available options:

product,

vendor

clicks.placement

object

Information about where an ad or product is placed on a page.

Show child attributes

clicks.placement.path

string

required

Minimum string length: 1

clicks.placement.position

integer

For components with multiple items (i.e. search results, similar products, etc), this should indicate the index of a given item within that list.

Required range: x >= 1

clicks.placement.page

integer

For paginated pages, this should indicate which page number triggered the event.

Required range: x >= 1

clicks.placement.pageSize

integer

For paginated pages this should indicate how many items are in each result page.

Required range: x >= 1

clicks.placement.productId

string

The ID of the product associated to the page in which this event occurred, if applicable. This ID must match the ID provided through the catalog service.

Minimum string length: 1

clicks.placement.categoryIds

string[]

An array of IDs of the categories associated to the page in which this event occurred, if applicable. These IDs must match the IDs provided through the catalog service.

Minimum array length: 1

A category ID.

Minimum string length: 1

clicks.placement.searchQuery

string

Minimum string length: 1

clicks.additionalAttribution

object

Show child attributes

clicks.additionalAttribution.id

string

required

The marketplace's ID of the entity associated with the interaction.

Minimum string length: 1

clicks.additionalAttribution.type

enum<string>

required

The type of entity associated with the interaction.

Available options:

product,

vendor

clicks.page

Page · object

Information about the page where an auction or event occurs.

Show child attributes

clicks.page.type

enum<string>

required

Type of page.

Available options:

home,

category,

PDP,

search,

cart,

other

clicks.page.pageId

string

required

Identifies the page

clicks.page.value

Detail of the page, depending on the type

Example:

"electronics"

clicks.object

object

Information regarding an organic or non-sponsored event.

Show child attributes

clicks.object.type

enum<string>

required

The type of object that is being reported on the interaction.

Available options:

listing,

banner

clicks.object.assetId

string

When type is banner, signals the ID of the asset of the banner

clicks.object.clickType

enum<string>

When type is listing, signals the specific interaction flavor with the listing.

Available options:

product,

like,

add-to-cart

clicks.clickType

enum<string>

For sponsored events only, signals the specific interaction flavor with the listing.

Available options:

product,

like,

add-to-cart

clicks.externalCampaignId

string

Marketplace provided ID for a campaign

clicks.externalVendorId

string

Marketplace provided ID for a vendor

clicks.deviceType

enum<string>

The device the user is on.

Available options:

desktop,

mobile

clicks.channel

enum<string>

Optional. The channel where the event occurred.

Available options:

onsite,

offsite,

instore

purchases

Purchase · object[]

An array of purchase events

Maximum array length: 50

Show child attributes

purchases.occurredAt

string<date-time>

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.

purchases.opaqueUserId

string

required

purchases.items

object[]

required

Items purchased.

Minimum array length: 1

Show child attributes

purchases.items.productId

string

required

The marketplace ID of the product being purchased.

Minimum string length: 1

purchases.items.unitPrice

number<double>

required

The price of a single item in the marketplace currency.

purchases.items.quantity

integer

default:1

Amount of products purchased.

Required range: x >= 1

purchases.items.vendorId

string

The vendor ID of the product being purchased. This field is optional and should be filled in if 1. a product is sold by multiple vendors, or 2. you want to use it for halo attribution

Minimum string length: 1

purchases.id

string

required

Minimum string length: 1

purchases.deviceType

enum<string>

The device the user is on.

Available options:

desktop,

mobile

purchases.channel

enum<string>

Optional. The channel where the event occurred.

Available options:

onsite,

offsite,

instore

pageviews

Page View · object[]

An array of page views

Maximum array length: 50

Show child attributes

pageviews.page

Page · object

required

Information about the page where an auction or event occurs.

Show child attributes

pageviews.page.type

enum<string>

required

Type of page.

Available options:

home,

category,

PDP,

search,

cart,

other

pageviews.page.pageId

string

required

Identifies the page

pageviews.page.value

Detail of the page, depending on the type

Example:

"electronics"

pageviews.occurredAt

string<date-time>

required

A RFC3339 formatted timestamp including UTC offset.

pageviews.opaqueUserId

string

required

pageviews.id

string

required

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

Minimum string length: 1

pageviews.deviceType

enum<string>

The device the user is on.

Available options:

desktop,

mobile

pageviews.channel

enum<string>

Optional. The channel where the event occurred.

Available options:

onsite,

offsite,

instore

Response

All events were reported successfully.

Create travel auctions [Beta] Report Link Users

⌘I

General

Auction examples

Webhook examples

Auctions

Events

Toptimize

Toppie API

Campaign API

Catalog API

Billing API

Reporting API

Invitation API

User API

Webhooks API

Assets API

Segments Service

Offsite Ads API

Forecasting Service

Media API

API Reference

Report events

Authorizations

Body

Response