Share via

Incoming bid response from bidder

  • Article

Warning

This describes the integration of the OpenRTB 2.4 protocol.

A bidder will send a bid response after it receives a Bid Request from the impression bus. The bid response will include the bidder's bid (price) and chosen creative (creative_id or creative_code). This creative will be served if the bid is ultimately accepted by the ad server. Multiple bids within the bid response are encouraged.

Implementation

Refer to the following links to locate the objects that you need more information on.

Bid request object | Seat Bid Object | Bid Object | Bid Response Extension Object | AppNexus Object | Custom Macro Object | Bid Payment Type Object |

Xandr expects all calls to return HTTP code 200 except for an empty bid response (no bid), which will return HTTP code 204. We currently support the following fields in the bid response object.

Bid response object

Field Type Description
id string Required: The ID of the bid request to which this is a response.
seatbid array of objects Required if a bid is made: Used for identifying seatbid objects. See Seat Bid Object for more information.
bidid string The bid response ID to assist tracking for bidders. This value is chosen by the bidder for cross-reference.

Note: This is used only to populate the macro ${AUCTION_BID_ID}. We do not store this information.
cur string The bid currency using ISO-4217 alphabetic codes. If omitted, default is USD. Also used for the macro ${AUCTION_CURRENCY} in the win notify URL and creative or pixel payload.

Seat bid object

Xandr supports the following fields in the seatbid object, each of which represents a different bidder seat and contains one or more individual bids.

Field Type Description
bid array of objects Required: An array of bid objects; each bid object relates to an Impression Object in the Bid Request.

Note: If supported by an exchange, one Impression Object can have many bid objects. See Bid Object for more information.
seat string Required: The ID of the member whose creative is chosen by the bidder and corresponds to the Xandr member_id. Also used to populate the ${AUCTION_SEAT_ID} macro in the win notify URL and creative or pixel payload.

Note:
- For DSPs migrated to Buyer Seat ID bidding, they can use buyer IDs native to their own systems. These identifiers will be registered as Seat Codes in Xandr systems.
- This feature is currently in Closed Beta. If you are interested in participating, reach out to your Xandr representative.

Bid object

Field Type Description
id string Required: The ID for the bid object; this is chosen by the bidder for tracking and debugging purposes. Useful when multiple bids are submitted for a single impression for a given seat.
impid string Required: The ID of the impression object to which this bid applies. Should match the id field from the bid request's impression object. Can be used to populate the ${AUCTION_IMP_ID} macro.
price float Required: The bid price expressed in CPM. Also used to populate the ${AUCTION_PRICE} macro.

If the bid_payment_type is not set to "Impression", then price will be the eCPM price for the bid, and the payment_type_price will be used to populate the ${{AUCTION_PRICE} macro.PRICE} macro.

Note: bid_payment_type is not enabled for all clients. Reach out to your account representative for this feature.

Warning: Although this value is a float, OpenRTB strongly suggests using integer math for accounting to avoid rounding errors.
adid string The Xandr creative ID, viewable via the API using the Creative Service. This ID references the actual ad to be served if the bid wins. Can be used to populate the ${AUCTION_AD_ID} macro. If both adid and crid are passed, adid takes precedence.
nurl string The win notify URL, which is dropped as a pixel into the web browser or SDK. Our server pings this URL when it receives a client-side notification from the device, which indicates that we won the auction. Responses will be sent server side. This occurs at the same time when we record the impression. The max length is 2000 characters with macros expanded.

The following macros are supported in the notify URL:
${AUCTION_ID} - Xandr auction_id_64
${AUCTION_BID_ID} - ID of the bid specified in the bidid field in the bid response
${AUCTION_IMP_ID} - ID of the impression, from the impid field in the bid object of the seatbid object
${AUCTION_SEAT_ID} - ID of the winning seat, from the seat field in the seatbid object
${AUCTION_AD_ID} - ID of the buyer's creative, from the adid field in the bid object of the seatbid object
${AUCTION_PRICE} - Clearing price of the impression in the currency specified in the cur field in the bid response
${AUCTION_CURRENCY} - Currency of the clearing price, as specified in the cur field in the bid response
${CREATIVE_CODE} - The code field set on the creative object via the API when registering a creative
${AN_PAYMENT_TYPE} - ID of the payment type of bid specified in the bid_payment_type field of the bid response

