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.

Internal 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.

External auction

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.

Specs

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.

Tags

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.

Responses

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.

Lost notifies

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.

Error list

For a list of all possible errors that could be sent in a Notify Request, see Bid Error Codes.

Notify full auction

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.

Examples

Single tag request - Auction won

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
         }
      ]
   }
}

Single tag request - Auction lost

{
    "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
    }
}

Single tag request - Error in response

{
    "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
    }
}

Related topic

Notify Request - FAQ