PubMatic supports Ad Serving integration using OpenRTB 2.3, as well as a proprietary API. This document covers the OpenRTB Ad Serving integration.

Objects and Parameters Supported

Supported objects and parameters are listed in the following table, with mandatory/optional indicators. Requests that do not contain mandatory objects and parameters will be considered invalid. 

Object: BidRequest

Attribute Type Description Supported Mandatory
id String Unique ID of the bid request, provided by the exchange. Yes Yes
imp Object Array Array of impression objects representing the impressions offered. At least 1 impression object is required. Yes Yes
site Object Details via a site object about the publisher’s website. Yes No
device Object

Details via a device object about the user’s device to which the impression will be delivered.

Yes Yes
user Object

Details via a user object about the human user of the device; the advertising audience.

Yes No
app Object Details via an App object about the publisher’s app (i.e., non-browser applications). Only applicable and recommended for apps. Yes No
at Integer

Default=2 

  • 1= publisher first price auction
  • 2= publisher second price auction
Yes Yes
cur String Array Array of allowed currencies for bids on this bid request using ISO-4217 alpha codes. Not supported. Imp[0].bidfloorcur will be considered for all impressions of the request No
bcat String Array Blocked advertiser categories using the IAB content categories. Yes No
badv String Array Block list of advertisers by their domains (e.g., “ford.com”). Yes No
regs Object A Regs object that specifies any industry, legal, or governmental regulations in force for this request. Yes No
ifa String ID sanctioned for advertiser use in the clear (i.e., not hashed). Yes No

Object: Imp

Note: Each impression object can contain any one of video/native/banner object otherwise it will be treated as invalid impression.

Attribute Type Description Supported Mandatory
id String A unique identifier for this impression within the context of the bid request (typically, starts with 1 and increments). Yes Yes
tagid String

Identifier for specific ad placement or ad tag that was used to initiate the auction. 
Note:

  • This can be also use as PubMatic ad placement id or ad id. In this case mapping of publisher ad id to PubMatic ad id needs to be maintained by the publisher.
  • Publisher needs to send PubMatid adid here.
Yes No
banner Object A banner object is required if this impression is offered as a banner ad opportunity. Yes Yes
native Object A Native object; required if this impression is offered as a native ad opportunity Yes No
video Object A Video object required if this impression is offered as a video ad opportunity. Yes No
instl Integer 1 = the ad is interstitial or full screen, 0 = not interstitial. Yes No
bidfloor Float

**Highly Recommended**

Minimum bid for this impression expressed in CPM.

Yes Highly Recommended
bidfloorcur  String Currency specified using ISO-4217 alpha codes.

Imp[0].bidfloorcur will be considered for all impressions of the request.

If not specified – default currency USD will be used.

No

iframebuster

String Array Array of exchange-specific names of supported iframe busters Yes No
secure Integer Flag 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. Yes No

Imp Extension Object

Attribute Type Description Supported Mandatory
pmZoneId String This parameter is used to pass zone ID for reporting. Yes No

Object: Banner

Attribute Type Description Supported Mandatory
w Integer Width of the impression in pixels. Yes Yes
h Integer Height of the impression in pixels. Yes Yes
battr Integer Array Blocked creative attributes. Yes No
pos Integer Ad position on screen. Yes No
topframe Integer Indicates if the banner is in the top frame as opposed to an iframe, where 0 = no, 1 = yes. Yes No
expdir Integer Array Directions in which the banner may expand. Yes No

Object: Video

Attribute Type Description Supported Mandatory
protocol (from video object) Not Supp

Video Bid Response protocol. VAST 1.0, VAST 2.0, VAST 3.0, etc. 

