Server to Server Wrapper Tag: Response Parameters & Sample

Document created by pubmatic-archivist on Mar 27, 2017Last modified by catherine.racette on Sep 25, 2017
Version 5Show Document
  • View in full screen mode

Response Parameters for Server Side Header Bidding Wrapper

The response from each partner is converted to Standard Open RTB Response Format (currently Version 2.4). If a partner's response contains bids for multiple impressions (e.g., in the Open RTB Response), then the response would be split into multiple Open RTB Response Objects. Each of the Open RTB Responses would be passed to controller. 

On valid request PubMatic will send back response in open RTB standard with 200 OK. All fields, which can be sent by PubMatic, are listed in tables below.

In case of an incorrect request/mandatory parameter missing or PubMatic have no creative will return back 204 no content.]

 

Object: BidResponse                                                   

AttributeTypeDescriptionSupported
idStringID of the bid request to which this is a response.Yes
seatbidObjectArray of seatbid objects; 1+ required if a bid is to be madeYes
bidid StringBidder generated response ID to assist with logging/tracking.Yes
curStringBid currency using ISO-4217 alpha codes. Default=USDYes
customdataStringOptional feature to allow a bidder to set data in the exchange's cookie. The string must be in base85 cookie safe characters and be in any format. Proper JSON encoding must be used to include "escaped" quotation marks.Yes
nbrIntegerReason for not biddingYes
extObjectPlaceholder for bidder-specific extensionsYes

Object: SeatBid                                 

AttributeTypeDescriptionSupported
bidObjectArray required Array of 1+ Bid objects each related to an impression. Multiple bids can relate to the same impression.Yes
seatStringID of the bidder seat on whose behalf this bid is made.Yes
groupInteger

Default=0

0=impressions can be won individually; 1=impressions must be won or lost as a group.

Yes
extObjectPlaceholder for bidder-specific extensionsYes

Object: Bid                                                                                                                                  

AttributeTypeDescriptionSupported
idStringBidder generated bid ID to assist with logging/tracking.Yes
impidStringID of the Imp object in the related bid request.Yes
priceStringBid price expressed as CPM although the actual transaction is for a unit impression only.Yes
nurlStringID of a preloaded ad to be served if the bid wins (not necessarily indicative of a delivered, viewed, or billable ad); optional means of serving ad markup.Yes
admStringMeans of conveying ad markup in case the bid wins.Yes
adomainString ArrayAdvertiser domain for block list checking (e.g., “ford.com”). This can be an array of for the case of rotating creatives.Yes
bundleStringA platform-specific application identifier intended to be unique to the app and independent of the exchange. On Android, this should be a bundle or package name (e.g., com.foo.mygame). On iOS, it is a numeric ID.Yes
iurlStringURL without cache-busting to an image that is representative of the content of the campaign for ad quality/safety checking.Yes
cidStringCampaign ID to assist with ad quality checking; the collection of creatives for which iurl should be representative.Yes
cridStringCreative ID to assist with ad quality checkingYes
adidStringID of a preloaded ad to be served if the bid wins.Yes
catString ArrayIAB content categories of the creative. Yes
attrInteger ArraySet of attributes describing the creative.Yes
apiIntegerAPI required by the markup if applicable.Yes
protocolIntegerVideo response protocol of the markup if applicable.Yes
qagmediaratingIntegerCreative media rating per IQG guidelines.Yes
dealidStringReference to the deal.id from the bid request if this bid pertains to a private marketplace direct deal.Yes
wIntegerWidth of the creative in device independent pixels (DIPS).Yes
hIntegerHeight of the creative in device independent pixels (DIPS).Yes
expIntegerAdvisory as to the number of seconds the bidder is willing to wait between the auction and the actual impression.Yes
extObjectPlaceholder for bidder-specific extensions to OpenRTBYes

 

Object: Bid.ext                   

AttributeTypeDescriptionSupported
dspidStringDsp IDYes
advidStringAdvertiser IDYes
 

Supported Response Formats

Client Type will come in as rs in the OpenRTB request (1: pwt/ortb (default), 2: gshowad.js, 3: dm_gpt_generic.js)

Response format will be a combination of client id and DB mapping. If Adserver Id=2, key-value separator will be '=', else if AdServer Id=3 or 4, separator will be ','

 

