UAS Ad Request API User Guide

Document created by pubmatic-archivist on Mar 27, 2017Last modified by david.simerly on Aug 23, 2018
Version 68Show Document
  • View in full screen mode

This API enables ad requests from the Unified Ad Server for:

 

 

Service Endpoints for UAS Ad Request

The service endpoints of the API are as follows:

 

 

Ad Request Parameters

The UAS platform allows you to directly integrate with your ad server/platform by making a server-to-server call. Refer to the following ad request parameters when sending the request to UAS. These parameters can be sent in GET or POST. If you send the same parameter in both GET and POST, the Ad Engine will override with the parameter value available in POST.

 

Basic UAS Parameters

Parameter NameRequiredDescription
auYes

ID of the ad's placement. Ad Unit Identifier is the unique identifier for an ad placement. Get this value from the parameter in the UAS ad tag.

 

How to get the Ad Unit ID

  • In Part Two of the Header section of the Banner/Rich Media Ad Tag, you can find Phoenix.defineAdSlot('AdUnit_ID',[[1100, 210]],'Div_ID_To_Render_This_Slot') on which the Ad Unit ID is configured.
  • Additionally, you can find the Ad Unit Identifier on the Ad Unit Management page.

 

If you have configured the UAS placement with different slots on the page, you can make a single ad request call to UAS for different slots available on the page by separating multiple AdUnit IDs using a PIPE (|) separator;

for example, au=adunit1|adunit2.

See Generating Ad Tags in UAS for more details about generating an ad tag.
aszYes

The size of the creative expected on the Ad Unit for Banner, Rich Media, Text, or HTML5 formats. You must pass only valid ad sizes for those configured on the Ad Unit. Passing other sizes results in UAS validation errors against configured ad sizes.

 

Get supported Ad Sizes by Ad Unit for Banner or Rich Media

  • In Part Two of the Header section of Banner or Rich Media Ad Tag, you can find Phoenix.defineAdSlot('AdUnit_ID',[[Width]x[Height], [Width]x[Height]],'Div_ID_To_Render_This_Slot') contains the list of supported sizes.
  • Additionally, you can find list of supported Banner or Rich Media ad sizes in view mode of Ad Unit.

If the ad slot handles different ad sizes, pass a comma-separated (,) list of ad sizes in [Width]x[Height] format.

 

If you are expecting to pass a single request for multiple ad slots, list the ad sizes in sequential order, using a PIPE (|) separator; for example, asz = 728x90,300x250|300x250.

The asz parameter applies only to Banner, Text, Rich Media, or HTML5 request types. Do not use for ad formats Native or Video (that is, req_type is 4 (Native) or 32 (Video)).

In single request mode, if the ad slot identifier DIV_01 expects an Image creative and the ad slot identifier DIV_02 expects a Native creative, configure the basic parameter like so:

au=AdUnit1|AdUnit1&*asz=300x250|&req_type=2|4*&res_format=2|2&rndn=0.219204017082&purl=https%3A%2F%2F
yoursitedomain.com%2Fpage.html&iid=DIV_01|DIV_02&ntid=|205


Be aware, however, that intermixing different formats is not recommended as it can lead to complex requests like the example above.
req_typeYes

Use Request Type to indicate the type of creative format the inventory supports.

 

The supported formats of creatives, and the number to be added:

ValueDescription
1Flash (Reserved - Not supported as on date for guaranteed creatives.)
2Image
4Native
8Text
16Third Party ( Supported for Wrapper Line Item )
32Video
64Rich Media
128HTML5

 

Single Request Mode: If you are expecting to pass a single request for multiple ad slots, list req_type in sequential order by ad slot using a PIPE (|) separator. In the following example, DIV_01 is configured for an image, while DIV_02 slot accepts a Rich Media Creative; for example, req_type=2|64&iid=DIV_01|DIV_02.

Do not mix request types for Native and Video in the same request along with other supported creative formats; for example, you can make a request from the Ad Unit with interchangeable formats such as Image, Text, Rich Media, HTML5, and Third Party (that is, 2+8+64+128+16=218), and it will render correctly.

For Video and Native, make a separate request from the Ad Unit for those specific formats.
res_formatYes

Specify the response type you expect from UAS:

 

