Marketplace Auction Notifications
- Overview
- Benefits
- Prerequisites
- Auction Notification Response Structure
- Reason Codes
- Example Responses
- FAQ
Overview
Many DSP partners, in particular those who started as desktop-focused, receive auction notifications or lost-bid notifications from the exchanges they are integrated with. These notifications are helpful for the following purposes:
- Rapidly identifying and resolving technical issues.
- Identifying trends in bidding behavior.
- Understanding the outcome of an auction on pre-Cached ad formats.
Benefits
This service provides DSPs with a powerful tool to help close a key information gap with how our current RTB auctions operate. Key benefits include:
- Full visibility into auction outcome at time of serving, including notification of whether the DSP wins or loses against the network proxy.
- Complete transparency on auction fails (e.g., technical, blocks, etc).
- Option to receive only loss transparency and not wins.
Prerequisites
In order to use the service, DSPs must:
- Have either an RTB 2.3 or an RTB 2.5 enabled bidder.
- Provide an HTTP OR HTTPS endpoint to receive auction notify responses.
Note: Your account team can enable you to receive auction notifications permanently or periodically for debugging purposes.
Auction Notification Response Structure
The auction notification response is structured like a typical bid response. For more information on individual fields from the bid response structure, refer to the 2.3 spec or 2.5 spec respectively.
The fields in bold denote those specific to auction notifications.
bidid |
Bid response ID to assist tracking for bidders. This value is chosen by the bidder for cross-reference. Optional for bidder and only shown if bidder passes in response. | |||
id |
Top-level ID of the bid request that this is a response for. | |||
http_status |
HTTP status code from the bid response. | |||
bidfloor |
Not typically passed by a bidder in the bid response; added here for troubleshooting. | |||
latency |
Latency of the bid response in seconds (e.g., .139 = 139ms). | |||
seatbid [] |
An array of all seats for this bidder endpoint. There must be at least one seat present. | |||
seat |
A unique identifier for this seat. This should be logged and will primarily be used for billing purposes. Optional for bidder to support. Required if using multiple seats. | |||
bid [] |
Enables consideration for all elements in the array, rather than just the first. The highest bid that is not excluded by blocklist violations and other validity checks will be submitted as the winning bid from this seat. | |||
id |
Used only to identify which among many bids in a seatbid was chosen. ID chosen by the bidder. | |||
adid |
ID that references the ad to be served if the bid wins. Logged if passed. | |||
impid |
Matches the impression object that was sent in the bid request to which this bid corresponds. This must match the value in imp.id from the bid request. |
|||
price |
The bid price, in CPM units. If the bid price is higher than $1000, the bid will not be considered for the auction. This is to protect bids from clearing at higher than market price CPMs. | |||
reason |
Note that the reason object can be located at different levels of heirarchy. |
|||
description |
String describing the reason for the notification. | |||
value |
Optional field if there is additional detail on the reason. | |||
id |
Reason ID from reason code mapping table. |
Reason Codes
Reason codes will be sent with the auction notify response and will be present at different levels of the bid response hierarchy, based on the specific reason. See the following table for details.
Reason Code Mapping Table
ID | Description | Value | Reason | Location |
---|---|---|---|---|
0 | win | Bid is the highest demand source for this impression. | bid object | |
1 | outbid | bidder, network, line item | bid object | |
2 | below price floor | bid object | ||
3 | invalid file extension | Filtered due to inclusion of swf or flv in markup. |
bid object | |
4 | missing values | Include missing value if applicable | can be a root, bid, or seatbid | |
5 | blocked adomain | Return adomain | Violates adomain blocks. |
bid object |
6 | blocked creative | Creative ID is blocked due to violation or low TDR, or blocked by publisher. | bid object | |
7 | unparseable | For example: not valid JSON. | root | |
8 | timeout | root | ||
9 | non http ok | 503 on bid request (or some other error such as 400, 500). We expect responses to be either HTTP 200 or 204. Any other response will not be processed. | root | |
10 | wrong format | Bid response is not video on a video only request, or bid response is not recognized as native on a native request. | bid object | |
11 | blocked seat | Buyer seat ID is blocked. | seatbid object | |
12 | invalid pmp deal ID | Bid response does not contain the correct PMP deal ID. | bid object | |
13 | invalid pmp domain | Bid response does not contain a publisher allowlisted adomain. | bid object | |
14 | invalid asset | Only sent for the native ad format. Assets used in bid response do not conform to OpenRTB specs. | bid object | |
15 | blocked category | Violates category blocks. | bid object | |
16 | auction id mismatch | Bid response contains auction ID that does not match the auction ID found in bid request. | bid object | |
17 | unexpected whitespace | Bid response contains unexpected whitespace (extra whitespace where it should not be). | bid object | |
20 | blocked creative attribute | Violates creative blocks. | bid object | |
21 | invalid audience segment deal id | Bid response contains an audience segment deal ID that is not valid. | bid object | |
22 | insecure creative url | Bid response contains a creative URL that is not secure. | bid object | |
23 | blocked app | Bid response contains a blocked bundle. | bid object |
Example Responses
Server Error - 503 Response Code
{
"latency": 0.137,
"reason": {
"description": "non_http_ok",
"id": 9
},
"bidfloor": 0.1,
"http_status": 503,
"id": "d42cca99e0584c21a33380d0f3efa3ce"
}
Marketplace Loss with Multiple Bids/Reasons
{
"latency": 0.139,
"seatbid": [{
"bid": [{
"reason": {
"description": "outbid",
"value": "bidder",
"id": 1
},
"impid": "1",
"price": 0.25,
"adid": "3141592",
"id": "bid1_2"
}],
"seat": "seat1"
},
{
"bid": [{
"reason": {
"description": "below_floor",
"id": 2
},
"impid": "1",
"price": 0.04,
"adid": "3141592",
"id": "bid2_1"
}],
"seat": "seat2"
}
],
"bidfloor": 0.1,
"http_status": 200,
"bidid": "bidid2",
"id": "2fa74f29641e44db88931ea86c87ced6"
}
Network Loss (Outbid by Ad Network)
{
"latency": 0.139,
"seatbid": [{
"bid": [{
"reason": {
"description": "outbid",
"value": "network",
"id": 1
},
"impid": "1",
"price": 0.51,
"adid": "3141592",
"id": "bid1_1"
}],
"seat": "seat1"
}],
"bidfloor": 0.1,
"http_status": 200,
"bidid": "bidid2",
"id": "2fa74f29641e44db88931ea86c87ced6"
}
FAQ
Why do we have an option for wins with this service?
Our imptracker
notification occurs at the time of charging a DSP for impressions served. This win notification will notify if the bid is the highest paying demand source for this impression at the time of the auction completion; that is, if the DSP has the highest bid price of all DSPs, and also if they beat the network proxies.
Does a “win” account for networks?
Yes, “wins” with this service mean the DSP’s bid represents the highest-priced demand source for this impression, and it will be sent to the user’s device.
I noticed some auction_ids are appearing for both losses and wins. Why is that?
You may see some loss notifications that end up becoming win notifications at a later point. The reason for this is due to publishers having their Marketplace line item compete with a network. For example, you may lose to a network and if (for a variety of reasons) that network cannot fulfill the impression request, you may then win and be able to serve your impression.
Please keep in mind that you may see multiple loss notifications with the same ID. The reason would be due to Publisher waterfall setups. Taking the previous example into consideration, there are possibilities where you lose to a network, that network cannot fulfill, you lose to a second network, so on and so forth.
Should I still use the impression tracker (1imptrackers1) if I integrate this service?
Yes, the impression tracker is the MoPub billing notification for an impression event. A “win” here represents a server-side win, meaning that your bid represented the highest paying demand source for this impression, but it doesn’t guarantee that it is shown to the user for a revenue event.
Note: MoPub uses client-side impression tracking (imptrackers) per IAB and MRC best practice for mobile impression counting.
How does this work if the bidder returns multiple seatbid or bid objects in their bid response?
All lost bids are grouped into a single auction notification response; each bid will have its own reason. If one bid is the winner from the auction, that individual bid will be sent in a separate auction notification and this bidder will receive a maximum of two notifications.
Why can the “reason” object be located at different levels of the response hierarchy?
It is dependent on where the error occurs see the reason code table for details.
What is the maximum QPS you will send through with auction notifies?
It is dependent on the rate of bids submitted. It will max out at 2x the rate of bids you submit (if you always submit multiple bids in a bid response), otherwise, the max QPS is equal to the rate of bids your bidder submits.
When will you send an auction notification? Will it be for every auction request I receive?
We only send auction notifications if there is a bid. I.e., all “NoBid” situations will be left out. Examples of NoBid situations are 204 response, or a 200 empty response. Sending back a 200 response with a $0 bid will trigger a notification.
How do you send auction notifies to our endpoint?
- HTTP method:
POST
- HTTP
content-type
:application/json
Additional Questions
For more information or questions, please email your Account Management team or visit our Support Center.
Please contact your account team for information or graphs on the rate of bids for your bidder to help guide this decision.
Last updated March 30, 2021
TWITTER, MOPUB, and the Bird logo are trademarks of Twitter, Inc. or its affiliates. All third party logos and trademarks included are the property of their respective owners.
© 2021 MoPub (a division of Twitter, Inc.)