HTTP Parameters Details (SSP Ad Server)

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

A basic ad request requires the following parameters. The following mandatory and optional parameters can be sent either in a HTTP GET request along with the query string or in a POST request along with post body in a key-value format separated by an ampersand (&).

                                                                                                                                          

Parameter
Mandatory
Description
operId
Yes
Identifier (ID) of the operation. Possible values are:
  • 1 - For HTML response
  • 3 - For JavaScript response
  • 102 - For JSON response
  • 201 - JSON response for mobile ad serving
Note:
We recommend that you use operId=201 for mobile inventory.

 

Please check the rs parameter's values which is associated with this parameter to retrieve JSON and JSONP response format for operId=201.
pubId
Yes
ID of the publisher. This value can be obtained from the pubId parameter in the PubMatic ad tag.
siteId
Yes
ID of the publisher's Web site. A publisher can have multiple sites. This value can be obtained from the siteId parameter in the PubMatic ad tag.
adId
Yes
ID of the ad's placement. A site can have multiple ad placements or positions which have the same or different ad sizes. adId is the unique identifier for such an ad placement and this value can be obtained from the adId parameter in the PubMatic ad tag.
adtype
Yes
Type of ad. This parameter is mandatory for native ad serving. Possible options are:
  • 1 - Text only ads
  • 2 - Image only ads
  • 3 - Text and Image ads
  • 4 - Ad made up of link units
  • 5 - HTML ads
  • 6 - Flash ads
  • 7 - Text and Flash ads
  • 8 - Text and Image and Flash ads
  • 9 - Text and Image and Flash and HTML ads
  • 10 - Text and HTML ads
  • 11 - Text and Image and Rich Media ads
  • 12 - Native ads
  • 13 - Video ads
  • 14 - Audio impression through VAST
kadheight
Yes
Height of the ad. This value can be obtained from the kadheight parameter from the PubMatic ad tag.
Note: For native ad format, sizes for native assets (not for ad) are provided; hence this is an optional parameter.
kadwidth
Yes
Width of the ad. This value can be obtained from the kadwidth parameter from the PubMatic ad tag.
Note: For native ad format, sizes for native assets (not for ad) are provided; hence this is an optional parameter.
pageURL
Yes
URL of the page for which the ad is requested.
Note:
This parameter's value should be URI encoded.

 

Since there is no page URL in the case of Mobile Application, you can set an empty string "" in this parameter.
kltstamp
Yes
Timestamp (in the YYYY-MM-DD HH:MM:SS format) of the user or browser at which the ad request is generated.
Note: This parameter's value should be URI encoded.
ranreq
Yes
A unique random number of data type double ranging between 0 to 1. This is required to avoid URL caching from the browser. For example, ranreq=0.6148488499487118
timezone
Yes
Time zone of the user or browser which is making an ad request. It is an offset [+/-]hh.mm.
Note: This parameter's value should be URI encoded.
screenResolution
Yes
Resolution of the screen in the WidthxHeight format.
Note: If you are unable to determine the screen resolution, you can set the default value as -1x-1 in this parameter.
adPosition
Yes
Position of the ad to be served, that is, the (Top x Left) position of the ad container.
Note: If you are unable to determine the ad position, you can set the default value as -1x-1 in this parameter.
inIframe
Yes
Indicates whether the ad is served in an iFrame or not. Possible values are:
  • 0 - False
  • 1 - True.
Note: If you are unable to determine it, you can set the default value as 1 in this parameter.
adVisibility
Yes
Fold placement of the ad to be served. Possible values are:
  • 0 - Visibility cannot be determined
  • 1 - Above the fold
  • 2 - Below the fold.
  • 3 - Partially above the fold
Note: If you are unable to determine it, you can set the default value as 0 in this parameter.
iabcat
No
List of IAB content categories for the overall site/application. Refer the "Table 6.1 Content Categories" in the Open RTB 2.1 / 2.2 specifications document.
If the site/application falls under multiple IAB categories, you can send categories separated by comma, and the string should be URL encoded.
For example, iabcat=IAB1%2CIAB-5%2CIAB1-6
dnt
No
Indicates whether the user has opted out of the publisher or not, or whether HTTP_DNT is set or not. Possible values are:
  • 0 - Either the user has not opted out of the publisher or HTTP_DNT is not set.
  • 1 - Either the user has opted out of the publisher or HTTP_DNT is set; in this case, PubMatic will not target such users.
