Developer documentation

Two integration paths - Mix and match as necessary.

Low Code

Deals with common use cases and gets you started quickly.

• Import catalog with feeds
• Embed banners with banners.js
• Enrich search results with the proxy

API Driven

For bespoke functionality and advanced use cases.

• Authentication
• API Reference

Try it out

1

Upload a product

2

Create your first campaign

3

Run an auction

4

Track events

const apikey = "TSC_mykey";
const catalog = {
  products: [
    {
      active: true,
      categories: ["soft-drinks"],
      id: "example-product-coca-cola",
      imageURL:
      "https://intl.cokestore.com/media/catalog/product/1/6/16181_squeeze-ko-can-maria-2.png",
      name: "Coca Cola can",
      price: "9.99",
      vendors: ["coca-cola"],
    },
  ],
};

try {
  const response = await fetch("https://api.topsort.com/public/v1/catalog-search-service/catalogs/products", {
    method: "PUT",
    mode: "cors",
    headers: {
      Authorization: `Bearer ${apikey}`,
      "Content-Type": "application/json; charset=utf-8",
    },
    body: JSON.stringify(catalog),
  })

  if (!response.ok) return { stderr: response.status };
  return { stdout: response.status };
} catch (error) {
  console.error(error);
}

Run code Executing...

output

const apikey = "TSE_mykey";
const campaign = {
  bids: [
    {
      target: { type: "product", id: "example-product-coca-cola" },
      "trigger": { type: "product", value: { matchType: "exact" } },
      amount: 1000
    }
  ],
  "budget": { type: "daily", amount: 10000 },
  campaignType: "autobidding",
  isActive: true,
  status: "approved",
  adFormat: "listing",
  name: "An example campaign"
};

try {
  const response = await fetch("https://api.topsort.com/public/v1/campaign-service/campaigns", {
    method: "POST",
    mode: "cors",
    headers: {
      Authorization: `Bearer ${apikey}`,
      "Content-Type": "application/json; charset=utf-8",
    },
    body: JSON.stringify(campaign),
    }
  )

  if (!response.ok) return { stderr: response.status };
  return { stdout: response.status };
} catch (error) {
  console.error(error);
}

Run code Executing...

output

const apikey = "TSE_mykey";
const auction = {
  "auctions": [
    {
      "products": { "ids": [ "example-product-coca-cola" ] },
      "slots": 1,
      "type": "listings"
    }
  ]
};

try {
  const response = await fetch("https://api.topsort.com/v2/auctions", {
    method: "POST",
    mode: "cors",
    headers: {
      Authorization: `Bearer ${apikey}`,
      "Content-Type": "application/json; charset=utf-8",
    },
    body: JSON.stringify(auction),
  })

  if (!response.ok) return { stderr: response.status };
  return await response.json();
} catch (error) {
  console.error(error);
}

Run code Executing...

output

const apikey = "TSE_mykey";
const events = {
  "clicks": [
    {
      "id": "d0cf3f56-a719-4e02-9c88-625f965ae6e7",
      "occurredAt": "2024-07-23T11:49:04+00:00",
      "opaqueUserId": "71303ce0-de89-496d-8270-6434589615e2",
      "resolvedBidId": "ChAGafmNzX5wy4sEaDnXi4iWEhABjxq1RG513IkbvRgIVcd6GhABjmiyW3t2Ur066CLC3jWVIgoKBjExMjYzNBABMPuVDw"
    }
  ]
};

try {
  const response = await fetch("https://api.topsort.com/v2/events", {
    method: "POST",
    mode: "cors",
    headers: {
      Authorization: `Bearer ${apikey}`,
      "Content-Type": "application/json; charset=utf-8",
    },
    body: JSON.stringify(events),
  })

  if (!response.ok) return { stderr: response.status };
  return { stdout: response.status };
} catch (error) {
  console.error(error);
}

Run code Executing...

output

Client libraries

We provide client libraries to help you get started quickly:

Topsort.js

Analytics.js

Topsort.kt

PHP

Banners.js

Topsort.swift

Learn more

Not sure where to begin? Learn about the fundamental components:

The Catalog

Banners

Campaigns

Auctions

Events