Report events

curl --request POST \
  --url https://api.topsort.com/v2/events \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "renders": [
    {
      "id": "3f2b9c14-7a1d-4e2b-9c3a-1b2c3d4e5f60",
      "occurredAt": "2019-01-01T12:59:58-05:00",
      "opaqueUserId": "71303ce0-de89-496d-8270-6434589615e8",
      "resolvedBidId": "WyJiX01mazE1IiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0=",
      "placement": {
        "path": "/categories/dairy",
        "position": 1,
        "page": 1,
        "pageSize": 15,
        "categoryIds": [
          "9BLIe"
        ]
      },
      "deviceType": "mobile",
      "channel": "onsite"
    }
  ]
}
'

import requests

url = "https://api.topsort.com/v2/events"

payload = { "renders": [
        {
            "id": "3f2b9c14-7a1d-4e2b-9c3a-1b2c3d4e5f60",
            "occurredAt": "2019-01-01T12:59:58-05:00",
            "opaqueUserId": "71303ce0-de89-496d-8270-6434589615e8",
            "resolvedBidId": "WyJiX01mazE1IiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0=",
            "placement": {
                "path": "/categories/dairy",
                "position": 1,
                "page": 1,
                "pageSize": 15,
                "categoryIds": ["9BLIe"]
            },
            "deviceType": "mobile",
            "channel": "onsite"
        }
    ] }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    renders: [
      {
        id: '3f2b9c14-7a1d-4e2b-9c3a-1b2c3d4e5f60',
        occurredAt: '2019-01-01T12:59:58-05:00',
        opaqueUserId: '71303ce0-de89-496d-8270-6434589615e8',
        resolvedBidId: 'WyJiX01mazE1IiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0=',
        placement: {
          path: '/categories/dairy',
          position: 1,
          page: 1,
          pageSize: 15,
          categoryIds: ['9BLIe']
        },
        deviceType: 'mobile',
        channel: 'onsite'
      }
    ]
  })
};

fetch('https://api.topsort.com/v2/events', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.topsort.com/v2/events",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'renders' => [
        [
                'id' => '3f2b9c14-7a1d-4e2b-9c3a-1b2c3d4e5f60',
                'occurredAt' => '2019-01-01T12:59:58-05:00',
                'opaqueUserId' => '71303ce0-de89-496d-8270-6434589615e8',
                'resolvedBidId' => 'WyJiX01mazE1IiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0=',
                'placement' => [
                                'path' => '/categories/dairy',
                                'position' => 1,
                                'page' => 1,
                                'pageSize' => 15,
                                'categoryIds' => [
                                                                '9BLIe'
                                ]
                ],
                'deviceType' => 'mobile',
                'channel' => 'onsite'
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.topsort.com/v2/events"

	payload := strings.NewReader("{\n  \"renders\": [\n    {\n      \"id\": \"3f2b9c14-7a1d-4e2b-9c3a-1b2c3d4e5f60\",\n      \"occurredAt\": \"2019-01-01T12:59:58-05:00\",\n      \"opaqueUserId\": \"71303ce0-de89-496d-8270-6434589615e8\",\n      \"resolvedBidId\": \"WyJiX01mazE1IiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0=\",\n      \"placement\": {\n        \"path\": \"/categories/dairy\",\n        \"position\": 1,\n        \"page\": 1,\n        \"pageSize\": 15,\n        \"categoryIds\": [\n          \"9BLIe\"\n        ]\n      },\n      \"deviceType\": \"mobile\",\n      \"channel\": \"onsite\"\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.topsort.com/v2/events")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"renders\": [\n    {\n      \"id\": \"3f2b9c14-7a1d-4e2b-9c3a-1b2c3d4e5f60\",\n      \"occurredAt\": \"2019-01-01T12:59:58-05:00\",\n      \"opaqueUserId\": \"71303ce0-de89-496d-8270-6434589615e8\",\n      \"resolvedBidId\": \"WyJiX01mazE1IiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0=\",\n      \"placement\": {\n        \"path\": \"/categories/dairy\",\n        \"position\": 1,\n        \"page\": 1,\n        \"pageSize\": 15,\n        \"categoryIds\": [\n          \"9BLIe\"\n        ]\n      },\n      \"deviceType\": \"mobile\",\n      \"channel\": \"onsite\"\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.topsort.com/v2/events")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"renders\": [\n    {\n      \"id\": \"3f2b9c14-7a1d-4e2b-9c3a-1b2c3d4e5f60\",\n      \"occurredAt\": \"2019-01-01T12:59:58-05:00\",\n      \"opaqueUserId\": \"71303ce0-de89-496d-8270-6434589615e8\",\n      \"resolvedBidId\": \"WyJiX01mazE1IiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0=\",\n      \"placement\": {\n        \"path\": \"/categories/dairy\",\n        \"position\": 1,\n        \"page\": 1,\n        \"pageSize\": 15,\n        \"categoryIds\": [\n          \"9BLIe\"\n        ]\n      },\n      \"deviceType\": \"mobile\",\n      \"channel\": \"onsite\"\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "errCode": "bad_request",
  "docUrl": "https://api.docs.topsort.com/reference/errors",
  "message": "could not find the provided resolved bid id"
}

Events

Report events

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

Renders — an ad was rendered in the page.
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.
Video events — a video ad reached a playback checkpoint or failed to play.

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 '
{
  "renders": [
    {
      "id": "3f2b9c14-7a1d-4e2b-9c3a-1b2c3d4e5f60",
      "occurredAt": "2019-01-01T12:59:58-05:00",
      "opaqueUserId": "71303ce0-de89-496d-8270-6434589615e8",
      "resolvedBidId": "WyJiX01mazE1IiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0=",
      "placement": {
        "path": "/categories/dairy",
        "position": 1,
        "page": 1,
        "pageSize": 15,
        "categoryIds": [
          "9BLIe"
        ]
      },
      "deviceType": "mobile",
      "channel": "onsite"
    }
  ]
}
'

