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

// Note: use an advanced api key (begins with TSC). Keep this secret!
const apikey = "TSC_xklAIE15WOnl12as11f467bk47asxn4LPazb";

const body = {
  "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(body),
  })

  if (!response.ok) {
    console.error("unexpected status: " + response.status);
  } else {
    console.log("success status: " + response.status);
  }
} catch (error) {
  console.error(error);
}

Run code Executing...

output

// Note: use an advanced api key (begins with TSC). Keep this secret!
const apikey = "TSC_xklAIE15WOnl12as11f467bk47asxn4LPazb";

const body = {
  "bids": [
    {
      "target": {
        "type": "product",
        "id": "example-product-coca-cola"
      },
      "triggers": [
        {
          "type": "keyword",
          "value": {
            "matchType": "exact",
            "words": [
              "soft drink"
            ]
          }
        }
      ]
    }
  ],
  "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?vendor_id=demo-vendor", {
    method: "POST",
    mode: "cors",
    headers: {
      Authorization: `Bearer ${apikey}`,
      "Content-Type": "application/json; charset=utf-8",
    },
    body: JSON.stringify(body),
  })

  if (!response.ok) {
    console.error("unexpected status: " + response.status);
  } else {
    console.log("success status: " + response.status);
  }
} catch (error) {
  console.error(error);
}

Run code Executing...

output

// Note: use a marketplace key (begins with TSE)
const apikey = "TSE_galAS785djk1n14cIO4923A758axnUJ127Ja";

const body = {
  "auctions": [
    {
      "searchQuery": "soft drink",
      "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(body),
  })

  if (!response.ok) {
    console.error("unexpected status: " + response.status);
  } else {
    console.log("success status: " + response.status);
  }
} catch (error) {
  console.error(error);
}

Run code Executing...

output

// Note: use a marketplace key (begins with TSE)
const apikey = "TSE_galAS785djk1n14cIO4923A758axnUJ127Ja";

const body = {
  "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(body),
  })

  if (!response.ok) {
    console.error("unexpected status: " + response.status);
  } else {
    console.log("success status: " + 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