Skip to content
Topsort Documentation
API

Creates a new auction

POST
/auctions

Authentication

Topsort’s APIs are authenticated via bearer tokens. Requests must include an authorization header containing your private API key.

Don't have an API key yet? Learn how to generate one.

Authorization
required
string

The header containing a private API key. Format this header as follows:

Authorization: Bearer <YOUR-API-KEY>

Request Body

The information describing what will be auctioned. Topsort will run an auction for each slot type, for which products’ bids will compete against each other. The products that will participate are included in the request.

application/json
object
slots
required

The Slots object specifies how many auctions winners should be returned for each promotion type. The promotion types depend on the marketplace configuration. For sponsored listings, use the “listings” key.

object
>= 1 properties
listings
integer
>= 1
products
required

An array of objects, each describing a product that should participate in the auction.

Array<object>
>= 1 items
object
productId
required
string format: string
>= 1 characters
quality
number format: double
<= 1
session

The Session object allows correlating user activity during a session whether or not they are actually logged in.

object
sessionId
required

Long-lived token identifying the customer interacting with the marketplace. If your users are always logged in you may use a hash of your customer ID. If your users may interact with your app or site while logged out we recommend generating a random identifier (UUIDv4) on first load and store it on local storage (cookie, local storage, etc) and let it live for at least a year.

string
>= 1 characters
geoTargeting

An object describing geographical information associated with this auction.

object
location
required

The location this auction is being run for.

string
>= 1 characters

Responses

The auction results. The list of Winner objects will contain at most slots entries. It may contain fewer or no entries at all if there aren’t enough products with usable bids. Bids become unusable if their campaign budget is exhausted, the bid is disqualified to preserve spend pacing, etc.

application/json
object
slots
object
listings
object
auctionId

Topsort assigned ID for the auction. Should be used in reporting impressions, clicks and purchases.

string
winners

Array of winner objects in order from highest to lowest bid. May be empty if there were no qualifying bids.

Array<object>
object
rank
required

Where the product’s bid ranked in the auction. One-based, so the product with rank 1 won the auction. In an auction response, the winners array is sorted so rank will match the entry’s index.

integer
>= 1
productId
required

The marketplace’s ID for the product. It will match the ID for a product in the request’s products array.

string
winnerType

The type of the winning bid, depending on the campaign. It can be product or vendor.

string
Allowed values: product vendor
winnerId

The marketplace’s ID of the winnning item, depending on the campaign.

string
resolvedBidId

An opaque topsort ID to be used when this item is interacted with.

string