ValueFormatDescription
1VASTUse this when requesting Video Creative
2JSONTypically used for Banner, Rich Media, Text, HTML5 and Native
3NativeUse this when requesting Native Creative only. The response will not include other creative details such as those received in JSON format.
For Single Request Mode, res_format should always be 2 if you are expecting to send a single request for all slots available on a page that supports different creative formats like Image, Native, and Video.
iidYes

Slot Identifier

 

When a page supports multiple ad slots for Ad Units, your request must identify every ad slot by its unique identifier. This is required when you make a single ad request for all the available ad slots on the page. UAS responds with the slot-specific creative, which you can use to determine and render a creative in the expected slot.

 

In the case of a single Ad request call, list the ad slots in the iid parameter using PIPE (|) separators; for example, iid=DIV_01 | DIV_02.

purlYes

URL of the target page for the ad.

This parameter's value should be one-time URI encoded.

If your inventory source is a mobile application, you can set, purl="".

Best Practice: optimize monetization by sending the mobile-application-specific and location parameters.
dpurlYes

Indicates the actual page URL.

Mandatory if your account and site level configuration are set to true as mentioned in Notes #1 and #2 below.
Notes:

  1. This parameter is applicable only when your account is marked as Publisher  Aggregators or Channel Partner
  2. If the associated site is enabled for white-listing purposes, this parameter becomes mandatory for Publisher Aggregators.
  3. This parameter's value should be one-time URI encoded.
  4.          
         
sitecodeNo

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

Notes:

  1. This parameter is applicable only in the case of Publisher Aggregators.
  2. For Publisher Aggregators, this parameter becomes mandatory, if the associated site is enabled for white-listing, 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 gets preference in the associated impressions.
  4.          
         
mdnNoA unique random number of data type double ranging between 0 to 1.
While this parameter is not required, you should use it when you want to avoid URL caching by the client browser; for example, mdn=0.6148488499487118
secNo

Secure Flag

If your web pages are secured (SSL compliant), in order to deliver only secured creatives, then you must send sec=1. When using sec=1, UAS selects only SSL complaint creatives from direct or guaranteed inventory. In the case of programmatic or holistic optimization, UAS notifies the demand partner.

tzNoTime zone of the user or browser submitting an ad request. It is an offset, [+/-]hh.mm.
This parameter's value should be URI encoded.
scrnNo

Resolution of screen in [Width]x[Height] format.

If you are unable to determine the screen resolution, you can set the default value as, -1x-1, which signals UAS to submit via the programmatic channel.
adpNo

Resolution of the screen in [Width]x[Height] format.

If you are unable to determine the screen resolution, you can set the default value as, -1x-1, which signals UAS to submit via the programmatic channel.
visiNo

Ad slot visibility on the page where the ad is served. Possible values are:

ValueDescription
0Visibility unknown
1Above the fold
2Below the fold
3Partially Above the fold

Submit multiple ad slots using a PIPE (|) separator.

If visibility is unknown, you can set the default value as 0, which signals UAS to submit via the programmatic channel.
pmZoneIdNo

Use this parameter to pass a zone id for reporting. You can have section-level reporting in a Programmatic Report at a Site Level.

cbackNo

Set the callback function name, which is called by a response from UAS. The response JSON is wrapped in a callback JS function; for example, cback=window.parent.Phoenix.adResponse.

 

The UAS wraps the JSON response with the callback function name as follows:

window.parent.Phoenix.adResponse({"bids":null}) // When there is no creative to render.
window.parent.Phoenix.adResponse({ "bids": [{<Actual Ad Content>}] }) // When UAS responds with creative to render.

 

Privacy Compliance Parameters

Parameter NameRequiredDescription
dntNo

Do Not Track Flag

 

Indicates whether the user has opted out of the publisher or not, or whether HTTP_DNT is set or not. Possible values are:

ValueDescription
0Either the user has not opted out of the publisher or HTTP_DNT is not set.
1Either the user has opted out of the publisher or HTTP_DNT is not set; in this case, PubMatic will not target these users.

 

The default value for this parameter is 0.
coppaNo

COPPA Compliance