Note:
- This macro is not enabled for all clients. Please reach out to your account representative for this feature.
- Only the macros in the preceding list can be used in the notify URL, no other macros are supported in the bid response.
lurl string Warning: This feature is currently in closed beta testing and is not available to all bidder integrations. If you would like to use this field in the bid response, please reach out to your account representative or file a support ticket at https://help.xandr.com.

Loss notice URL called by Xandr when a bid is known to have been lost. Substitution macros may be included. Responses will be sent server side.

The following macros are supported in the loss notice URL.
${AUCTION_ID} - Xandr auction_id_64
${AUCTION_BID_ID} - ID of the bid specified in the bidid field in the bid response
${AUCTION_IMP_ID} - ID of the impression, from the impid field in the bid object of the seatbid object
${AUCTION_SEAT_ID} - ID of the winning seat, from the seat field in the seatbid object
${AUCTION_AD_ID} - ID of the buyer's creative, from the adid field in the bid object of the seatbid object
${AUCTION_LOSS} - Loss reason codes
${AUCTION_CURRENCY} - Currency of the clearing price, as specified in the cur field in the bid response
${CREATIVE_CODE} - The code field set on the creative object via the API when registering a creative.

For the full list of loss reason codes that are supported in the ${AUCTION_LOSS} macro, see Loss Reason Codes.
crid string The creative ID from the bidder's system. Used to reference a Xander creative based on the creative code as set via the Creative Service. If both adid and crid are passed, adid takes precedence.
cid string The campaign ID from the bidder's system. Used for SSP reporting.
dealid string The deal ID from the deal object in the Bid Request, if this bid relates to a deal.
ext object Used for identifying platform-specific extensions to the OpenRTB bid response. See Bid Response Extension Object.

Bid response extension object

Xandr supports a single object in the ext object to support platform-specific extensions.

Field Type Description
appnexus object Specifies the platform-specific extensions to the OpenRTB bid response. See AppNexus Object.

AppNexus object

Xandr supports the following fields in the appnexus extension object.

Field Type Description
custom_macros array of objects Used for identifying custom_macro objects. See Custom Macro Object.
min_price float The minimum price to which the bid should be reduced in the second price auction.
spend_protection_pixel_ids array of integers Deprecated.
custom_notify_data string Note: This feature is not enabled by default. You must request to have this field enabled.

Use this field to pass information to the Notify Request. The string is entered as freeform text and will be automatically URL- and/or cookie-encoded by ImpBus.
click_url string The click URL to be associated with the creative. This field should contain a redirect link. For example, https://mydomain.com/abcd?redir=
enable_bid_shading integer Note: This field is in the process of being deprecated. It is set as false irrespective of the value sent in the bid response.
bid_payment_type array of objects Note: This feature is not enabled by default. You must request to have this field enabled.

Specifies the payment type for which the Bidder is bidding and will be billed. If omitted, then we will consider the payment type to be 'impression'.

Custom macro object

Xandr supports the following fields in the custom_macro object of the appnexus extension object.

Field Type Description
name string The name of the macro to be replaced in any of the creative's URLs (media, pixel, click, and so on). The name must be formatted as ${MACRO_NAME} within the creative's URL or content.

Note: The custom macros are replaced AFTER system macros have been replaced. Refer to the Creative Service for more information.
value string The value used to replace the macro. Do not escape forward slashes. Even if the value is an integer, it must be placed within quotation marks (for example, "42"). The max length of the value is 550 characters.

Bid payment type object

Xandr supports the following fields in the bid_payment_type object of the appnexus extension object.

Note

This feature is not enabled by default. You must request to have this field enabled.

