With Topsort API V2, Sponsored Listings have more flexibility and can batch multiple auctions of different types in one request. Check out our API v2 reference for more information on variables, responses, and requests.

Changes from V1

These are the main differences from API v1:

  • Session information is no longer required.
  • You can run up to 5 different auctions of 2 different types in one request.
  • The 2 different types of auctions you can run in one request are banner ads and sponsored listings.
  • When 1 auction fails, the response will indicate which auction failed. One failed auction does not prevent the other auctions from successfully displaying winners. Winners for other auctions will be returned regardless of the failed auction(s).

The required variables here are type, slots , and productId.

NameTypeDescriptionRequired/Optional
typestringSpecifies type of auction: listing or bannerRequired
slotsintegerSpecifies the maximum number of auction winners that should be returnedRequired
productIdarray of stringsAn array of strings, each describing a product ID that should participate in the auction. (Can include up to 10,000 items)Required

Request

This is an example of a request made using the API V2 in JSON format.

{
  "auctions": [
    {
      "type": "listings",
      "slots": 2,
      "products": {
        "ids": [
          "p_PJbnN",
          "p_ojng4",
          "p_8VKDt",
          "p_Mfk15"
        ]
      },
      "geoTargeting": {
        "location": "New York"
      }
    },
    {
      "type": "banners",
      "slots": 1,
      "aspectRatio": "4:1",
      "category": {
        "id": "c_yogurt"
      }
    }
  ]
}

Response

Your response will include as many auction results as you created auction items for (5 being the greatest amount). In the array, winning products are ordered from highest to lowest bid. It will be empty if there were no qualifying bids or if there was an error.

There is a new boolean variable, error, that indicates whether the auction was resolved successfully.

This is an example of the response using the API V2 in JSON format.

{
  "results": [
    {
      "winners": [
        {
          "rank": 1,
          "winnerType": "product",
          "winnerId": "p_Mfk15",
          "resolvedBidId": "WyJiX01mazE1IiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0="
        },
        {
          "rank": 2,
          "winnerType": "product",
          "winnerId": "p_PJbnN",
          "resolvedBidId": "WyJlX1BKYm5OIiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwibGlzdGluZ3MiLCJkZWZhdWx0IiwiIl0="
        }
      ],
      "error": false
    },
    {
      "winners": [
        {
          "rank": 1,
          "winnerType": "product",
          "winnerId": "p_PJbnN",
          "resolvedBidId": "WyJlX1BKYm5OIiwiMTJhNTU4MjgtOGVhZC00Mjk5LTgzMjctY2ViYjAwMmEwZmE4IiwiYmFubmVyQWRzIiwiZGVmYXVsdCIsIiJd",
          "asset": [
            {
              "url": "https://topsort.cdnprovider.com/lhs-banner-image-for-p_PJbnN-1x.png"
            }
          ]
        }
      ],
      "error": false
    }
  ]
}