Skip to content
Topsort Documentation
API

Create sponsored brand auctions

POST
/auctions/sponsored-brand

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 batched auction request, for which products’ bids will compete against each other.

application/json
object
auctions
required
Array<object>
>= 1 items <= 5 items

Describes the intent of running a sponsored brand auction.

Exactly one of the following fields must be set:

  • products
  • category
object
winners
required

Specifies the maximum number of auction winners that should be returned.

integer format: int32
>= 1
category

A category for the purpose of running an auction.

object
id
required

The category ID of the bids that will participate in an auction.

string
>= 1 characters
products
object
ids
required

An array of product IDs that should participate in the auction.

Array<string>
>= 1 items <= 10000 items
qualityScores

An array of marketplace defined quality scores, each corresponding to the product ID with matching array index. If given, these values will be combined with our internal quality scores to provide a score that better represents the relevance of the participating products. Note that the length of this array must be the same as the length of the ids array and that the values must be between 0 and 1.

Array<number>
>= 1 items <= 10000 items

Responses

The auction results. The list of winners will contain at most winners entries per auction. It may contain fewer or no entries at all if there aren’t enough products with usable bids, that is, a bid amount greater than the reserve price and belonging to a campaign with enough remaining budget. Bids become unusable if campaign budget is exhausted, the bid is disqualified to preserve spend pacing, etc.

application/json
object
results
required
Array<object>
>= 1 items <= 5 items
object
winners
required

Array of winner objects in order from highest to lowest bid. It will be empty if there were no qualifying bids or if there was an error.

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 format: int32
>= 1
productId
required

The marketplace’s ID of the winning entity, depending on the target of the campaign.

string
resolvedBidId
required

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

string
title

An optional title for the sponsored brand selected when creating the campaign.

string
assets
required

Assets used to render the sponsored brand ad.

Array<object>
>= 1 items
object
url

A vendor provided asset that the marketplace has to render. The asset will be served by Topsort’s CDN.

string format: uri
role

The role of the asset. It can be either logo or image.

string
contentType

The asset MIME type.

string
contentLength

The size of the asset in bytes.

integer format: uint32
width

The asset width in pixels.

integer format: uint32
height

The asset height in pixels.

integer format: uint32
error
required

A boolean indicating whether this auction was resolved successfully.

boolean