Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.topsort.com/llms.txt

Use this file to discover all available pages before exploring further.

The auctions API enables you to create a wide variety of auctions. Whether you want to include sponsored listings in search results or banners on your homepage, we’ve got you covered.

​
Before you begin

Before you’re ready to use the auctions API, you need to:
  1. Obtain an API key to authenticate.
  2. Create several campaigns, to have bids available for the auctions.
Ensure your campaigns have sufficient budget! The most common reason for empty auction results is budget exhaustion. Campaigns with zero remaining budget cannot participate in auctions, leading to no winners. Check your campaign budgets before testing auctions.

​
Request

The /auctions endpoint allows you to run up to 5 auctions in one request. The full spec for this endpoint is found here. This can be quite a lot to take in at once, so let’s stick to the basics now. Every request body should be provided as JSON and is generally structured as follows. 
{
  "auctions": [
    {
      "type": "listings",
      "slots": 2
    },
    {
      "type": "banners",
      "slots": 1
    }
  ]
}
There are several interesting things about this (incomplete) snippet:
  • Auctions are provided as an array to the auctions field. You can provide 1 to 5 auctions in a single request.
  • Each auction has a type that will determine whether it’s auctioning listings or banners.
  • Each auction has a slots field, this determines the maximum number of winners of the auction.
To complete the above snippet you will need to add more fields, check out the sponsored listings example or sponsored banners example for more information.

​
Response

Do not cache this response or it’s results. Auctions need to be unique per page view, this is what makes the system work.If the auction results are cached, the same results could be shown to multiple users or to the same user multiple times.
If there are no request errors, the auctions endpoint will return the results for each auction. A successful response does not mean that each auction succeeded or has winners. You will need to check the results to determine this.

​
Response with winners

Suppose that both auctions in the earlier request result in winners, the response could look something like this: 
{
  "results": [
    {
      "winners": [
        {
          "rank": "1",
          "resolvedBidId": "WyJiX01mazE1IiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0="
        },
        {
          "rank": "2",
          "resolvedBidId": "WyJlX1hKYm5OIiwiMTNiNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0=="
        }
      ],
      "error": false
    },
    {
      "winners": [
        {
          "rank": "1",
          "resolvedBidId": "WyJzb21lLXNsb3QiLCIxM2I1NTgyOC04ZWFkLTQyOTktODMyNy1jZWJiMDAyYTBmYTgiLCJiYW5uZXJzIiwiZGVmYXVsdCIsIiJd=="
        }
      ],
      "error": false
    }
  ]
}
Things to note about this response:
  • Auction results are under a top level results property.
  • The order of the results corresponds to the order of the auctions.
  • Each result has an array of winners. This array can be empty and it will never be more than the slots of the auction.
  • It’s possible for auctions to fail/succeed independently. The error flag indicates whether an auction succeeded.

​
Empty Winners Array

If winners is empty ([]), common causes include:
  • Budget exhausted: Campaigns have spent their daily/total budget
  • No active campaigns: No campaigns are targeting the auction context
  • Bid too low: Campaign bids are below auction floor prices
  • Product mismatch: Campaign products don’t match auction criteria
The exact fields on the winners depend on the type of the auction, but they will always have:
  • rank a 1-based number corresponding to its position in winners.
  • resolvedBidId identifying the bid that made this winner win. This ID is used to relate the bid to events.

​
Response without winners

It’s not guaranteed that an auction will result in winners. If there are no active campaigns that match it’s criteria, there won’t be any bids to place. If our earlier auction request did not have any winners for either auction, it’s response will look something like this: 
{
  "results": [
    {
      "winners": [],
      "error": false
    },
    {
      "winners": [],
      "error": false
    }
  ]
}
Note that this response still contains results for both auctions.

​
Further reading

Check out the other pages in this section to see complete examples for different use cases.