Skip to content
Topsort Documentation
API

Report an event

POST
/events

Authentication

Topsort’s APIs are authenticated via bearer tokens. Requests must include an authorization header containing your private API key.

Don't have an API key yet? Learn how to generate one.

Authorization
required
string

The header containing a private API key. Format this header as follows:

Authorization: Bearer <YOUR-API-KEY>

Request Body

Use the /events endpoint to notify Topsort about significant consumer interactions on the e-commerce site: impressions — product links become visible to the consumer; clicks — the consumer clicks on a product link; and purchases — the consumer buys some products.

One of:

A product has become visible to the consumer. In case you cannot send the impression when the product is 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 allow them to better predict their campaigns.

object
eventType
required

Discriminator for the type of event.

string
Allowed values: Impression
session
required

The Session object allows correlating user activity during a session whether or not they are actually logged in.

object
sessionId
required

Long-lived token identifying the customer interacting with the marketplace. If your users are always logged in you may use a hash of your customer ID. If your users may interact with your app or site while logged out we recommend generating a random identifier (UUIDv4) on first load and store it on local storage (cookie, local storage, etc) and let it live for at least a year.

string
>= 1 characters
impressions
required
Array<object>
>= 1 items
object
placement
required
object
page
required

A marketplace assigned name for a page.

string
>= 1 characters
location

A marketplace defined name for a page part.

string
>= 1 characters
productId

The product that was rendered.

string
auctionId

Required for promoted products. Must be the ID for the auction the product won.

string
>= 1 characters
id

The marketplace’s ID for the impression.

string
>= 1 characters
resolvedBidId
string
>= 1 characters
occurredAt

RFC3339 formatted timestamp including UTC offset

string format: date-time

Responses

An object containing the markeplace ID for the event and the Topsort ID for the same event. Logging this can facilitate debugging. The field name for the TopsortID will be “impressionID”, “clickId” or “purchaseId” depending on the event in the request.

One of:
object
impressions

The collection of all impressions that were processed correctly.

Array<object>
object
impressionId
required

Topsort assigned ID for the impression.

string
id

The marketplace’s ID for the impression, if provided.

string