The following are supported response formats for the Server Side Header Bidding API.

1. Default Open RTB 2.4 Response (rs=1). 

This will be the default response when rs is not present in the request.

Sample Open RTB 2.4 Response

{
    "id": null,
    "seatbid": [{
        "bid": [{
            "impid": "1471504048821_0",
            "price": 2,
            "adm": "%3Cspan%20class%3D%22PubAPIAd%22%20%20id%3D%22F3FD629F-4C35-4F64-8CE6-C3FAA8E13792%22%3E%3Chtml%3E%3Cbody%3E%20%3C%2Fbody%3E%3C%2Fhtml%3E%3C%2Fspan%3E%20%3C%21--%20PubMatic%20Ad%20Ends%20--%3E",
            "h": 90,
            "w": 728,
            "ext": {
                "extension": {
                    "trackingUrl": "http://aktrack.pubmatic.com/AdServer/AdDisplayTrackerServlet?operId=1&pubId=5890&siteId=39725&adId=97113&adServerId=1303&kefact=2.000000&kaxefact=2.000000&kadNetFrequecy=0&kadwidth=728&kadheight=90&kadsizeid=7&kltstamp=1473925384&indirectAdId=0&adServerOptimizerId=2&ranreq=0.35227230576370405&kpbmtpfact=0.000000&dcId=4&tldId=20896101&passback=25&imprId=4D1A5C42-CCDA-434A-9479-3E60376A90AD&oid=4D1A5C42-CCDA-434A-9479-3E60376A90AD&ias=272&crID=0&ucrid=13213156294910600931&campaignId=0&pageURL=http%253A%252F%252F172.16.4.36%252FssWrapperTest.html",
                    "slotname": "DMDemo@728x90",
                    "slotindex": 0
                }
            }
        }, {
            "impid": "1471504048821_1",
            "price": 2,
            "adm": "%3Cspan%20class%3D%22PubAPIAd%22%20%20id%3D%22490E2DDD-B643-4D74-B9B9-01EBF5358C8D%22%3E%3Chtml%3E%3Cbody%3E%20%3C%2Fbody%3E%3C%2Fhtml%3E%3C%2Fspan%3E%20%3C%21--%20PubMatic%20Ad%20Ends%20--%3E",
            "h": 250,
            "w": 300,
            "ext": {
                "extension": {
                    "trackingUrl": "http://aktrack.pubmatic.com/AdServer/AdDisplayTrackerServlet?operId=1&pubId=5890&siteId=39725&adId=97113&adServerId=1303&kefact=2.000000&kaxefact=2.000000&kadNetFrequecy=0&kadwidth=728&kadheight=90&kadsizeid=7&kltstamp=1473925384&indirectAdId=0&adServerOptimizerId=2&ranreq=0.35227230576370405&kpbmtpfact=0.000000&dcId=4&tldId=20896101&passback=25&imprId=6F100F6C-BB99-4481-ABCE-AE6627999BB0&oid=6F100F6C-BB99-4481-ABCE-AE6627999BB0&ias=272&crID=0&ucrid=1747262745997287654&campaignId=0&pageURL=http%253A%252F%252F172.16.4.36%252FssWrapperTest.html",
                    "slotname": "DMDemo1@300x250",
                    "slotindex": 0
                }
            }
        }, {
            "impid": "1471504048821_2",
            "price": 2,
            "adm": "%3Cspan%20class%3D%22PubAPIAd%22%20%20id%3D%22490E2DDD-B643-4D74-B9B9-01EBF5358C8D%22%3E%3Chtml%3E%3Cbody%3E%20%3C%2Fbody%3E%3C%2Fhtml%3E%3C%2Fspan%3E%20%3C%21--%20PubMatic%20Ad%20Ends%20--%3E",
            "h": 90,
            "w": 728,
            "ext": {
                "extension": {
                    "trackingUrl": "http://aktrack.pubmatic.com/AdServer/AdDisplayTrackerServlet?operId=1&pubId=5890&siteId=39725&adId=97113&adServerId=1303&kefact=2.000000&kaxefact=2.000000&kadNetFrequecy=0&kadwidth=728&kadheight=90&kadsizeid=7&kltstamp=1473925384&indirectAdId=0&adServerOptimizerId=2&ranreq=0.35227230576370405&kpbmtpfact=0.000000&dcId=4&tldId=21358545&passback=25&imprId=C96233F8-D1F1-40AD-8074-5A0F867401EF&oid=C96233F8-D1F1-40AD-8074-5A0F867401EF&ias=272&crID=0&ucrid=10016402110716446289&campaignId=0&pageURL=http%253A%252F%252F172.16.4.36%252FssWrapperTest.html",
                    "slotname": "DMDemo2@728x90",
                    "slotindex": 1
                }
            }
        }]
    }]
}

     

