Skip to main content

Open RTB Bid Response Specifications

The response for a bid request should have the following structure:

response​

AttributeRequired?Description
idYesID of the bid request to which this is a response (string)
seatbidYesCollection of bids made by the bidder on behalf of a specific seat (array)

Note: The id must match the one provided in the request

seatbid​

AttributeRequired?Description
bidYesArray of the bid object related to the targeted impression

seatbid.bid​

AttributeRequired?Description
idYesID for the bid object, used for tracking (string)
impidYesID of the impression object in the related bid request.
priceYesBid price in CPM or CPC (float)
admYesXML/JSON Ad Markup (string)
nurlYesWin notification URL, it is recommended to use HTTP over HTTPS for nurl (string)
burlNoBilling notification URL, it is recommended to use HTTP over HTTPS for nurl (string)
extNoExoClick specific extension (object)

Notes:

  • The impid must match the one provided in the request.

  • The adm must be provided in JSON or XML based on the ad format targeted: JSON for Native, In-Stream and Push Notifications; XML for all the other formats.

  • The nURL must be notified in order to ensure campaign capping and avoid getting the same response every time.

  • The bURL is called when impressions or clicks have been delivered, depending on CPM or CPC from btype field (default CPM).

seatbid.bid.ext​

AttributeRequired?Description
btypeRecommendedPricing Model. Values: 1 = CPM, 2 = CPC. Default = 1 (int).

Note: When the response is for an Email Clicks zone request, 1 = Smart CPC.

No Bid Response​

To answer to a bid request without making an actual bid, an HTTP response code 204 "No Content" should be sent.

Win and Billing Notification URLs​

If either the nURL or the bURL are in the bid response and are valid URLs, ExoClick platform will send a GET request to them. These URLs can have a few tokens to be replaced by ExoClick before doing the GET:


${AUCTION_ID} - ID of the bid request; from "Bid Request Object -> id" attribute.
${AUCTION_BID_ID} - ID of the bid; from "Bid Response Object -> bidid" attribute.
${AUCTION_IMP_ID} - ID of the impression just won; from "Bid Request Object -> Impression Object -> id" attribute.
${AUCTION_SEAT_ID} - ID of the bidder seat for whom the bid was made; from "Bid Response Object -> Seat Bid Object -> Bid Object -> id" attribute.
${AUCTION_AD_ID} - ID of the ad markup the bidder wishes to serve; from "Bid Response Object -> Seat Bid Object -> Bid Object -> adid" attribute.
${AUCTION_PRICE} - Settlement price using the same currency and units as the account; from "Bid Response Object -> Seat Bid Object -> Bid Object -> price" attribute.
${AUCTION_CURRENCY} - The currency used in the bid (explicit or implied); for confirmation only.

Example:


https://mysite.com/my_notification_url?id=${AUCTION_ID}&bidid=${AUCTION_BID_ID}&price=${AUCTION_PRICE}&currency=${AUCTION_CURRENCY}

If you are using both nURL and bURL, ExoClick will make a call to both of them.

ADM structure​

Depending on the ad format, the adm parameter can contain a piece of XML or JSON. You can find detailed examples of adm structures in our examples page

When creating the ADM, please bear in mind the following:

  • iFrame markups (Banner, Fullpage Interstitial) must be enabled in your ExoClick account in order to be able to use them.

  • In-Stream, Native and Push Notification ads should contain a JSON encoded string in the adm.

  • The adm parameter from In-Stream can follow one of two structures: Remote VAST or Local VAST. In Remote VAST, you simply need to declare the URL where the VAST Wrapper is located, whereas in Local VAST you need to declare any "trackingEvents" you want to track in addition to the "videoURL" and "clickURL".

Currently we support impression, progress and complete events. Impression and progress events are compulsory, whereas complete can be added only if you are using Local VAST.

The ADM must follow the same structure as shown in our example above.

  • As an optional parameter, you can include crop_anchor_point in the JSON string from the Native Ads adm to determine where the anchor point of your native image is located. The available values are:

    • MIDDLE_CENTER = 0,
    • TOP_LEFT = 1,
    • TOP_CENTER = 2,
    • TOP_RIGHT = 3,
    • MIDDLE_LEFT = 4,
    • MIDDLE_RIGHT = 5,
    • BOTTOM_LEFT = 6,
    • BOTTOM_CENTER = 7,
    • BOTTOM_RIGHT= 8

Here is a visualization of the available anchor points:

crop anchor point

Note that, while we also allow imptrackers in Native Ads, we strongly recommend using eventtrackers instead.

  • Push Notification ads only allow one image asset per notification. The width and height depend on what's coming from the request, which can be 192x192 or 720x480. Note that the adm must also be a JSON encoded string as the request will be coming from a Native object.

  • Lastly, Push Notification ads allow only one "imptracker" URL

Examples​

You can find detailed examples from Bid responses and ADM structures in our Advertiser Response example page