Field Type Description
payment_type integer Specifies the payment type for which the Bidder is bidding and will be billed. If the payment type is not 'impression', then a billing notify URL must be set on the bid object. The currently supported values are -
1: Impression
2: Views - Standard Display
6: Views - Custom Display - 100pv1s
8: Views - Standard Video
9: Views - Custom Video - 100pv50pd

Note: Currently, for "Viewable Impression" bids, only USD bids are supported.
price double Specifies the bid price for the payment type. For the 'Viewable Impression' payment type, the bid price will be vCPM.

For more information, check the Overview page.

Note

Why we don't support the adm field?

Xandr works with members who care deeply about brand and reputation. For this reason, we are careful to ensure that the advertisements (creatives) that pass through our system are acceptable to all parties. For quality assurance, all creatives that serve on third-party inventory must be pre-registered using the Creative Service.

For these reasons, Xandr does not support the adm field (which allows bidders to pass in the actual ad markup). Instead, we construct the ad markup using the provided adid and nurl for win notification.

Example for bid response

{
    "id": "4876290993254515176",
    "seatbid": [{
        "bid": [{
                "id": "1",
                "impid": "8278013996604217356",
                "price": 1,
                "adid": "16",
                "nurl": "https://68.67.148.76:10011/notify?TAFFYOpenRTBAuctionID=${AUCTION_ID}&price=${AUCTION_PRICE}",
                "ext": {
                    "appnexus": {
                        "custom_macros": [{
                            "name": "dynamic_ad_markup",
                            "value": "dynamic.js"
                        }]
                    }
                }
            }

        ],
        "seat": "2739"
    }],
    "bidid": "1",
    "cur": "USD"
}

Example for multi-bid response

Multi-bid response for one seat value
Option 1
{
    "id": "4876290993254515176",
    "seatbid": [{
        "bid": [{
                "id": "1",
                "impid": "8278013996604217356",
                "price": 1,
                "adid": "16",
                "nurl": "https://68.67.148.76:10011/notify?TAFFYOpenRTBAuctionID=${AUCTION_ID}&price=${AUCTION_PRICE}"
            },
            {
                "id": "2",
                "impid": "8278013996604245835",
                "price": 1,
                "adid": "22",
                "nurl": "https://68.67.148.76:10011/notify?TAFFYOpenRTBAuctionID=${AUCTION_ID}&price=${AUCTION_PRICE}"
            },
            {
                "id": "3",
                "impid": "2345613996604245835",
                "price": 1,
                "adid": "23",
                "nurl": "https://68.67.148.76:10011/notify?TAFFYOpenRTBAuctionID=${AUCTION_ID}&price=${AUCTION_PRICE}"
            }
        ],
        "seat": "2739"
    }],
    "bidid": "1",
    "cur": "USD"
}
Option 2
{
    "id": "4876290993254515176",
    "seatbid": [{
        "bid": [{
                "id": "1",
                "impid": "8278013996604217356",
                "price": 1,
                "adid": "16",
                "nurl": "https://68.67.148.76:10011/notify?TAFFYOpenRTBAuctionID=${AUCTION_ID}&price=${AUCTION_PRICE}"
            } 
        ],
        "seat": "2739"
    }],
    "seatbid": [{
        "bid": [ {
                "id": "2",
                "impid": "8278013996604245835",
                "price": 1,
                "adid": "22",
                "nurl": "https://68.67.148.76:10011/notify?TAFFYOpenRTBAuctionID=${AUCTION_ID}&price=${AUCTION_PRICE}"
            }
        ],
        "seat": "2739"
    }],
    "seatbid": [{
       "bid": [ {
                "id": "3",
                "impid": "2345613996604245835",
                "price": 1,
                "adid": "23",
                "nurl": "https://68.67.148.76:10011/notify?TAFFYOpenRTBAuctionID=${AUCTION_ID}&price=${AUCTION_PRICE}"
            }
        ],
        "seat": "2739"
    }],
    "bidid": "1",
    "cur": "USD"
}
Multi-bid response for multiple seat values
{
    "id": "4876290993254515176",
    "seatbid": [{
        "bid": [{
                "id": "1",
                "impid": "8278013996604217356",
                "price": 1,
                "adid": "16",
                "nurl": "https://68.67.148.76:10011/notify?TAFFYOpenRTBAuctionID=${AUCTION_ID}&price=${AUCTION_PRICE}"
            }
 
        ],
        "seat": "2739"
    },
    {
        "bid": [{
                "id": "1",
                "impid": "8278013996604217356",
                "price": 1,
                "adid": "15",
                "nurl": "https://68.67.148.76:10011/notify?TAFFYOpenRTBAuctionID=${AUCTION_ID}&price=${AUCTION_PRICE}"
            }
 
        ],
        "seat": "1234"
    },
    {
        "bid": [{
                "id": "1",
                "impid": "8278013996604217356",
                "price": 1,
                "adid": "22",
                "nurl": "https://68.67.148.76:10011/notify?TAFFYOpenRTBAuctionID=${AUCTION_ID}&price=${AUCTION_PRICE}"
            }
 
        ],
        "seat": "9876"
    }],
    "bidid": "1",
    "cur": "USD"
}