2. DM Standard Response for gshowad.js (rs=2)

Based on the mapping configuration (AdServer Id) PubMatic will have a different response format. If there is no mapping present we will present the default response with a '=' separator

Sample Response when Adserver Id= 2 (default format)

var bidDetailsMap = {
    "/15671365/DMDemo1@300x250:1": {
        "ecpm": 2,
        "creative_tag": "\u003cspan class=\"PubAPIAd\"\u003e\u003chtml\u003e\u003cbody\u003e \u003c/body\u003e\u003c/html\u003e\u003c/span\u003e \u003c!-- PubMatic Ad Ends --\u003e",
        "tracking_url": "http://aktrack.pubmatic.com/AdServer/AdDisplayTrackerServlet?operId=1\u0026pubId=5890\u0026siteId=39725\u0026adId=97113\u0026adServerId=1303\u0026kefact=2.000000\u0026kaxefact=2.000000\u0026kadNetFrequecy=0\u0026kadwidth=300\u0026kadheight=250\u0026kadsizeid=7\u0026kltstamp=1471342744\u0026indirectAdId=0\u0026adServerOptimizerId=2\u0026ranreq=0.1\u0026kpbmtpfact=0.000000\u0026dcId=4\u0026tldId=20291892\u0026passback=25\u0026imprId=DA3158F0-247B-4DB8-8138-22A6717CFBE8\u0026oid=DA3158F0-247B-4DB8-8138-22A6717CFBE8\u0026ias=272\u0026crID=0\u0026campaignId=0\u0026pageURL=http%3A%2F%2F172.16.4.36%2FssWrapperTest.html",
        "width": 300,
        "height": 250
    },
    "/15671365/DMDemo2@728x90:1": {
        "ecpm": 0,
        "creative_tag": null,
        "tracking_url": null,
        "width": null,
        "height": null
    }
};
var progKeyValueMap = {
    "/15671365/DMDemo1@300x250:1": "bidstatus=1;bid=2.000000;bidid=/15671365/DMDemo1@300x250:1;wdeal=",
    "/15671365/DMDemo2@728x90:1": "bidstatus=0;bid=0.000000;bidid=/15671365/DMDemo2@728x90:1;wdeal="
};
if (typeof buzz === 'function') {
    buzz();
}

    

Sample Response when Adserver Id = 3

