Skip to end of metadata
Go to start of metadata

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.

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.

On This Page

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

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

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.

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.

Example Notify Requests

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.
Single Tag Request - Auction Lost
Single Tag Request - Error in Response
Multi Tag Request - Pending update

Related Topics