Indicates whether the visitor is COPPA-specific or not. For COPPA (Children's  Privacy Protection Act) compliance, if the visitor's age is below 13, they should not be served targeted ads.

 

The United States Federal Trade Commission has written a comprehensive FAQ on complying with COPPA at https://www.ftc.gov/tips-advice/business-center/guidance/complying-coppa-frequently-asked-questions.

 

Possible values are:

ValueDescription
0Indicates that the visitor is not COPPA-specific and can be served targeted ads.
1Indicates that the visitor is COPPA-specific and should be served only COPPA-compliant ads/Creatives
UAS will directly filter the Line Items that are not COPPA-compliant when the ad request expects only COPPA-compliant creative be delivered.
lmtNo

"Limit Ad Tracking" signal commercially endorsed; for example, iOS, Android.

Possible values are:

ValueDescription
0Limit Ad Tracking is unrestricted/disabled.
1Limit Ad Tracking is enabled by a user on a mobile device.
gdprHighly Recommended for EU inventory / users

GDPR parameter signal if the request coming from user is subject to GDPR compliance or not.

Possible values are:

ValueDescription
0

The ad request is not subject to GDPR compliance

1

The ad request is subject to GDPR compliance

For EU countries, If no "gdpr" parameter then UAS considers default as 1.
gdpr_consentHighly Recommended

URL-safe base64-encoded GDPR consent string. Encodes the consented-to purposes and vendor consent string, as obtained from the CMP JS API or OpenRTB

The default sense of consent under GDPR is “opt-out” of all defined purposes for data use by all parties.

 

Native Ad Request Parameters

The Unified Ad Server allows the hosting of Native creatives using the Native Template for direct creatives. If your inventory is enabled for the programmatic channel, UAS tries to monetize from the programmatic channel based on the Demand Optimization Setting.

 

UAS provides options to input the Native asset requirement either in the form of a Native Template Identifier or Direct Native JSON as per IAB standard protocol.

 

Parameter NameRequiredDescription
ntidYes

Native template identifier associated with an Ad Unit. You can pass only one template ID for a given ad unit/ad slot at a time in the ad request.

 

Pass template IDs separated by a pipe ( | ) in case of multi ad request., when making a single request call either for multiple ad unit.

 

It has higher preference over "ntI" ( Below parameter ) if both parameters are passed in Ad Request at a same time and ad engine will ignore ntl.

ntlNo

Native Input JSON

 

Pass the Native JSON as per IAB standard protocol in the ad request.

 

Pass multiple Native JSON as an array when you are making single request call either for multiple ad units as shown in example.

For example, ntI={"ntI": [{"native":"NATIVE JSON FOR AD UNIT"},{"native":"NATIVE JSON FOR ANOTHER AD UNIT"}]}

The parameter value has to be URL encoded while sending in the ad request.

 

Video Parameters

Parameters can be configured while creating an ad unit while making a Video ad request call to UAS.

 

The following parameters will receive a higher preference if passed in the UAS ad request rather than if they are configured in the ad unit. It will also send to Programmatic Channel for better monetization.

*Parameter Name: UAS uses the parameters prefixed with * to apply filters to the guaranteed creative. It does not use any other video parameters for guaranteed ad serving.
Parameter NameRequiredDescription
*vadfmtYes

Video ad format (VAST version) supported as per the IAB standards in response. Possible options are:

ValueDescription
1VAST 1.0 (unsupported)
2VAST 2.0
3VAST 3.0
vfmtYes

Acceptable video streaming formats. It is a combination of the following values separated by +:

ValueDescription
0All
1video/mp4
2application/x-shockwave-flash (VPAID - FLASH)
3video/wmv
4video/h264
5video/webm
6application/javascript (VPAID - JS)
7video/ogg
8video/flv

 

For example, 1+4
Note: Its default value is 0 (All).

vtypeYes

Type of video. Possible values are:

ValueDescription
0Any type
1Linear
2Overlay


Note: Its default value is 0.

*vapiYes

Video ad API (VPAID) version supported as per the IAB standards in response. Possible options are:

ValueDescription
0No VPAID Supported ( Specific to PubMatic )
1VPAID 1.0
2VPAID 2.0


If you do not include this parameter, PubMatic will consider it as No VAPID support and will not pass to the Programmatic Channel.

*vwYes

Width (in pixels) of the video player. For example, 480

*vhYes

Height (in pixels) of the video player. For example, 640

vmimlYes

Minimum duration (in seconds) of the video clip.
For example, 10

vmaxlYes

Maximum duration (in seconds) of the video clip.

For example, 20

vposHighly Recommended

Position of the video in the content. Possible options are:

ValueDescription
0Any position
1Pre-roll
2In-roll
3Post-roll


Note: Its default value is 0.

vskipHighly Recommended

Indicates whether the video ad can be skipped or not. Possible options are:

ValueDescription
0Ads cannot be skipped
1Ads can be skipped


Note: Default value is 0 

vskipdelayNo

Duration (in seconds) after which the user can skip the video ad, if the ad can be skipped. After the skip-delay (also known as skip-offset) duration, a skip button will appear allowing the user to skip the ad. Possible value is any positive integer.

 

Note: Default value is 0 (indicates that the ad can be immediately skipped)

vnoskipadlenNo

Length of the video ad for which the skip functionality will not be applicable. If the video ads can be skipped, ads shorter than this length are rendered without a skip button, that is, the skip option is available only on ads longer than this duration.

 

Default value: 0

 

Note: This parameter can be used by the publisher to give some flexibility to advertisers to play a non-skippable video ad in skippable ad inventory; (trade-off between video ad and publisher content)

vplayHighly Recommended

List of allowed playback methods. If blank, assume that all are allowed. Possible values are as follows:

ValueDescription
1Auto-play sound on
2Auto-play sound off
3Click-to-play
4Mouse-over

 

For example, 1+3

vcomHighly Recommended

Indicates whether a companion ad is requested or not. Possible options are:

ValueDescription
0False
1True


Note: Its default value is 0.

 

Custom Key Value Parameters

GDPR: The custom key and its values must not be used to pass data that PubMatic or others could use or recognize as personally-identifiable information or personal data.
Parameter NameRequiredDescription
gkvNo

Global custom key values, applicable for all slots available on the page.


The key-value pairs should be separated by an ampersand (&). If the key contains multiple values, then the values should be separated by a comma (,).

 

If your Line Item targeted on K1=V1&K2=V2, the Line Item will serve only if the ad request/ad tag contains K1=V1&K2=V2. The key and value are case sensitive and Line Item will not get deliver if ad request/ad tag contains K1=V1&k2=v2 (Here k2 and v2 are small letters).

 

Deactivating the key (for example, K1=V1), impacts all existing Line Items targeting where K1=V1 is used for targeting. The Line Item starts delivering even if the ad request now contains only K2=V2.

 

The gkv value in the ad request must be URL encoded; for example, the value gkv=K1=V1&K2=V2, when URL encoded form would be: gkv=K1%3DV1%26K2%3DV2

slt_kvNo

Use slt_kv parameter if you would like to pass a slot-specific key value in the ad request/ad tag.

 

The key-value pairs should be separated by an ampersand (&). If the key contains multiple values, the values should be separated by a comma (,).


The key-value pairs of different slots should be separated by a pipe ( | ).

 

If your Line Item targeted on K1=V1&K2=V2, the Line Item will serve only if the ad request/ad tag contains K1=V1&K2=V2. The key and value are case sensitive and Line Item will not get delivered if the ad request/ad tag contains K1=V1&k2=v2 (Here k2 and v2 are small letters).

 

Deactivating the Key ( for example, K1=V1), impacts all existing Line Items targeting where K1=V1 is used for targeting. The Line Item  starts delivering even if the ad request now contains only K2=V2.

 

The slt_kv value in the ad request must be URL encoded; for example, the value, slt_kv=K1=V1&K2=V2, when URL encoded would be: slt_kv=K1%3DV1%26K2%3DV2

If the ad request/ad tag contains both gkv ( Global Custom Key ) and slt_kv (Slot-Specific Key), it will get considered for the slot while checking targeting for custom key on the Line Item. For example, if Ad Request contains gkv=K1%3DV1 and slt_kv=K2%3DV2, the Line Item will get delivered containing K1=V1&K2=V2 targeting if eligible for the Ad Unit.

 

Location-Specific Parameters

Parameter NameRequiredDescription
locNo

Location of the user's mobile device. Its value indicates the latitude and longitude, and should be specified in the Latitude, Longitude format such as 41.906365, -75.327759.

Latitude varies from -90 to 90 and longitude varies from -180 to 180. Note that South and West are depicted as negative numbers.

loc_sourceNo

Source of Latitude & Longitude. 

ValueDescription
1Latitude, Longitude obtained using Actual GPS
2Location information obtained using IP address
3Location information obtained using user registration data
If you pass loc then you must also pass loc_sourc.

 

Mobile Application Profile-Specific Parameters

Parameter NameRequiredDescription

iabcat

No

IAB Category

 

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, send categories separated by comma, and the string should be URL encoded. For example, iabcat=IAB1%2CIAB-5%2CIAB1-6

nameNo

Application Name

 

Name of the mobile application. This value should be the same as that mentioned on the application (app) store.

aidNo

Application ID

 

Mobile application's ID on the exchange. This parameter is applicable only in the case of a mobile application view. In case of iOS App, this is recommended to be correctly passed by the caller.

bundleNo

Application Bundle

 

Application bundle or package name; for example, com.foo.mygame. This is intended to be a unique ID across multiple exchanges. In case of Android App, this is recommended to be correctly passed by the caller.

catNo

Application Category

 

Application primary category as displayed on storeurl page for the respective platform.

apiNo

Application API

 

List of supported API frameworks for this impression. If an API is not explicitly listed, then it is assumed to be not supported. If an application supports multiple API frameworks, you can send the multiple framework values separated by :: and URL encoded string. For example, api=3%3A%3A4%3A%3A5

 

ValueDescription
3MRAID 1.0
4ORMMA
5MRAID 2.0
storeurlNo

Application Store URL

URL of the app store from where a user can download this application.

This parameter's value should be one-time URI encoded.
verNo

Application Version

Version of the application

appdomainNo

Application Domain

Indicates the domain of the mobile application

paidNo

Application Paid

 

Indicates whether the mobile application is a paid version or not. Possible values are:
0 - Free version

1 - Paid version

 

Mobile Application-Specific Parameters

Parameter
Mandatory
Description
udid
Yes

Device ID

A unique device identifier for the given udidtype.

udidtype
Required for Mobile Apps

Device ID Type

Type of value provided in the udid parameter mentioned above. Possible values are:

ValueMobile Application PlatformDescription
0iOS/AndroidOther/Unknown
1iOS

IDFA (Identifier for Advertiser)

You can find more information here to understand how to retrieve this using Objective C in iOS application.

2iOS

IDFV (Identifier for Vendor)

You can find more information here to understand how to retrieve this using Objective C in iOS application.

3Android

Android identifier

You can find more information here to understand how to retrieve this using Android in Android application.

9Android

Android Advertising Identifier

You can find more information here to understand how to retrieve this using Android in Android application.

udidhash
Required for Mobile Apps

Device ID Hash Type

 

Type of algorithm used for hashing the device identifier provided in the udid parameter mentioned above. If you are sending the IDFA, IDFV or Android Advertising identifier we recommended sending Raw unless you have privacy/security compliance. You must pass this parameter if you are passing udid or udidtype.

 

Possible values are:

ValueDescription
0Unknown - not aware if performed any hashing on udid
1Raw
2SHA1
3MD5
Default value is 0.

 

Mobile Device Parameters

Parameter
Mandatory
Description
nettypeNo

Type of network used for the data connection.

Possible values are:

  • wifi
  • cellular
UAS does not use this parameter for guaranteed line item targeting if targeting is set.
carrierNo

Name of the carrier or ISP derived from the user's IP address.

This parameter and value aren't used for selecting direct Line Items. UAS inferred the carrier details using IP address and is used for targeting. If Carrier details are passed over UAS ad request then it has been used to inform demand partner for Holistic optimization.
jsHighly Recommended

Indicates whether the user's mobile device supports JavaScript or not.

 

Possible values are;

ValueDescription
-1Unknown (Default value). UAS does not pass the js value to the programmatic channel if the publisher has not explicitly provided the value.
0Device does not support JavaScript
1Device supports JavaScript
deviceOrientationNo

ID of the device orientation. Possible values are:

ValueDescription
0Portrait orientation
1Landscape orientation

 

Blocking Advertiser and Creative

Parameter
Mandatory
Description
battrNo

Blocked Creative Attributes

 

Comma-separated list of blocked creative attributes’ IDs.

For details on the values passed and the corresponding category names, refer to the Creative Attributes table in the Reference section of this document.
blkdmnsNoBlocked Domain IDs

 

Comma-separated list of advertiser domains' IDs to be blocked for the given impression.
blkadvtidsNo

Blocked Advt IDs

 

Comma-separated list of advertisers' IDs to be blocked for the given impression.

blkadvtdmnsNo

Blocked Advt Domains

 

This parameter will have a comma-separated list of advertiser domain URLs, that PubMatic ad-serving will block from responding with creative. The limit of URLs the system can support is 40 URLs.

blkiabcatsNo

Blocked IAB Cat IDs

 

Comma-separated list of advertiser IAB category IDs to be blocked for the given impression. For the list of supported IAB categories, refer the IAB Categories List table. The limit of IAB categories the system can support is 20 categories.

 

Ad Request Headers

If you are expecting to integrate with users using a server-to-server approach using the UAS ad request, you must send the following set of HTTP Headers. 

 

Parameter
Mandatory
Description
User-Agent
Yes

User Agent of the browser.


This is an important header as it is used to apply filters to find eligible line items if targeted on Device Targeting such as Browser, Device Capabilities, Operating System, Device Manufacture and Model, Device Categories.

Accept-Language
Yes
Indicates the list of languages accepted by the browser. This is used if your line item is targeted on Language.
RLNClientIpAddr
Yes

This is an important header as it is used to apply filters to find eligible line items if targeted on IP address, Geo such as Country, State, City, DMA and Zip Code.


Indicates the IP address of the device which originated in the ad request.

Please send only one IP address (should be the one most relevant to the user). Do not send multiple IP addresses or X-Forwarded-For header, or this may result in an error/non-monetization.
Referer
No
Indicates the Reference URL for the ad request.
KADUSERCOOKIE
Yes
In case of server-to-server integration, sending PubMatic user ID as KADUSERCOOKIE header parameter is mandatory. The PubMatic user ID should be sent in the request header as a cookie key-value pair. The user cookie key name is KADUSERCOOKIE.

For example, Cookie:KADUSERCOOKIE=F6FC89B0-54AE-46E1-A5FF-10336B7A8E26;

Refer: Server side user cookie sync up

 

Ad Response Parameters

{
     "bids": [{
          "id": "DIV1",
          "ecpm": 0,
          "ct": "%3Ca%20href=%22http://phtrack.pubmatic.com/track%3Fts=1450160060\u0026r=10537090-87ab-4c17-8fb6-d3bcc89c8a8a\u0026i=f4c09386-6c74-4e10-8dfe-d34a7b1bc87c\u0026a=118418\u0026t=67\u0026au=48\u0026p=http%253A%252F%252F192.82.243.85%253A8090%252FCPCTest.html\u0026wl=65\u0026ty=3\u0026url=http%253A%252F%252FBing.com%22%20target=%22_blank%22%3E%3Cimg%20src=%22http://dummyimage.com/970x250/000/fff\u0026text=CPCTest1-House.png%22alt=%22CPC%20House%22%20title=%22CPC%20House%22%3E%3C/a%3E",
          "crTy":2,
          "tr": ["http://phtrack.pubmatic.com/track?ts=1450160060\u0026r=10537090-87ab-4c17-8fb6-d3bcc89c8a8a\u0026i=f4c09386-6c74-4e10-8dfe-d34a7b1bc87c\u0026a=118418\u0026t=67\u0026au=48\u0026p=http%3A%2F%2F192.82.243.85%3A8090%2FCPCTest.html\u0026wl=65\u0026ty=1"],
          "cltr":[ "http://phtrack.pubmatic.com/track?ts=1450160060\u0026r=10537090-87ab-4c17-8fb6-d3bcc89c8a8a\u0026i=f4c09386-6c74-4e10-8dfe-d34a7b1bc87c\u0026a=118418\u0026t=67\u0026au=48\u0026p=http%3A%2F%2F192.82.243.85%3A8090%2FCPCTest.html\u0026wl=65\u0026ty=3\u0026url=http%3A%2F%2FBing.com"],
          "at": 0,
          "pd": 0,
          "h": 250,
          "w": 970,
          "in": false,
          "creativeID": 103,
          "adUnitID": 48,
          "lineItemID": 65,
          "orderID": 28
     }]
}

 

Parameter NameTypeDescription
idStringSlot
ecpmFloat32ecpm
ctStringCreative
crTyInteger

Creative Type:

  1. Flash
  2. Image
  3. Native
  4. Text
  5. ThirdParty
  6. Video
  7. RichMedia
trArray of StringsTracking URL(s)
cltrArray of StringsClick Tracking URL(s)
atIntegerAuto Refresh Time
pdIntegerPrefetch Data
HeightIntegerHeight of the Creative
WidthIntegerWidth of the Creative
IsNative BooleanIf the response is native (useful for the AdClient.js)
CreativeIDIntegerCreative ID from the DB (for debugging)
AdUnitIDIntegerAd Unit ID (for debugging)
LineItemIDIntegerLine Item ID (for debugging)
OrderIDIntegerOrder ID (for debugging)
exchangeRateFloatUAS does the conversion from any other currency to USD during an auction using day-level exchange rate.
impressionIDStringUnique identifier for an impression

 

Sample Ad Requests/Responses

Banner/Rich Media Request

The following link demonstrates how to construct a basic ad request for Banner expecting only Image type of Creative. You can add/modify various other important parameter values using Ad Request Parameters explained above. 

http://ae.pubmatic.com/ad?au=<AdUnit1>&asz=W1xH1,W2xH2&req_type=2&res_format=2&rndn=0.219204017082&purl=https%3A%2F%2Fyoursitedomain.com%2Fpage.html&iid=DIV_01

 

No Ad Response

{
    "bids": null
}

 

Banner Ad Response

The following is a sample response for a Banner/Rich Media Creative.

{
    "bids": [{
        "id": "DIV_01",
        "ecpm": 0.01,
        "ct": "<Creative to be render>",
        "tr": [
            "Impression Tracker 1",
            "Impression Tracker 2"
        ],
        "cltr": [],
        "at": 0,
        "pd": 0,
        "h": 250,
        "w": 300,
        "in": false,
        "creativeID": "<Creative Identifier>",
        "adUnitID": <AdUnit Identifier> ,
        "lineItemID": <Line Item Identifier> ,
        "orderID": <Order Identifier> ,
        "crTy": 2,
        "exchangeRate": <Exchange Rate of the day>,
        "impressionID": "<Impression Identifier - GUID>"
    }]
}

 

Native Ad Request

Request for Native Creative Format.

http://ae.pubmatic.com/ad?au=AdUnit1&req_type=4&res_format=2&rndn=0.219204017082&purl=https%3A%2F%2Fyoursitedomain.com%2Fpage.html&iid=DIV_01&ntid=<Native Template ID>

 

Native Response

{
    "bids": [{
        "id": "DIV_01",
        "ecpm": 0.01,
        "ct": "Encoded Native Creative JSON",
        "tr": [
            "Impression Tracker 1",
            "Impression Tracker 2"
        ],
        "cltr": [],
        "at": 0,
        "pd": 0,
        "h": 250,
        "w": 300,
        "in": false,
        "creativeID": "<Creative Identifier>",
        "adUnitID": <AdUnit Identifier> ,
        "lineItemID": <Line Item Identifier> ,
        "orderID": <Order Identifier> ,
        "crTy": 3,
        "exchangeRate": <Exchange Rate of the day>,
        "impressionID": "<Impression Identifier - GUID>"
    }]
}

 

Video Ad Request

http://ae.pubmatic.com/ad?au=AdUnit1&req_type=32&res_format=1&rndn=0.219204017082&purl=https%3A%2F%2Fyoursitedomain.com%2Fpage.html&iid=DIV_01&vadfmt=2&vfmt=0&vtype=1&vw=400&vh=300&vpos=1&vskip=1&vplay=1+3&vcom=0

 

Video Response

The video response contains the video XML creative.

 

Single Request Mode

If you have configured multiple ad slots on the page and expect to make a single ad request call for all ad slots rather than the individual request from your server to the UAS system, you can send various parameters either at global level or slot level.

 

Ad Request: Banner/Rich Media Format

The following is a sample banner request format for Ad Unit 1 across two slots DIV_01 and DIV_02. The slot-level-supported parameters should be separated by a PIPE in the sequence of the Slot you are expecting to pass parameter. In the following sample request, it is expected to deliver creative/ad size ( 300x250) for DIV_01 and 250x250 for DIV_02 of type Image only.

 

Request for Banner Creative

50|250x250&req_type=202|202&res_format=2&rndn=0.219204017082&purl=https%3A%2F%2Fyoursitedomain.com%2Fpage.html&iid=DIV_01|DIV_02

 

Ad Response: Banner/Rich Media

If UAS found a valid set of creatives for all requested slots, you can find the array of bids containing the creative having "id" as slot identifier by which you can recognize and render the slot-specific creative.  If UAS does not find creative for a specific ad slot the ad response won't contain any creative for the slot identifier. 

{
    "bids": [{
        "id": "DIV_01",
        "ecpm": 3,
        "ct": "<Creative Code to be render>",
        "tr": [
            "Impression Tracker 1",
            "Impression Tracker 2"
        ],
        "cltr": [],
        "at": 0,
        "pd": 0,
        "h": 250,
        "w": 300,
        "in": false,
        "creativeID": "<Creative Identifier>",
        "adUnitID": <AdUnit Identifier> ,
        "lineItemID": <Line Item Identifier> ,
        "orderID": <Order Identifier> ,
        "crTy": <Creative Type> ,
        "exchangeRate": <Exchange Rate of the day>,
        "impressionID": "<Impression Identifier - GUID>"
    },
    {
        "id": "DIV_02",
        "ecpm": 5,
        "ct": "<Creative Code to be render>",
        "tr": [
            "Impression Tracker 1",
            "Impression Tracker 2"
        ],
        "cltr": [],
        "at": 0,
        "pd": 0,
        "h": 250,
        "w": 250,
        "in": false,
        "creativeID": "<Creative Identifier>",
        "adUnitID": <AdUnit Identifier> ,
        "lineItemID": <Line Item Identifier> ,
        "orderID": <Order Identifier> ,
        "crTy": <Creative Type> ,
        "exchangeRate": <Exchange Rate of the day>,
        "impressionID": "<Impression Identifier - GUID>"
    }]
}

 

Ad Request: Native Ad Format

Using Native Template Id: Here both ad slots of Ad Unit 1 expect Native creative for ad slot DIV_01 and DIV_02 for Native Template mentioned in "ntid" parameter. 

 

Request for Native Ad Format Using Native Template ID

http://ae.pubmatic.com/ad?au=AdUnit1|AdUnit1&req_type=4|4&res_format=2|2&rndn=0.219204017082&purl=https%3A%2F%2Fyoursitedomain.com%2Fpage.html&iid=DIV_01|DIV_02&ntid=205|206

 

Using Native JSON: Here Both ad slots of Ad Unit 1 expect Native  creative for ad slot DIV_01 and DIV_02 for Native Template in "ntI" parameter.   The ntI parameter value should be URL encoded. 

 

Request for Native Ad Format Using Native Template JSON

http://ae.pubmatic.com/ad?au=AdUnit1|AdUnit1&req_type=4|4&res_format=2&rndn=0.219204017082&purl=https%3A%2F%2Fyoursitedomain.com%2Fpage.html&iid=DIV_01|DIV_02&ntI={"ntI": [{"native": <Native Template JSON For DIV_01>}, {"native":  <Native Template JSON For DIV_02>} ] }

 

Ad Request: With Mixed Ad Format

In Single Request Mode, you can intermix the various creative formats such as Image, Native and Video (that is, req_type) if ad slots expect different creative format. However, it is not recommended to mix a variety of formats, as it may increase the complexity of the request.

 

Request for Banner, Native and Video

http://ae.pubmatic.com/ad?au=AdUnit1|AdUnit1|AdUnit2&asz=300x250|&req_type=202|4|32&res_format=2&rndn=0.219204017082&purl=https%3A%2F%2Fyoursitedomain.com%2Fpage.html&iid=DIV_01|DIV_02|DIV_03&ntid=|205&vadfmt=2&vfmt=0&vw=400&vh=300

 

⇧ Top

Attachments

    Outcomes