var bidDetailsMap = {
    "/15671365/DMDemo1@300x250:1": {
        "ecpm": 2,
        "creative_tag": "\u003cspan class=\"PubAPIAd\"\u003e\u003chtml\u003e\u003cbody\u003e \u003c/body\u003e\u003c/html\u003e\u003c/span\u003e \u003c!-- PubMatic Ad Ends --\u003e",
        "tracking_url": "http://aktrack.pubmatic.com/AdServer/AdDisplayTrackerServlet?operId=1\u0026pubId=5890\u0026siteId=39725\u0026adId=97113\u0026adServerId=1303\u0026kefact=2.000000\u0026kaxefact=2.000000\u0026kadNetFrequecy=0\u0026kadwidth=300\u0026kadheight=250\u0026kadsizeid=7\u0026kltstamp=1471341115\u0026indirectAdId=0\u0026adServerOptimizerId=2\u0026ranreq=0.1\u0026kpbmtpfact=0.000000\u0026dcId=4\u0026tldId=20291816\u0026passback=25\u0026imprId=82C474D4-FB6F-4096-B8E2-6FBAA217ACD6\u0026oid=82C474D4-FB6F-4096-B8E2-6FBAA217ACD6\u0026ias=272\u0026crID=0\u0026campaignId=0\u0026pageURL=http%3A%2F%2F172.16.4.36%2FssWrapperTest.html",
        "width": 300,
        "height": 250
    },
    "/15671365/DMDemo2@728x90:1": {
        "ecpm": 2,
        "creative_tag": "\u003cspan class=\"PubAPIAd\"\u003e\u003chtml\u003e\u003cbody\u003e \u003c/body\u003e\u003c/html\u003e\u003c/span\u003e \u003c!-- PubMatic Ad Ends --\u003e",
        "tracking_url": "http://aktrack.pubmatic.com/AdServer/AdDisplayTrackerServlet?operId=1\u0026pubId=5890\u0026siteId=39725\u0026adId=97113\u0026adServerId=1303\u0026kefact=2.000000\u0026kaxefact=2.000000\u0026kadNetFrequecy=0\u0026kadwidth=728\u0026kadheight=90\u0026kadsizeid=7\u0026kltstamp=1471341115\u0026indirectAdId=0\u0026adServerOptimizerId=2\u0026ranreq=0.1\u0026kpbmtpfact=0.000000\u0026dcId=4\u0026tldId=0\u0026passback=25\u0026imprId=9FE06691-BA0B-4283-B36E-FFECCB520DFA\u0026oid=9FE06691-BA0B-4283-B36E-FFECCB520DFA\u0026ias=272\u0026crID=0\u0026campaignId=0\u0026pageURL=http%3A%2F%2F172.16.4.36%2FssWrapperTest.html",
        "width": 728,
        "height": 90
    }
};
var progKeyValueMap = {
    "/15671365/DMDemo1@300x250:1": "bidstatus;1;bid;2.000000;bidid;/15671365/DMDemo1@300x250:1;wdeal;",
    "/15671365/DMDemo2@728x90:1": "bidstatus;1;bid;2.000000;bidid;/15671365/DMDemo2@728x90:1;wdeal;"
};
if (typeof buzz === 'function') {
    buzz();
}

    

3. DM Standard Response for dm_gpt_generic.js (rs=3)

Based on the mapping configuration (Adserver Id), PubMatic will  we will have different response format. In case there is no mapping present we will have default response with ';' separator

Sample Response when Adserver Id = 3 (default response format)