Win notification

For more information, see the definition of the nurl field above.

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.

Loss notification

If you opt for a loss notification, it will look something like this. The loss notification information appears at the end of the response.

{
    "notify_request": {
        "timestamp": "2016-03-17 06: 52: 40 ",
        "auction_timestamp": "2016 - 03 - 17 06: 52: 40 ",
        "user_id_64 ": 659854875312903738,
        "response_time_ms ": 40,
        "bid_info ": {
            "no_cookies": false,
            "payment_rule_id": 1772411,
            "no_flash": false,
            "browser": 7,
            "operating_system": 2,
            "operating_system_extended": 91,
            "operating_system_family": 5,
            "carrier": 1,
            "device_type": 1,
            "language": 1,
            "session_freq": 1,
            "pub_session_freq": 1,
            "country": "US",
            "within_iframe": false,
            "selling_member_id": 701,
            "publisher_id": 1483811,
            "user_id_64": 659214875312903738,
            "ip_address": "98.21.53.49",
            "user_agent": "Mozilla/5.0 (Windows NT 6.0; WOW64; rv: 44.0) Gecko / 20100101Firefox / 44.0 ",
            "region ": "PA ",
            "city ": "Ephrata",
            "postal_code ": "17522 ",
            "postal_code_id ": 12813,
            "dma ": 566,
            "time_zone ": "America / New_York ",
            "url ": "https: //www.example.com/",
            "domain": "example.com",
            "device_ids": {},
            "inventory_audits": [{
                "auditor_member_id": null,
                "intended_audience": "general",
                "inventory_attributes": [],
                "content_categories": [27, 8476]
            }],
            "userdata_json": "{\"uid\":\"5xb25EqcY3Hd9B\"}",
            "tpuids": [{
                "user_id": "5xc25EqcY3Hc9B"
            }],
            "segments": [{
                "id": 1,
                "member_id": 0,
                "code": "cookie_birthday",
                "provider": "Appnexus",
                "last_seen_min": 23767080
            }, {
                "id": 2087662,
                "member_id": 2636,
                "last_seen_min": 23959609
            }]
        },
        "tags": [{
            "id": 6123680,
            "auction_id_64": 4123382184097823951,
            "full_tag_info": {
                "auction_id_64": 4123382184097823951,
                "size": "300x250",
                "sizes": ["300x250"],
                "smaller_sizes_allowed": false,
                "position": "unknown",
                "tag_format": "iframe",
                "ad_profile_id": 114603,
                "visibility_profile_id": 625,
                "allowed_media_types": [1, 11],
                "media_subtypes": ["banner"],
                "predicted_view_rate": 0.1708,
                "estimated_clear_price": 9.00000,
                "estimated_average_price": 3.1630,
                "id": 6003680,
                "site_id": 1672260,
                "venue_id": 1299844
            },
            "payment_rule_id": 177245,
            "notify_type": "lost"
        }],
        "responses": [{
            "result": "error",
            "error": "Creative inactive, expired or not found by code;Member id: 1999,code: '537748'",
            "error_id ": 307
        }]
    }
}