Note: The default value for this parameter is 0.
coppa
No
Indicates whether the visitor is COPPA-specific or not. For COPPA (Children's Online Privacy Protection Act) compliance, if the visitor's age is below 13, then such visitors should not be served targeted ads.
Possible options are:
  • 0 - Indicates that the visitor is not COPPA-specific and can be served targeted ads.
  • 1 - Indicates that the visitor is COPPA-specific and should be served only COPPA-compliant ads.
The United States Federal Trade Commission has written a comprehensive FAQ on complying with COPPA at http://business.ftc.gov/documents/Complying-with-COPPA-Frequently-Asked-Questions.
awt
No
Indicates whether the tracking URL has been wrapped or not in the creative tag.
Possible options are:
  • 0 - Indicates that the tracking URL is sent separately in the response JSON as tracking_url. In this case, the tracking_url field is absent in the JSON response.
  • 1 - Indicates that the tracking_url value is wrapped in an Iframe and appended to the creative_tag.
  • 2 - Indicates that the tracking_url value is wrapped in a JS tag and appended to the creative_tag.
Note:
  • If the awt parameter is absent in the bid request URL, then it is same as awt=0 mentioned above.
  • Its default value is 0.
pmZoneId
No
This parameter is used to pass a zone ID for reporting.
kadpageurl
No
Indicates the actual page URL.
Notes:
1. This parameter is applicable only in case of Publisher Aggregators.
2. For Publisher Aggregators, this parameter becomes mandatory, if the associated site is enabled for white-listing purpose.
 
sitecode
No
Indicates the property code for the domain/application as shared by publisher in the offline mode.
Notes:
1. This parameter is applicable only in case of Publisher Aggregators.
2. For Publisher Aggregators, this parameter becomes mandatory, if the associated site is enabled for white-listing purpose and platform for the site is either "Mobile App Android" or "Mobile App iOS."
3. If both "kadpageurl" and "sitecode" parameters are present, then "sitecode" parameter will get preference in the associated impressions.
 
instlNoProvides interstitial ad type information for the request. Publisher is advised to send this information in ad-request so that this information can be passed to the demand partners.
secNoFlag to indicate, if the impression requires secure HTTPS URL creative assets and markup, where 0 = non-secure, 1 = secure. If omitted, the secure state is unknown, but non-secure HTTP support can be assumed.
dctrNo

Allows key-value pair information to be passed to the SSP platform.

Multiple values and syntax are allowed as follows: dctr=ENCODED<key1=V1,V2,V3|key2=v1|key3=v3,v5>

Example:

dctr=company%3Dpubmatic%7Cplace%3Dpune%2Cbanglore

contentobjNo

valid json string wrapped in { }. The complete JSON will be URL encoded
For example: {"context": "6","qagmediarating": 1,"embeddable": 0,"language": "en"}

Note: This should be URL encoded.

Max Size = 4096

pmpNo

This will provide publisher Private Market Places functionality. pmp should contain encoded json of deals - deal object array.
deal object contains id - String value. A unique identifier for the direct deal.
For example: "deals":[ {"id":"A97736253"}, {"id":"A97736786"}]
Maximum 50 deals are supported in array. Maximum length of deal.id is 64.
For example, input: pmp=%22deals%22%3A%5B%0D%0A%7B%22id%22%3A%22A97736253%22%7D%2C%0D%0A
%7B%22id%22%3A%22A97736786%22%7D%0D%0A%5D

 

Sample ad request:

http://showads1065.pubmatic.com/AdServer/AdServerServlet?pubId=31400&siteId=36255&adId=
313852&kadwidth=1&kadheight=1&SAVersion=2&js=1&kdntuid=1&pageURL=http%3A%2F%2Fthebiglead.com
%2F&inIframe=1&kadpageurl=INSERT_ENCODED_PAGEURL_HERE&operId=3&adtype=12&kltstamp=2015-7-
7%2016%3A56%3A18&timezone=5.5&screenResolution=1366x768&ranreq=0.09192118114654302&
pmUniAdId=0&adVisibility=2&adPosition=-408x174&instl=1

 

The optional parameters include the following:

Attachments

    Outcomes