- Created by Phil Ayoub, last modified by Janessa Johnson on Oct 09, 2018
See Real Time Bidding API Components for more information on the Real Time Bidding API
API Details
API calls happen over a REST-like Interface using the HTTP GET or POST request and response mechanism.
Bid requests will be sent to Demand Partner as URL parameters and POST data. The data that a Demand Partner elects to receive in the request will dictate if POST data will be used.
Sample API request format with details of the impression: http://pubmatic.adapters.demandpartner.com/bid? &requestId=<ID_of_the_request> &ip=<user_IP_Address> &uid=<PubMaticäó»s_anonymized_user_ID> &timezone=<time_zone_offset> &adHeight=<height_of_the_ad_unit> &adWidth=<width_of_the_ad_unit> &pubId=<ID_of_the_Publisher_on_PubMatic> &siteId=<ID_of_the_Site_on_PubMatic> &adId=<ID_of_the_ad_slot_on_PubMatic> &adPosition=<position_of_the_ad_unit> &uFoldPos=<Publisher-defined_fold_position> &sFoldPos=<PubMatic_system_determined_fold_position> &inIframe=<flag_denoting_impression_is_coming_from_inside_iframe> &screenResolution=<resolution_of_the_useräó»s_display> &language=<language_setting_of_the_user_agent> &browser=<user_agent> &cookie=<Demand_Partneräó»s_user_sync_assigned_user_ID> &refurl=<URL_of_the_referring_page> &pageurl=<URL_of_the_page> &siteurl=<base_URL_of_the_site> &optout=<Opt_out_status_of_user> &vertical=<Site_vertical> &iab_verticals=<iab_verticals> coppa=<COPPA_status> &platform=<Type_of_platform>
Example: http://pubmatic.demandpartner.com/ bid? requestId=FCB4D38D-AC3D-4E84-B70E-5B629DDE7DF9 &adWidth=320&adHeight=50&uid=&siteurl=http%3A%2F%2Fkomli.com&pageurl=www.test.com&macs =152&ip=172.16.1.217&adTagType=Iframe&bidCurrency=USD&adId=30351&pubId=5007&siteId=5008 &inIframe=1&uFoldPos=2&sFoldPos=0&freq=0&timezone=5.5&category=0%2C0%2C0&screenResolution =1366x768&adPosition=0x0&language=en-US%2Cen%3Bq%3D0.5&browser=Mozilla%2F5.0%20%28iPhone %3B%20CPU%20iPhone%20OS%208_0%20like%20Mac%20OS%20X%29%20AppleWebKit%2F600.1.4%20%28KHTML %2C%20like%20Gecko%29%20Version%2F8.0%20Mobile%2F12A365%20Safari%2F600.1.4&instl=1& platform=2&iab_verticals=IAB1%2CIAB1-1%2CIAB2-1
Sample API Response Format
Single-Bid Format
text/plain id=<transaction ID> bid=<bid price> buyer=<buyer ID number from the Demand Partneräó»s buyer code store> creativeId=<ID> creativeJSURL=<JavaScript creative URL> creativeHTMLURL=<Html Creative URL> creativeTAG=<Javascript Tag> landingPageURL=<URL of the landing page äóń for creative control> requestId=<ID of the request>
Examples
Normal bid
id=8870961626866372241
bid=0.15
buyer=234
creativeId= c-1234-36759
creativeJSURL=http://ad.adnetwork.com/server/ads.js?aid=24808139&click=${PUBMATIC_CLICK_TRACKING_URL}&sp=${PUBMATIC_SECOND_PRICE}
landingPageURL=http://campaign.advertiser.com/12345
requestId=067EADA2-D822-4DDD-B34D-2EFCD06A127F
bidCurrency=USD
campaignId=campaign123
iUrl=http://www.pubmatic.com/sampleimage
creativeAttribute=1
rmt=pr
dnbr=5
Zero bid
requestId=067EADA2-D822-4DDD-B34D-2EFCD06A127F bid=0
Multi-Bid Format
{
"bidCurrency" : "USD",
"bids" :[
{
"id": "8870961626866372241",
"bid": 0.15,
"buyer" : 234,
"creativeId" : "c-1234-36759",
"creativeJSURL":"http://ad.adnetwork.com/server/ads.js?aid=24808139&click=${PUBMATIC_CLICK_TRACKING_URL}&sp=${PUBMATIC_SECOND_PRICE} ",
"landingPageURL" : "http://campaign.advertiser.com/12345",
"requestId" : "067EADA2-D822-4DDD-B34D-2EFCD06A127F",
"campaignId" : "campaign123",
"iUrl" : "http://www.pubmatic.com/sampleimage",
"creativeAttribute":5,
"rmt":"pr"
},
{
"id": "8870961626866372241",
...
"requestId" : "067EADA2-D822-4DDD-B34D-2EFCD06A127F"
}
],
"dnbr":6
}
Examples
Normal bid
{
"bidCurrency" : "JPY",
"bids" : [
{
"requestId": "10",
"id": "1",
"bid": 50.1,
"creativeId" : "c-1234-36759",
"creativeJSURL": "http://64.106.163.182/creative.php?width=60&height=60",
"landingPageURL": "pubmatic.com",
"dealId": "BROSIM002"
},
{
"requestId": "10",
"id": "2",
"bid": 75.1,
"creativeId" : "c-1234-36759",
"creativeJSURL": "http://64.106.163.182/creative.php?width=40&height=40",
"landingPageURL": "pubmatic.com",
"dealId": "BROSIM003"
},
{
"requestId": "10",
"id": "3",
"bid": 100.1,
"creativeId" : "c-1234-36759",
"creativeJSURL": "http://64.106.163.182/creative.php?width=20&height=20",
"landingPageURL": "pubmatic.com",
"dealId": "BROSIM004"
}
]
}
Zero bid
{
"bids" :[
{
"bid": 0.0,
"requestId" : "067EADA2-D822-4DDD-B34D-2EFCD06A127F"
}
]
}
GDPR Parameters
The following are GDPR-specific parameters.
Example
{ ...
"gdpr": 1,
"consent": "BONihAGONihAGABABAENAQ____AArABAAAA"
…
}
Example of Google EB Request
{ ...
"gdpr": 1,
"consented_providers": [123, 456]
…
}
GDPR Parameters Format
| Parameter | Mandatory | Multi-Valued | Description |
|---|---|---|---|
| gdpr | No | Integer | Possible values: 0 or 1 to indicate whether or not the impression is GDPR-regulated. |
| consent | No | String | If the Regs.ext.gdpr flag is 1 then this string gives consent information of various vendors. |
| consented_providers | No | Array of Integers | Set of IDs corresponding to providers for whom the publisher has told Google that its EEA (European Economic Area) users have consented to the use of their personal data for ad personalization. Note: Only applicable to Google EB requests. |
API Request Parameters
From PubMatic to Ad Network in HTTP URL parameters.
| Parameter | Mandatory | Multi-Valued | Description |
|---|---|---|---|
| requestId | Yes | No | A unique request ID is generated by PubMatic. It should be returned back in response for correlating and verification purpose. Limited to 40 bytes. Example: 993DCB9F-9203-488C-818A-79FF231C921B |
| uid | No | No | Unique ID is generated by PubMatic for the user Limited to 40 bytes Example: D2799BE3-0981-4956-838C-199C4C9263AB |
| ip | No | No | The public IP address of the user. Limited to 16 bytes. Example: 24.1.0.5 |
| xff | No | No | X-Forwarded-For HTTP header as received by PubMatic |
| adWidth | Yes | No | Width of the ad unit. Limited to 4 bytes. Example: 728 |
| adHeight | Yes | No | Height of the ad unit. Limited to 4 bytes. Example: 90 |
| pubId | No | No | ID of Publisher as identified by PubMatic. Example:12345 |
| siteId | No | No | ID of Site as identified by PubMatic. Example:123456 |
| adId | No | No | ID of Ad Tag as identified by PubMatic. Example:1234567 |
| adTagType | No | No | JavaScript or Iframe serving based on the ad tag selection made by the publisher in PubMatic. Limited to 12 bytes. Supported values: JavaScript, Iframe |
| adPosition | No | No | Absolute Position of the ad in the page. Represented in LeftxTop. Limited to 10 bytes. If we are unable to find the position, value would be -1x-1. Example: 400x200 |
| uFoldPos | No | No | User defined Fold position of the ad slot.
|
| sFoldPos | No | No | System detected Fold position of the ad slot.
|
| freq | No | No | The number of times the user was delivered an ad from a Demand Partner in the last 24 hours, starting from the time when the user first saw the ad from this Demand Partner. This would be passed only if there is a frequency cap set. Limited to 4 bytes. Example: 2 |
| bidCurrency | Yes | No | Currency of the bid/deal floor values being passed in the RTB request. |
| timezone | No | No | The local time zone of the user browsing the page. Time zone is represented in hourly offset relative to GMT. Limited to 6 bytes. Example: 5.5 (represents IST) Example: -8 (represents PST) |
| inIframe | No | No | Flag identifying whether the Impression is coming from inside an Iframe or not. Valid values: 0/1. 0-not in Iframe, 1-in Iframe |
| inMultipleNestedIframes | No | No | Flag identifying whether the Impression is coming from more than one nested Iframes or not. Valid values: 0/1. 0-not in nested Iframe, 1-in nested Iframe |
| screenResolution | No | No | Resolution of the user screen. Represented in widthxheight. Limited to 10 bytes. Example: 1024x768 |
| language | No | No | Language settings of the user. Details received through HTTP Accept-Language header. URL encoded string. Limited to 64 bytes. Example: en-us,en;q=0.5 |
| browser | No | No | Browser details of the user. Details received through HTTP User-Agent header. URL encoded string. Limited to 128 bytes. Example: mozilla/5.0%20(Windows;%20U;%20Windows%20NT%205.1;%20en-US;%20rv:1.8.1.16)%20Gecko/20080702%20Firefox/2.0.0.16%20(.NET%20CLR%203.5.30729) |
| cookie | No | No | Any cookie parameters that the Demand Partner has set via PubMatic (via PubMaticäó»s user sync service and the piggyback cookie mechanism). |
| pageurl | Yes | No | The URL of the page that contains the impression (not an Iframe). URL encoded string. Limited to 512 bytes. |
| siteurl | Yes | No | The base URL of the site as configured in PubMatic. URL encoded string. Limited to 512 bytes. |
| refurl | No | No | Referring URL, if the referring URL was retrieved. |
| pmpEnable | No | No | If PMP has been enabled for a site, the flag is set to 1. |
| secure | No | No | If the page from which ad request originates is äóěhttpsäóť, then the value is 1. It is expected that the partners will respond with an äóěhttpsäóť creative URL. The bid will not be considered for auction if creativeURL in RTB response is äóěhttpäóť and secure flag is 1. |
| optout | No | No | If the user has opted out of the PubMatic system, this parameter will get passed with value as 1; otherwise its value will be 0. |
| vertical | No | No | ID of the content category that PubMatic has assigned to the publisheräó»s Web site. |
| coppa | Yes | No | The United States Federal Trade Commission has changed the compliance rules for the Childrenäó»s Online Privacy Protection Act (äóěCOPPAäóť), effective July 1, 2013. The proposal effects websites and applications that have been identified as: (1) directed to users under 13 years of age; or (2) collecting information from users actually known to be under 13 (collectively äóěChildrenäó»s Sitesäóť). |
| platform | Yes | No | Type of platform on which the impression will be displayed. This parameter indicates the primary platform of the property. Possible values are:
|
API Response Parameters
From Ad Network to PubMatic in HTTP response.
| Parameter | Mandatory | Multi-Valued | Description |
|---|---|---|---|
| id | Yes | No | Ad Networkäó»s ID for this bid transaction, used for logging and can be passed as a parameter in the creative call, which helps the Demand Partner to correlate the bid value with the impression. Limited to 128 bytes. |
| bid | Yes | No | Demand Partneräó»s bid value (eCPM). The bid should be in an approved bidCurrency and is a decimal number (float value) with maximum 4 digits allowed after the decimal point.Example:1.5024 The bid value has to be 0 if not interested in bidding. |
| ebid | No | No | Demand Partneräó»s bid value (eCPM), encrypted using the encryption & authentication keys chosen by Demand Partner. The bid should be encrypted to a string of 38 bytes using hmac-sha2 algorithm conveyed to Demand Partner. This value when decrypted, will be considered to be specified in an approved bid currency and is a decimal number (float value). This is optional & may be used when demand partners chooses to send their bid values encrypted. Please see section on äóěBid Value / Second Price Encryptionäóť for more details. |
| buyer | Yes | No | ID of Buyer (Trading Desk/Agency) on DSP end. Reference list of Buyer ID äóń details mapping can be done offline. Limited to 16 Bytes. Example: 32 |
| bidCurrency | Yes | No | Currency of the bid or ebid value. (Default value: USD) |
| creativeJSURL | No | No | URL for returning Java Script code for serving the creative.
|
| creativeHTMLURL | No | No | URL for returning Html code for serving the creative. This URL should contain variable (MACRO) for replacing with Click Tracking URL during the ad call. Limited to 2048 bytes.
|
| creativeTAG | No | No | JavaScript/HTML code snippet to serve creative directly on browser. The JS code may contain variable (MACRO) for replacing Second Price and Click tracking URL during the ad call. Ad tag size must not exceed 8192 bytes. |
| creativeId | Yes | No | Unique Identifier of the creative. This can be used as reference to report creative violations and by publishers for creative control. Limited to 256 bytes. Example: c-1234-36759 |
| landingPageURL | Yes | No | Landing Page URL of the Creative to be used for Creative Control äóń URL Block List. Limited to 2048 bytes. Note: This parameter is mandatory if landingPageTLD is not specified. If both äóělandingPageURLäóť and äóělandingPageTLDäóť are absent in bid response, the bid will not be considered for auction. |
| landingPageTLD/Adomain | Yes | No | The domain name of the advertiser whose creative will be served in the ad tag (for example www.advertiser.com or www.advertiser.co.uk). This is used to enforce advertiser block lists. |
| creativeAttribute | Yes for RTB Bid Response Transparency | No | Attributes of the creative. If the creative to be served is rich media, then it is mandatory to send this parameter in the response. For more details, refer the Creative Attributes table in the reference section of this document. Example: 1 Note: This value should be sent as an integer for a multi-bid response. |
| rmt | No | No | Rich media technology of the creative. For more details, refer the Rich Media Technologies table in the reference section of this document. Example: pr Note: This value should be sent as a string for a multi-bid response. |
| requestId | Yes | No | Request ID sent by PubMatic in the request for correlation and verification of the bid. |
| campaignI | Yes for RTB Bid Response Transparency | No | Campaign ID or similar that appears within the ad markup. |
| iURL | Yes for RTB Bid Response Transparency | No | Sample Image URL (without cache busting) for content checking. |
| dnbr | No | No | Reason for not bidding on a Private Marketplace deal’s impression. In such cases, Demand Partners are requested to send this value in the response. For more details, refer the Deal - No Bid Reason table in the reference section of this document. Example: 5 |
Ad Serving when the Demand Partner Wins the Auction
A demand partner can specify a creativeHTMLURL or a creativeJSURL in the bid response to be called to draw down the winning ad tag code.
Specifying HTML URL in response to the bidding API call
Demand Partner can specify the URL of an HTML file to display the ad as the output of the bidding call request made to them along with transaction ID and click tracking URL parameters.
Example
http://demand.partner.com//728_90tag.html?txID=123456&clickTrackingURL=${PUBMATIC_CLICK_TRACKING_URL}
When the Demand Partner wins the auction, PubMatic will then display the ad by returning the HTML code containing an Iframe with the height and width of the ad and the source (src) parameter set to the HTML URL returned by the Demand Partner.
Example
<iframewidth="728"scrolling="no"height="90"frameborder="0"name="iframe0"allowtransparency="true"marginheight="0"marginwidth="0"vspace="0"hspace="0"src="http://demand.partner.com/728_90tag.html? txID =123456&clickTrackingURL=${PUBMATIC_CLICK_TRACKING_URL} "></iframe>
Specifying JavaScript URL in response to the bidding API call
Demand Partner can specify URL of a JavaScript code to display the ad as the output of the bidding call request made to them along with transaction ID and click tracking URL parameters.
Example
http://demand.partner.com/somePublisher/generatetag?size=728x90&txID =123456&clickTrackingURL=${pubmaticURLfortracking}
When the Demand Partner wins the auction, PubMatic will then display the ad by returning the HTML code containing the script tag with the source (src) parameter set to the JavaScript URL returned by the Demand Partner.
Example
<script type="text/javascript" src="http://demand.partner.com/generatetag?size=728x90&txID =123456&clickTrackingURL=${pubmaticURLfortracking}></script>
Specifying Creative-Tag in response to the bidding API call
Demand Partner can send creative-tag to display the ad as the output of the bidding call request made to them along with PubMatic macro variables like second_price, click_tracking_url etc.
Example
<script> var tm_params = {}; tm_params.clickUrl = "%%CLICK_URL%%http://demand.partner.com/assets/1x1.png"; tm_params.sourceUrl = "%%SOMEMACRO%%"; </script> <script type="text/javascript" src="http://demand.partner.com/placement.js?id=hArg31uRIFWe0rRaWIeZ&rand=[RANDOM]&pmsecondprice=${PUBMATIC_SECOND_PRICE}&clickTrackingURL=${PUBMATIC_CLICK_TRACKING_URL}"></script>
When the Demand Partner wins the auction, PubMatic will then display the ad by returning the creative-tag to browser. PubMatic Macro variables in the tag will be replaced with corresponding values; otherwise the code will not be modified.
Example
<script> var tm_params = { } ; tm_params.clickUrl = "%%CLICK_URL%%http://demand.partner.com/assets/1x1.png" ; tm_params.sourceUrl = "%%SOMEMACRO%%" ; < /script> <script type= "text/javascript" src= "http://demand.partner.com/placement.js?id=hArg31uRIFWe0rRaWIeZ&rand=[RANDOM]&pmsecondprice=2.107&clickTrackingURL=http://track.pubmatic.com" > < /script>
Bid Value / Second Price Encryption
Bid Value Encryption
Demand Partner can opt to send bid value in RTB response to PubMatic in encrypted form. Below given section (“Encryption/Decryption Algorithm”) describes the algorithm in detail.
The process of opting in for sending encrypted bid price in RTB response is as follows:
- An encryption key and an integrity key specified by either Demand Partner or by PubMatic is shared with other party. This key is entered in PubMatic’s system. This is done offline (via email).
- Demand Partner then sends encrypted values as challenge to PubMatic. PubMatic uses its algorithm to decrypt these values to verify interoperability of algorithm implementations. This is also done offline (via email).
- After successful completion of step 2, rtb-support team will do local sandbox testing to ensure correctness across RTB request-response cycle.
- Once confirmed, Demand Partner can send encrypted bid values in live RTB responses.
Second Price Encryption
Demand Partner can opt to receive second price value (substituted in creative URL/ Tag) in encrypted form. Below given section (“Encryption/Decryption Algorithm”) describes the algorithm in detail.
- The process of opting in for encrypted second price in creative URL/Tag is as follows:
- An encryption key and an integrity key specified by either Demand Partner or by PubMatic are shared with other party. This key is entered in PubMatic’s system. This is done offline (via email).
PubMatic then sends encrypted values as challenge to Demand Partner. Demand Partner uses its algorithm to decrypt these values to verify interoperability of algorithm implementations. This is also done offline (via email). - After successful completion of step 2, RTB-support team will do local sandbox testing to ensure correctness across RTB request-response and Demand Partner creative serving cycle.
Once confirmed, Demand Partner can get encrypted second price values in production environment.
Encryption/Decryption Algorithm
Algorithm for Encryption
- The algorithm we use is symmetric key algorithm. It uses encryption key for encrypting & decrypting the values and integrity key for authenticating the received data.
- Generate a 16 byte string called initial vector, first 8 byte of which contains timestamp & remaining 8 bytes contain random number. Represent 8 byte double values as 8 byte plain_text.
- encoded_text(8 bytes) = plain_text(8 bytes) ^ HMAC-SHA256(initialization_vector(16 bytes), encryption key).
- signature(4 bytes) = HMAC-SHA256(initialization_vector(16 bytes) + plain_text(8 bytes), integrity key).
- final_text(38 bytes)= convert_into_web_safe_base64 _string[initialization_vector(16 bytes) + encoded_text(8 bytes) + signature(4 bytes) ].
- This final_text is then sent as final encrypted value. Web_safe_base64 doesn’t have padding and replaces “+” by “-” and “/” by “_”.
Algorithm for Decryption
- encrypted_text(28 bytes) = decode_web_safe_base64_string(final_text(38 bytes)).
- Segregate encrypted_text (28 bytes) into initialization_vector(16 bytes), encoded_text(8 bytes) & signature(4 bytes).
- plain_text(8 bytes) = encoded_text(8 bytes) ^ HMAC-SHA256(initialization_vector(16 bytes), encryption_key).
- Integrity_hash(4 bytes) = HMAC-SHA256(initialization_vector(16 bytes) + plain_text(8 bytes), integrity_key).
- Verify integrity of received data by comparing integrity_hash & signature.
Reference
http://docs.pulsepoint.com/display/RTB/Real-Time+Bidding+API
API - Inline List Sharing Mechanism
Demand Partners can opt to receive optional data parameters in the bid request. Due to the size of some of this data, PubMatic will send these requests as an HTTP POST with the additional data in the POST body formatted as JSON.
Only available data will be added into the JSON Structure. If there is no POST data to be sent, the resulting bid request will be sent as a GET.