Auction examples
- Running auctions
- Sponsored listings
- Sponsored banners
- Sponsored brands
Asset examples
Webhook examples
Events
Audience API
Billing API
Campaign API
- GETGet Campaigns
- POSTCreate Campaign
- GETGet Campaign By Id
- DELDelete Campaign By Id
- PATCHUpdate Campaign By Id
- GETGet Campaign Bids
- POSTCreate Campaign Bids
- DELDelete Campaign Bid By Id
- PATCHUpdate Campaign Bid By Id
- POST[BETA] Get estimated clicks of a future campaign for a given vendor
- GETGet Products In Campaign
- GETGet Sponsored Products
Catalog API
Invitation API
Modal API
Reporting API
Assets API
Audience API
Billing API
Campaign API
- GETGet Campaigns
- POSTCreate Campaign
- GETGet Campaign By Id
- DELDelete Campaign By Id
- PATCHUpdate Campaign By Id
- GETGet Campaign Bids
- POSTCreate Campaign Bids
- DELDelete Campaign Bid By Id
- PATCHUpdate Campaign Bid By Id
- POST[BETA] Get estimated clicks of a future campaign for a given vendor
- GETGet Products In Campaign
- GETGet Sponsored Products
Catalog API
Invitation API
Modal API
Reporting API
Toppie API
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.
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 has no body data.Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Body
RFC3339 formatted timestamp including UTC offset.
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.
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.
1If 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.
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.
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).
1For components with multiple items (i.e. search results, similar products, etc), this should indicate the index of a given item within that list.
x > 1For paginated pages, this should indicate which page number triggered the event.
x > 1For paginated pages this should indicate how many items are in each result page.
x > 1The 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.
1An 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.
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).
1If 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.
RFC3339 formatted timestamp including UTC offset.
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.
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.
1If 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.
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.
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).
1For components with multiple items (i.e. search results, similar products, etc), this should indicate the index of a given item within that list.
x > 1For paginated pages, this should indicate which page number triggered the event.
x > 1For paginated pages this should indicate how many items are in each result page.
x > 1The 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.
1An 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.
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).
1If 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.
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.
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.
Items purchased.
The marketplace ID of the product being purchased.
1The price of a single item in the marketplace currency.
x > 0Count of products purchased.
x > 1The 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
1The 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.
1curl --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 has no body data.