Notify request
Bidders receive notifications regarding auction results, bid response time, and any errors generated by a particular bidder's bid response (i.e. 'JSON parsing error'). These notifications will be sent via a server side call to a bidder-specified notify_URI
when the auction has completed and the impression is served. You can manage the amount of information you receive in your notifications using the notify_full_auction
field in the Bidder Service. Notifications include details about each submitted bid.
Note
In certain auction types, a lost or pending notification may be generated prior to the win notification. Win notifications are always authoritative and override any other notifications previously received for that auction.
For all auctions we conduct, bidders will receive notifications when an auction is won and when an error occurs. Bidders can also opt into receiving notifications when an auction is lost by submitting a support request.
For all auctions conducted by a third-party, bidders will receive a pending notification when their bid is passed along to the third-party, and a notification when an auction is won.
Field | Scope | Type | Description |
---|---|---|---|
timestamp |
all | timestamp | Time the request was sent. |
user_id_64 |
some | int | The ID of the user. On "lost" and "no-bid" requests, no user ID will be specified. |
fail |
some | boolean | Returns true when the bid response could not be processed (e.g. invalid JSON passed in the bid response). |
error |
some | string | When fail is true, this field displays the corresponding error message. See Error List below. |
error_id |
some | int | More details on the number provided can be found here. |
response_time_ms |
some | int | When provided, this is the number of milliseconds for the the bid_response to return. This parameter will be excluded if no response is returned. |
Field | Scope | Type | Description |
---|---|---|---|
id |
some | int | ID of the tag. |
auction_id_64 |
all | int | The ID of the auction. This is useful for reconciliation and discrepancies, so we recommend that you add to your logs. |
notify_type |
all | enum | Possible values are kept , sold , won , lost , default , or pending .Note: kept and sold only apply if you are the owner of the inventory. |
post_pending |
all | boolean | Set to true if member has won the final auction for a third party inventory. |
member_id |
some | int | The ID of the member included in the bid response. On "lost" and "no-bid" requests, no member ID will be specified. |
creative_id |
some | int | The ID of the creative included in the bid response. On "lost" and "no-bid" requests, no creative ID will be specified. |
price_paid |
type = won | double | The actual price paid (CPM) by the winner. This is only available if you won the impression. |
price_sold_for |
type = sold | double | The revenue received by the owner of the impression when sold. For sellers only. |
custom_notify_data |
some | string | If you won the impression for this tag, the custom notify data that you submitted for the winning bid will pass through at the tag level in the notification. |
payment_rule_id |
some | int | The ID of the payment rule the tag has assigned to it. |
Field | Scope | Type | Description |
---|---|---|---|
result |
all | string | This flag (ok or error ) reports the receipt of a valid bid response to your bidder. If it is error , you will receive a relevant error message. |
price_bid |
some | double | The price bid in the bid response. |
error_id |
some | int | When result is error , this field displays the error code. For more information, see Notify Request Error Codes. |
error |
some | string | When result is error , this field displays the corresponding error message. For more information, see Notify Request Error Codes. |
custom_notify_data |
some | string | When provided, this is any data that the bidder has specified in the response to be passed through to the notification. |
Note
The responses array will not be present when post-pending
is true
.
We can send you notify requests when you send a nonzero bid response for an auction, and don't win the auction. This can occur either because you were outbid, or because your bid was rejected. Bids can be rejected for either technical reasons such as a badly formed JSON message or for business-level reasons such as using a creative that is blocked by the seller, or sending a bid price which is below the floor for a deal. If you are having trouble getting delivery on a given creative, lost notify messages are a great way to see why your creative is not winning more impressions. To turn on lost notify messages, please submit a support request and a representative can enable this for your bidder.
For a list of all possible errors that could be sent in a Notify Request, see Bid Error Codes.
If the Bidder Service parameter notify_full_auction
is set to true
, full_tag_info
, and bid_info
will be included in the response. The parameter full_tag_info
contains all information described in the Tags section of the Bid Request page, except the exclusive_default
field, while bid_info
contains all information in the Bid_info and Segments sections of the Bid Request page.
Note
For post-pending notifies (post-pending
is set to true
), full_tag_info
is not available because the bid acceptance callback has not yet been received.
Note
This is only available when using the platform bid protocol. OpenRTB wins will be sent using the NURL field in the bid response.
{ "notify_request":{
"timestamp":"2011-02-09 00:11:44",
"response_time_ms":4,
"tags":[
{
"id":474074,
"auction_id_64":7606327141949238687,
"payment_rule_id":65930,
"price_paid":0.90000,
"member_id":670,
"notify_type":"won",
"creative_id":12345,
"user_id_64":4628364836293826
}
],
"responses":[
{
"result":"ok",
"price_bid":1.00000
}
]
}
}
{
"notify_request": {
"user_id_64": 2843838668060323000,
"responses": [
{
"price_bid": 0.06207,
"result": "ok"
}
],
"tags": [
{
"notify_type": "lost",
"id": 9373851,
"payment_rule_id": 874041,
"auction_id_64": 1177991420539445500
}
],
"timestamp": "2016-09-27 21:49:06",
"auction_timestamp": "2016-09-27 21:49:06",
"response_time_ms": 67
}
}
{
"notify_request": {
"user_id_64": 9191106446964517565,
"responses": [
{
"error_id": 408,
"result": "error",
"error": "Creative 536754694 brand 75445 banned on member's ad profile 542799"
}
],
"tags": [
{
"notify_type": "lost",
"id": 5632681,
"payment_rule_id": 821648,
"auction_id_64": 442903072350998711
}
],
"timestamp": "2016-09-27 21:48:46",
"auction_timestamp": "2016-09-27 21:48:46",
"response_time_ms": 87
}
}