HTTP Parameters Details (SSP Ad Server)

The table below provides parameter details for requests to SSP Ad Server.


Before using PubMatic APIs, first generate the API Access Token. For more information, see Getting Started with PubMatic APIs.

A basic ad request requires the following parameters. Send the following mandatory and optional parameters 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 ( & ).

ParameterTypeMandatoryDescription
operIdIntegerYes

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.

pubIdIntegerYesID of the publisher. This value can be obtained from the  pubId  parameter in the PubMatic ad tag.
siteIdIntegerYesID 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.
adIdIntegerYesID 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.
adtypeIntegerYes

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

kadheightIntegerYes

Height of the ad. Obtain this value from the kadheight  attribute of the PubMatic ad tag.
Note: For native ad format, sizes for native assets (not for ad) are provided; hence this is an optional parameter.

kadwidthIntegerYes

Width of the ad. Obtain this value from the kadwidth  attribute of the PubMatic ad tag.
Note: For native ad format, sizes for native assets (not for ad) are provided; hence this is an optional parameter.

pageURLStringYes

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.
kltstampTimestampYes

Timestamp (use 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.

ranreqFloatYesA 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
timezoneStringYes

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.

screenResolutionStringYes

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.

adPositionStringYes

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.

inIframeBooleanYes

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.
adVisibilityIntegerYes

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.
app_site_keywordsStringNo

A comma-separated list of keywords about the app/site.
  • When this parameter is present, keywords parameter will be ignored.
  • Maximum length supported: 1024 ASCII Characters (after URL decode). Strings greater than this length will be truncated and used/passed-further.
iabcatArrayNoList of IAB content categories for the overall site/application. Refer the "Table 6.1 Content Categories" in the OpenRTB 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
dntBooleanNo

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.
coppaBooleanNo

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.
awtIntegerNo

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".

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.

pmZoneIdIntegerNoUse this parameter to pass a zone ID for reporting.
pchainStringNoPayment ID chain string containing embedded syntax described in the TAG Payment ID Protocol v1.0. Learn more at, TAG Certified Against Fraud Guidelines.
kadpageurlStringYes

Indicates the actual page URL.

Note:
This parameter is mandatory if the associated site is enabled for allowlisting purposes.

sitecodeIntegerSee notes.

Indicates the property code for the domain/application as shared by publisher in the offline mode.

Notes:

  1. This parameter is mandatory and applicable only for Publisher Aggregators.
  2. For Publisher Aggregators, this parameter becomes mandatory if the associated site is enabled for white-listing purposes, 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 gets preference in the associated impressions.
instlObjectNoProvides 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.
secBooleanNoFlag 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.
dctrArrayNo

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

contentobjObjectNo

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

pmpObjectNo

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

multisizeArrayNo

This parameter is used to send multiple requests for different sizes. kadheight and kadwidth parameter are treated as primary sizes for the ad tag. Maximum 5 ad sizes are supported in adserver including primary sizes.

The multisize parameter doesn't work for: 

defaulted ad-requests,

video requests,

native requests.

Sizes should be sent as comma separated values.

eg: multisize=300x100%2C250x250%2C100x100

gdpr
No

Possible values = 0 or 1 to indicate whether or not the impression is GDPR-regulated.

gdpr_consentBooleanNo

If the above flag is 1 then this string gives consent information of various vendors.

Example:

gdpr=1&gdpr_consent=BONihAGONihAGABABAENAQ____AArABAAAA

us_privacyStringNo

ccpa us_privacy string, which contains user optout status.

Example = us_privacy=1YNY

cplistArrayNo

Comma-separated list 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; Applicable only to Google EB requests.

Example: gdpr= 1&cplist=221,224

schainArrayYes

A serialized Supply Chain Object that takes an array of comma-delimited (,), or bang-delimited (!), values in a pre-determined sequence. Each delimited string value must be URL encoded.

Do not encode the entire array…

Encode only each individual, delimited value.

For example: 

schain=1.0,1!exchange1.com,1234%21abcd,1,bid-request-1,publisher%2c%20Inc.,publisher.com

To learn more see, Supply Chain For Non-OpenRTB Requests.

useripv4StringNoIpv4 address of device from which the ad request is generated.
userip6StringNoIpv6 address of device from which the ad request is generated.
useragentStringNoIndicates the name of the browser. To be sent in plain text. Do not encode the UA string.

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‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍‍$&schain=1.0,1!exchange1.com,
1234%21abcd,1,bid-request-1,publisher%2c%20Inc.,publisher.com

Optional parameters

AdTruth-specific Parameters

Formatting Parameters

Mobile-specific Parameters

RTB-only Floor Parameters

Response Format Parameters

User Information Parameters

Video-specific Parameters

Rich Media Parameters

Native Parameters

oRTB content fields