No No
protocols Integer Array of supported video bid response protocols. Refer to List 5.8 in http://www.iab.net/media/file/OpenRTBAPISpecificationVersion2_2.pdf. At least one supported protocol must be specified in either the protocols attribute. Yes No
mimes String Array Content MIME types supported for media files. Common video MIME types may include “video/x-flv" and "video/mp4," while "application/x-shockwave-flash" typically applies to VPAID creatives. Yes No
linearity Integer Indicates if the impression is linear or nonlinear. 1=Linear/In-Stream and 2=Non-Linear/Overlay. Yes No
minduration Integer Minimum video ad duration in seconds Yes No
maxduration Integer Maximum video ad duration in seconds. Protocol Video bid response protocols supported. (See Table 6.7 in http://www.iab.net/media/file/OpenRTBAPISpecificationVersion2_2.pdf Yes No
api Integer Array API frameworks supported (See Table 6.4 in http://www.iab.net/media/file/OpenRTBAPISpecificationVersion2_2.pdf) Yes No
w Integer Width of the video player in pixels. Yes No
h Integer Height of the video player in pixels. Yes No
startdelay Integer Indicates the start delay in seconds for pre-roll, mid-roll, or
post-roll ad placements. 
Yes No
maxbitrate Integer Maximum bit rate in Kbps. Yes No
playbackmethod Integer Array Defines whether inventory is user-initiated or autoplay sound on/off. (See Table 6.8 in http://www.iab.net/media/file/OpenRTBAPISpecificationVersion2_2.pdf) Yes No
delivery Integer Array List of supported delivery methods (e.g., streaming, progressive). (See Table 6.12 in http://www.iab.net/media/file/OpenRTBAPISpecificationVersion2_2.pdf) BrightRoll only supports progressive delivery at this time. No No
pos Integer Ad position on the page. (See Table 6.5 in http://www.iab.net/media/file/OpenRTBAPISpecificationVersion2_2.pdf) Yes No
companiontype Integer Array Describes the VAST companion resource types supported by the inventory (e.g., static resource, iframe resource, etc.) (See Table 6.17 in http://www.iab.net/media/file/OpenRTBAPISpecificationVersion2_2.pdf) No No
companionad Object Array Companion ads are described by the banner object No No
fullscreenexpandable Integer

Possible Values:

0 = not expandable

1 = is expandable

2 = unknown

Yes No
is_skippable Integer

This parameter defines if the inventory allows the user to skip the ad. 

Possible Values for the Request:

0 =  not skippable

1 = is expandable

2 = unknown

Placed inside of ext object of Bid Requests.

Yes No
skip_offset Integer If the inventory is skippable, this parameter defines the number of seconds into that ad that the skip button appears. Yes No

Object: Native

Attribute Type Description Supported Mandatory
request String

Request payload complying with the Native Ad Specification 1.0: http://www.iab.net/media/file/OpenRTB-Native-Ads-Specification-1_0-Final.pdf

Yes Yes
ver String Version of the Native Ad Specification to which request complies; highly recommended for efficient parsing Yes No
api Integer Array List of supported API frameworks for this impression. If an API is not explicitly listed, it is assumed not to be supported. No No
battr Integer Array Blocked creative attributes No No
ext Object Placeholder for exchange-specific extensions to OpenRTB No No

NOTE: Refer to OpenRTB-Native-Ads-Specification-1_0-Final.pdf for Native request and response details.

Object: Mobile App

Attribute Type Description Supported Mandatory
id String

Mobile application's ID on the exchange.

Yes No
name String App name (may be aliased upon request) Yes No
publisher Object Details about the Publisher. Yes No
bundle String Application bundle or package name. Intended to be a unique ID across exchanges. Yes No
domain String Domain of the app. Yes No
storeurl String App store URL for an installed app; for QAG 1.5 compliance. Yes No
cat String Array Array of IAB content categories of the app. (Refer to List 5.1 in https://www.iab.com/wp-content/uploads/2015/06/OpenRTB-API-Specification-Version-2-3.pdf​) Yes No
sectioncat String Array Array of IAB content categories that describe the current section of the app. (Refer to List 5.1 in https://www.iab.com/wp-content/uploads/2015/06/OpenRTB-API-Specification-Version-2-3.pdf​) No No
pagecat String Array Array of IAB content categories that describe the current page or view of the app. (Refer to List 5.1 in https://www.iab.com/wp-content/uploads/2015/06/OpenRTB-API-Specification-Version-2-3.pdf​) No No
ver String Application version Yes No
privacypolicy Integer Indicates if the app has a privacy policy, where 0=no, 1=yes No No
paid Integer 0=app is free, 1=app is a paid version Yes No
keywords String comma separated list of keywords about the app No No
content Object Details of the content in the app. Yes No

Object: Content

Attribute Type Description Supported Mandatory
id String Exchange-specific Yes No

Object: Device

Attribute Type Description Supported Mandatory
ua String Browser user agent string. Yes No
dnt Integer Standard “Do Not Track” flag as set in the header by the browser, where 0 = tracking is unrestricted, 1 = do not track Yes No
lmt Integer "Limit Ad Tracking" signal commercially endorsed No No
devicetype Integer The general type of device. Refer to List 5.17 in https://www.iab.com/wp-content/uploads/2015/06/OpenRTB-API-Specification-Version-2-3.pdf Yes No
make String Device make (e.g., "Apple") Yes No
model String Device model (e.g., "iPhone") Yes No
os String Device operating system (e.g., "iOS") Yes No
osv String Device operating system version (e.g., "3.1.2") Yes No
hwv String Hardware version of the device (e.g., "5S" for iPhone 5S). No No
h Integer Physical height of the screen in pixels. No No
w Integer Physical width of the screen in pixels. No No
ppi Integer Screen size as pixels per linear inch. No No
pxratio float The ratio of physical pixels to device independent pixels. No No
js Integer Support for JavaScript, where 0=no, 1=yes. Yes No
flashver string Version of Flash supported by the browser. No No
language String Browser language using ISO-639-1-alpha-2. Yes No
geo Object Location of the device assumed to be the user's current location defined by a Geo object. This will be given lower priority in respect to user.geo object. Yes No
ip String IPv4 address closest to device. Either of ip/ipv6 is required. Yes Yes
Ipv6 String IP address closest to device as IPv6. Either of ip/ipv6 is required. Yes Yes
carrier String Carrier or ISP (e.g., "Verizon"). "WiFi is often used in mobile to indicate high bandwidth (e.g., video friendly vs. cellular). Yes No
connectiontype Integer Network connection type. Refer to List 5.18.in https://www.iab.com/wp-content/uploads/2015/06/OpenRTB-API-Specification-Version-2-3.pdf Yes No
ifa String ID sanctioned for advertiser use in the clear (i.e., not hashed) No No
didsha1 String Hardware device ID *e.g., IMEI; hashed via SHA1. Yes No
didmd5 String Hardware device ID *e.g., IMEI; hashed via MD5. Yes No
dpidsha1 String Platform device ID (e.g., Android ID); hashed via SHA1. Yes No
dpidmd5 String Platform device ID (e.g., Android ID); hashed via MD5. Yes No
macsha1 String MAC address of the device; hashed via SHA1. No No
macmd5 String MAC address of the device; hashed via MD5. No No

Object: Site

Attribute Type Description Supported Mandatory
id String Exchange-specific site ID. 
Note:
  • If this is to be used for multi-site support, this should be the PubMatic site id. In this case, mapping of the publisher site id to PubMatic site id needs to be maintained by publisher.
  • If the publisher is willing to send only the tag id in the request, then the PubMatic site id will be derived from imp[0].tagid. It will be advantageous if the publisher sends both the site id and tag id.
  • If the publisher is not willing to modify the site body, they can send site id in the PubMatic end point URL.
Yes No
cat String Array Array of IAB content categories of the site. Yes No
page String URL of the page where the impression will be shown. ref string Referrer URL that caused navigation to the current page. It must not be encoded. Yes No
ref String Referrer URL that caused navigation to the current page. Yes No
pagecat String Array Array of IAB content categories that describe the current page or view of the site. Yes No
publisher Object Details about the Publisher Yes Yes
content Object Details about the content within the site. Yes No

Object: Geo

Attribute Type Description Supported Mandatory
lat Float Latitude from -90.0 to +90.0, where negative is south Yes No
lon Float Longitude from -180.0 to +180.0, where negative is west. Yes No
type Integer Source of location data; recommended when passing lat/lon. Yes No
country String Country code using ISO-3166-1-alpha-3. Yes No
region String Region code using ISO-3166-2; 2-letter state code if USA Yes No
metro String Google metro code; similar to but not exactly Nielsen DMAs. Yes No
city String City using United Nations Code for Trade & Transport Locations. It must not be encoded. Yes No
zip String Zip or postal code Yes No

Object: User

Attribute Type Description Supported Mandatory
buyeruid  String Buyer-specific ID for the user as mapped by the exchange for the buyer. Yes No
yob  Integer Year of birth as a 4-digit integer. Yes No
gender String Gender, where “M” = male, “F” = female, “O” = known to be other (i.e., omitted is unknown). Yes No
geo Object Location of the user’s home base defined by a Geo object. This is not necessarily their current location. This will be given higher preference over device.geo object Yes No
id String Exchange-specific ID for the user. At least one of id or buyerid is recommended. Buyerid will be preferred by PubMatic. Yes No

Object: Regs

Attribute Type Description Supported Mandatory
coppa Integer Flag indicating if this request is subject to the COPPA regulations established by the USA FTC, where 0 = no, 1 = yes. Yes No

Object: Publisher

Attribute Type Description Supported Mandatory
id String Exchange-specific publisher ID Yes No

PubMatic Response

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 wrong request/mandatory parameter missing or PubMatic have no creative will return back 204 no content.

PubMatic supports either adm or nurl for video, which can be configured upon request.

Object: BidResponse

Attribute Type Description Supported
id String ID of the bid request to which this is a response. Yes
seatbid Object Array of seatbid objects; 1+ required if a bid is to be made Yes
bidid  String Bidder generated response ID to assist with logging/tracking. Yes
cur String Bid currency using ISO-4217 alpha codes. Yes

Object: SeatBid

Attribute Type Description Supported
bid Object Array required Array of 1+ Bid objects each related to an impression. Multiple bids can relate to the same impression. Yes
seat String ID of the bidder seat on whose behalf this bid is made. Yes

Object: Bid

Attribute Type Description Supported
id String Bidder generated bid ID to assist with logging/tracking. Yes
impid String ID of the Imp object in the related bid request. Yes
price Float Bid price expressed as CPM although the actual transaction is for a unit impression only. Yes
cid String Campaign ID to assist with ad quality checking; the collection of creatives for which iurl should be representative. Yes
adm String Means of conveying ad markup in case the bid wins. Yes
adomain String Array Advertiser domain for block list checking (e.g., “ford.com”). This can be an array of for the case of rotating creatives. Yes
iurl String URL without cache-busting to an image that is representative of the content of the campaign for ad quality/safety checking. Yes
crid String Creative ID to assist with ad quality checking Yes
adid String ID of a preloaded ad to be served if the bid wins. Yes
dealid String Reference to the deal.id from teh bid requeest if this bid pertains to a private marketplace dierct deal. No
ext Object Placeholder for bidder-specific extensions to OpenRTB Yes
h Integer Height of the creative in pixels. Yes
w Integer Width of the creative in pixels Yes

Object: Bid.ext

Attribute Type Description Supported
dspid String Dsp ID Yes
advid String Advertiser ID Yes

Integration Step

Once contract is completed, PubMatic will share the end point with publisher. End point will be similar to http://openbid.pubmatic.com/translator. On this end point, publisher can send open RTB request to PubMatic.

Sample Example

Request Sample

{
    "id": "93D3BAD6-E2E2-49FB-9D89-920B1761C865",
    "at": 1,
    "bcat": ["IAB25", "IAB7-39", "IAB8-18", "IAB8-5", "IAB9-9"],
    "regs": {
        "coppa": 0
    },
    "imp": [{
        "id": "1",
        "instl": 1,
        "bidfloor": 1.2,
        "bidfloorcur": "USD",
        "iframebuster": ["vendor1.com", "vendor2.com"],
        "secure": 1,
        "banner": {
            "w": 728,
            "h": 90,
            "pos": 1,
            "topframe": 0,
            "battr": [1, 2, 16],
            "expdir": [1, 2]
        },
        "ext": {
            "pmZoneId": "XY"
        }
    }, {
        "id": "2",
        "instl": 1,
        "bidfloor": 1.2,
        "bidfloorcur": "USD",
        "iframebuster": ["vendor1.com", "vendor2.com"],
        "secure": 1,
        "banner": {
            "w": 728,
            "h": 90,
            "pos": 1,
            "topframe": 0,
            "battr": [1, 2, 16],
            "expdir": [1, 2]
        },
        "ext": {
            "pmZoneId": "XY"
        }
    }],
    "site": {
        "cat": ["IAB3-1"],
        "pagecat": ["IAB3-1"],
        "page": "http://sitexyz.com/sample.html",
        "ref": "http://referringsite.com/referringpage.html",
        "publisher": {
            "id": "35169"
        }
    },
    "device": {
        "ip": "12.34.56.78",
        "dnt": 1,
        "ua": " Mozilla/5.0 (Windows NT 6.1; WOW64; rv:43.0) Gecko/20100101 Firefox/43.0 ",
        "language": "en-US,en;q=0.5",
        "geo": {
            "country": "US",
            "region": "MA",
            "city": "EastLongmeadow",
            "lat": 42.062000,
            "lon": -72.498901,
            "zip": "01028",
            "type": 2
        }
    },
    "user": {
        "buyeruid": "169F3707-380A-4D76-BE37-B2DB05992D4A",
        "yob": 2010,
        "gender": "F",
        "id": "fCgI95ehkzsr4S0vBXHr9Ue9",
        "geo": {
            "country": "US",
            "region": "MA",
            "city": "EastLongmeadow",
            "lat": 42.062000,
            "lon": -72.498901,
            "zip": "01028",
            "type": 2
        }
    },
    "badv": ["badv.com", "badv1.com", "badv2.com"]
}

Sample Response

{
    "id": "93D3BAD6-E2E2-49FB-9D89-920B1761C865",
    "seatbid": [{
        "bid": [{
            "id": "613673EF-A07C-4486-8EE9-3FC71A7DC73D",
            "impid": "1",
            "price": 100,
            "adid": "916",
            "adm": "cr=<html><a href=\"http://www.pubmatic.com\" target=\"_blank\"><img src = http://blog.gamenightphotos.com/wp-content/uploads/2012/08/300X250-sample-3.png /></a></html>",
            "adomain": ["www.addomain.com"],
            "iurl": "http://localhost11",
            "crid": "creative111",
            "dealid": "dealabc",
            "ext": {
                "dspid": "abc",
                "advid": "xyz"
            }
        },
        {
            "id": "613673EF-A07C-4486-8EE9-3FC71A7DC73D",
            "impid": "2",
            "price": 100,
            "adid": "916",
            "adm": "cr=<html><a href=\"http://www.pubmatic.com\" target=\"_blank\"><img src = http://blog.gamenightphotos.com/wp-content/uploads/2012/08/300X250-sample-3.png /></a></html>",
            "adomain": ["www.addomain.com"],
            "iurl": "http://localhost11",
            "crid": "creative111",
            "dealid": "dealabc",
            "ext": {
                "dspid": "abc",
                "advid": "xyz"
            }
        }],
        "seat": "pubmatic"
    }],
    "cur": "USD"
}

 

NOTE:

To support creative scan publisher needs to replace:

  • ${AUCTION_PRICE} macro with actual bid price in case pubmatic win bid.
  • ${AUCTION_PRICE} macro with AUDIT in case its creative scan.