import requests

url = "https://api.topsort.com/v2/events"

payload = { "renders": [
        {
            "id": "3f2b9c14-7a1d-4e2b-9c3a-1b2c3d4e5f60",
            "occurredAt": "2019-01-01T12:59:58-05:00",
            "opaqueUserId": "71303ce0-de89-496d-8270-6434589615e8",
            "resolvedBidId": "WyJiX01mazE1IiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0=",
            "placement": {
                "path": "/categories/dairy",
                "position": 1,
                "page": 1,
                "pageSize": 15,
                "categoryIds": ["9BLIe"]
            },
            "deviceType": "mobile",
            "channel": "onsite"
        }
    ] }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    renders: [
      {
        id: '3f2b9c14-7a1d-4e2b-9c3a-1b2c3d4e5f60',
        occurredAt: '2019-01-01T12:59:58-05:00',
        opaqueUserId: '71303ce0-de89-496d-8270-6434589615e8',
        resolvedBidId: 'WyJiX01mazE1IiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0=',
        placement: {
          path: '/categories/dairy',
          position: 1,
          page: 1,
          pageSize: 15,
          categoryIds: ['9BLIe']
        },
        deviceType: 'mobile',
        channel: 'onsite'
      }
    ]
  })
};

fetch('https://api.topsort.com/v2/events', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.topsort.com/v2/events",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'renders' => [
        [
                'id' => '3f2b9c14-7a1d-4e2b-9c3a-1b2c3d4e5f60',
                'occurredAt' => '2019-01-01T12:59:58-05:00',
                'opaqueUserId' => '71303ce0-de89-496d-8270-6434589615e8',
                'resolvedBidId' => 'WyJiX01mazE1IiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0=',
                'placement' => [
                                'path' => '/categories/dairy',
                                'position' => 1,
                                'page' => 1,
                                'pageSize' => 15,
                                'categoryIds' => [
                                                                '9BLIe'
                                ]
                ],
                'deviceType' => 'mobile',
                'channel' => 'onsite'
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.topsort.com/v2/events"

	payload := strings.NewReader("{\n  \"renders\": [\n    {\n      \"id\": \"3f2b9c14-7a1d-4e2b-9c3a-1b2c3d4e5f60\",\n      \"occurredAt\": \"2019-01-01T12:59:58-05:00\",\n      \"opaqueUserId\": \"71303ce0-de89-496d-8270-6434589615e8\",\n      \"resolvedBidId\": \"WyJiX01mazE1IiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0=\",\n      \"placement\": {\n        \"path\": \"/categories/dairy\",\n        \"position\": 1,\n        \"page\": 1,\n        \"pageSize\": 15,\n        \"categoryIds\": [\n          \"9BLIe\"\n        ]\n      },\n      \"deviceType\": \"mobile\",\n      \"channel\": \"onsite\"\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.topsort.com/v2/events")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"renders\": [\n    {\n      \"id\": \"3f2b9c14-7a1d-4e2b-9c3a-1b2c3d4e5f60\",\n      \"occurredAt\": \"2019-01-01T12:59:58-05:00\",\n      \"opaqueUserId\": \"71303ce0-de89-496d-8270-6434589615e8\",\n      \"resolvedBidId\": \"WyJiX01mazE1IiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0=\",\n      \"placement\": {\n        \"path\": \"/categories/dairy\",\n        \"position\": 1,\n        \"page\": 1,\n        \"pageSize\": 15,\n        \"categoryIds\": [\n          \"9BLIe\"\n        ]\n      },\n      \"deviceType\": \"mobile\",\n      \"channel\": \"onsite\"\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.topsort.com/v2/events")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"renders\": [\n    {\n      \"id\": \"3f2b9c14-7a1d-4e2b-9c3a-1b2c3d4e5f60\",\n      \"occurredAt\": \"2019-01-01T12:59:58-05:00\",\n      \"opaqueUserId\": \"71303ce0-de89-496d-8270-6434589615e8\",\n      \"resolvedBidId\": \"WyJiX01mazE1IiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0=\",\n      \"placement\": {\n        \"path\": \"/categories/dairy\",\n        \"position\": 1,\n        \"page\": 1,\n        \"pageSize\": 15,\n        \"categoryIds\": [\n          \"9BLIe\"\n        ]\n      },\n      \"deviceType\": \"mobile\",\n      \"channel\": \"onsite\"\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "errCode": "bad_request",
  "docUrl": "https://api.docs.topsort.com/reference/errors",
  "message": "could not find the provided resolved bid id"
}

Authorizations

Authorization

string

header

required

A valid API key generated in Topsort's UI. Use a TSE API key for calls to Auctions or Events API.

Body

application/json

Event data including renders, impressions, clicks, purchases, page views, and video events.

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

renders

Render · object[]

An array of render events

Maximum array length: 50

Show child attributes

impressions

Impression · object[]

An array of impression events

Maximum array length: 50

Show child attributes

clicks

Click · object[]

An array of click events

Maximum array length: 50

Show child attributes

purchases

Purchase · object[]

An array of purchase events

Maximum array length: 50

Show child attributes

pageviews

Page View · object[]

An array of page views

Maximum array length: 50

Show child attributes

videoEvents

Video event · object[]

An array of video events

Maximum array length: 50

Show child attributes

Response

All events were reported successfully.

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

Placement API

Export API

API Reference

Report events

Authorizations

Body

Response