bidDetailsMap["4bd7f5b68a014e8e3ce9ed51c6206c23"] = {
    "ecpm": 0.5100,
    "creative_tag": "%3Cspan%20class%3D%22PubAPIAd%22%3E%3Cdiv%20id%3D%22sonar-admedium-E62B6743%22%3E%3Cscript%20type%3D%22text%2Fjavascript%22%3Evar%20sonar_admedia%3Dsonar_admedia%7C%7C%7B%7D%3Bsonar_admedia%5B%27E62B6743%27%5D%3D%7Bsize%3A3%2Cref%3A%27wfaa.com%27%2Cuid%3A%2715246455031303320585%27%2Ccid%3A%279604%27%2Caaid%3A%277660638269465052685%27%2Cbwa%3A%270.51%27%2Cssp%3A%27pubmatic-ap%27%2Cts%3A1471855679%2Csig%3A%277CrnkL_fNpqVrup6dcLUTn0tY2L_LJeccW8W4BGORrllMP5_krK0Cq77cS5h40aLQfZRGnKP0PqTTfZOKbX74aJ8cOE%2A%27%7D%3B%3C%2Fscript%3E%3C%2Fdiv%3E%3Cscript%20type%3D%22text%2Fjavascript%22%3E%28function%28%29%7Bvar%20s%3Ddocument.createElement%28%27script%27%29%3Bvar%20x%3Ddocument.getElementsByTagName%28%27script%27%29%5B0%5D%3Bs.type%3D%27text%2Fjavascript%27%3Bs.async%3Dtrue%3Bs.src%3D%28%27https%3A%27%3D%3Ddocument.location.protocol%3F%27https%3A%2F%2F%27%3A%27http%3A%2F%2F%27%29%2B%20%27ap-sonar.sociomantic.com%2Fjs%2F2010-07-01%2Fadpan%2Fpubmatic-ap%3F2013-07-23%27%3Bx.parentNode.insertBefore%28s%2Cx%29%3B%7D%29%28%29%3B%3C%2Fscript%3E%0A%3Cscript%20type%3D%22text%2Fjavascript%22%20src%3D%22https%3A%2F%2Fc.betrad.com%2Fsurly.js%3F%3Bad_w%3D728%3Bad_h%3D90%3Bcoid%3D348%3Bnid%3D7875%3Becaid%3D28489%3B%22%3E%3C%2Fscript%3E%3C%2Fspan%3E%20%3C%21--%20PubMatic%20Ad%20Ends%20--%3E",
    "tracking_url": "http%3A%2F%2Faktrack.pubmatic.com%2FAdServer%2FAdDisplayTrackerServlet%3FoperId%3D1%26pubId%3D28489%26siteId%3D134824%26adId%3D575087%26adServerId%3D243%26kefact%3D0.510000%26kaxefact%3D0.510000%26kadNetFrequecy%3D1%26kadwidth%3D728%26kadheight%3D90%26kadsizeid%3D7%26kltstamp%3D1471855679%26indirectAdId%3D0%26adServerOptimizerId%3D2%26ranreq%3D0.21417216721543686%26kpbmtpfact%3D0.510000%26dcId%3D4%26tldId%3D20196051%26passback%3D0%26imprId%3D0F7C5D3E-C385-4410-B859-110744273F56%26oid%3D0F7C5D3E-C385-4410-B859-110744273F56%26ias%3D257%26fbs%3D1%26crID%3D0300258457955680%26campaignId%3D19713%26creativeId%3D0%26pctr%3D0.000000%26wDSPByrId%3D1%26pageURL%3Dhttp%253A%252F%252Fwww.wfaa.com%252F%26lpu%3Djungleerummy.com",
    "width": "728",
    "height": "90"
};
bidDetailsMap["f5683f5a28f9182ad637a02578e9730b"] = {
    "ecpm": 0.0000,
    "creative_tag": "",
    "tracking_url": "",
    "width": "0",
    "height": "0",
    "error": "2"
};
bidDetailsMap["76e9304f35ae2beea28b73312ca442a0"] = {
    "ecpm": 0.0000,
    "creative_tag": "",
    "tracking_url": "",
    "width": "0",
    "height": "0",
    "error": "2"
};
progKeyValueMap["/32805352/tx-dallas-WFAA-B3341/home@728x90:0"] = "bidstatus;3;bid;0.5100;bidid;4bd7f5b68a014e8e3ce9ed51c6206c23;wdeal;";
progKeyValueMap["/32805352/tx-dallas-WFAA-B3341/home@960x66:0"] = "bidstatus;0;bid;0.0000;bidid;f5683f5a28f9182ad637a02578e9730b;wdeal;";
progKeyValueMap["/32805352/tx-dallas-WFAA-B3341/home@970x66:0"] = "bidstatus;0;bid;0.0000;bidid;76e9304f35ae2beea28b73312ca442a0;wdeal;";
if (typeof DM.callBack === 'function') {
    DM.callBack();
}

Sample Response when AdServer Id = 2

