Running auctions
Learn how to use the auctions API to create auctions for listings and banners.
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:
- Obtain an API key to authenticate.
- Create several campaigns, to have bids available for the 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.
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 inwinners
.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.