Share via

Notify request

  • Article

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

Notify Request - FAQ