bidDetailsMap["4bd7f5b68a014e8e3ce9ed51c6206c23"] = {
    "ecpm": 0.5100,
    "creative_tag": "%3Cspan%20class%3D%22PubAPIAd%22%3E%3Cdiv%20id%3D%22sonar-admedium-E62B6743%22%3E%3Cscript%20type%3D%22text%2Fjavascript%22%3Evar%20sonar_admedia%3Dsonar_admedia%7C%7C%7B%7D%3Bsonar_admedia%5B%27E62B6743%27%5D%3D%7Bsize%3A3%2Cref%3A%27wfaa.com%27%2Cuid%3A%2715246455031303320585%27%2Ccid%3A%279604%27%2Caaid%3A%277660638269465052685%27%2Cbwa%3A%270.51%27%2Cssp%3A%27pubmatic-ap%27%2Cts%3A1471855679%2Csig%3A%277CrnkL_fNpqVrup6dcLUTn0tY2L_LJeccW8W4BGORrllMP5_krK0Cq77cS5h40aLQfZRGnKP0PqTTfZOKbX74aJ8cOE%2A%27%7D%3B%3C%2Fscript%3E%3C%2Fdiv%3E%3Cscript%20type%3D%22text%2Fjavascript%22%3E%28function%28%29%7Bvar%20s%3Ddocument.createElement%28%27script%27%29%3Bvar%20x%3Ddocument.getElementsByTagName%28%27script%27%29%5B0%5D%3Bs.type%3D%27text%2Fjavascript%27%3Bs.async%3Dtrue%3Bs.src%3D%28%27https%3A%27%3D%3Ddocument.location.protocol%3F%27https%3A%2F%2F%27%3A%27http%3A%2F%2F%27%29%2B%20%27ap-sonar.sociomantic.com%2Fjs%2F2010-07-01%2Fadpan%2Fpubmatic-ap%3F2013-07-23%27%3Bx.parentNode.insertBefore%28s%2Cx%29%3B%7D%29%28%29%3B%3C%2Fscript%3E%0A%3Cscript%20type%3D%22text%2Fjavascript%22%20src%3D%22https%3A%2F%2Fc.betrad.com%2Fsurly.js%3F%3Bad_w%3D728%3Bad_h%3D90%3Bcoid%3D348%3Bnid%3D7875%3Becaid%3D28489%3B%22%3E%3C%2Fscript%3E%3C%2Fspan%3E%20%3C%21--%20PubMatic%20Ad%20Ends%20--%3E",
    "tracking_url": "http%3A%2F%2Faktrack.pubmatic.com%2FAdServer%2FAdDisplayTrackerServlet%3FoperId%3D1%26pubId%3D28489%26siteId%3D134824%26adId%3D575087%26adServerId%3D243%26kefact%3D0.510000%26kaxefact%3D0.510000%26kadNetFrequecy%3D1%26kadwidth%3D728%26kadheight%3D90%26kadsizeid%3D7%26kltstamp%3D1471855679%26indirectAdId%3D0%26adServerOptimizerId%3D2%26ranreq%3D0.21417216721543686%26kpbmtpfact%3D0.510000%26dcId%3D4%26tldId%3D20196051%26passback%3D0%26imprId%3D0F7C5D3E-C385-4410-B859-110744273F56%26oid%3D0F7C5D3E-C385-4410-B859-110744273F56%26ias%3D257%26fbs%3D1%26crID%3D0300258457955680%26campaignId%3D19713%26creativeId%3D0%26pctr%3D0.000000%26wDSPByrId%3D1%26pageURL%3Dhttp%253A%252F%252Fwww.wfaa.com%252F%26lpu%3Djungleerummy.com",
    "width": "728",
    "height": "90"
};
bidDetailsMap["f5683f5a28f9182ad637a02578e9730b"] = {
    "ecpm": 0.0000,
    "creative_tag": "",
    "tracking_url": "",
    "width": "0",
    "height": "0",
    "error": "2"
};
bidDetailsMap["76e9304f35ae2beea28b73312ca442a0"] = {
    "ecpm": 0.0000,
    "creative_tag": "",
    "tracking_url": "",
    "width": "0",
    "height": "0",
    "error": "2"
};
progKeyValueMap["/32805352/tx-dallas-WFAA-B3341/home@728x90:0"] = "bidstatus=3;bid=0.5100;bidid=4bd7f5b68a014e8e3ce9ed51c6206c23;wdeal=";
progKeyValueMap["/32805352/tx-dallas-WFAA-B3341/home@960x66:0"] = "bidstatus=0;bid=0.0000;bidid=f5683f5a28f9182ad637a02578e9730b;wdeal=";
progKeyValueMap["/32805352/tx-dallas-WFAA-B3341/home@970x66:0"] = "bidstatus=0;bid=0.0000;bidid=76e9304f35ae2beea28b73312ca442a0;wdeal=";
if (typeof DM.callBack === 'function') {
    DM.callBack();
}

 

Error Codes

                       

Error CodeDescription
1The slot/adunit passed is unmapped in the PubMatic system
2Missing Mandatory parameter/internal error such as invalid Ids or system error
3The request times out as per the timeout configured for Partner or global timeout
4Partner API Response Error

 

Server to Server Header Bidding Documentation

PubMatic Server-Side Wrapper Tag Overview 

Server to Server Wrapper Tag: Request Body 

Server to Server Wrapper Tag: Response Parameters & Sample 

HTTP Header Parameters 

HTTP Request Parameters 

Attachments

    Outcomes