Ad Tags

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

Description

Ad Tags indicate the ad slot on a site or app in which the ad needs to be displayed. These tags are mapped to either Banner ads, Video ads or Native ads.

Methods

                                             

Method Path
HTTP Method Type
Description
Link to Definition
/publisherAdTag?entityId={publisherId}POSTCreate an ad tag associated with a specific site or app in the PubMatic platformCreating an Ad Tag
/publisherAdTagGETRetrieve the list of ad tags associated with the publisher's accountRetrieving List of Ad Tags
/publisherAdTag/{id}?entityId={publisherId}GETRetrieve the details of a specific ad tagRetrieving Details of an Ad Tag
/publisherAdTag/{id}?entityId={publisherId}PUTUpdate the details of an existing ad tagUpdating an Ad Tag
/publisherAdTag/{id}?pubId={publisherId}DELETEDelete a specific ad tag from the PubMatic platformDeleting an Ad Tag
/publisherAdTag?pubId={publisherId}&adTagId={ad1,ad2}DELETEDelete multiple ad tags from the PubMatic platformDeleting Multiple Ad Tags

 

Create an Ad Tag

Overview

This API allows you to create a basic ad tag with a passback demand placement associated with it. While creating an ad tag, there are two approaches:

  1. User can provide the details of an existing passback placement
  2. User can provide the mandatory details (currency, eCPM and passback script) to create a new passback placement. The system will automatically map this new passback placement to the new ad tag.

While creating a video/native ad tag, user needs to pass some extra information in the form of beans such as videoProperties/nativeAdTagConfigMapping.

Request

         

URI

${URI_PREFIX}/inventorymgmt/publisherAdTag

 

Note: For sandbox testing, $URI_PREFIX should be replaced with "http://api-sandbox.pubmatic.com/v1".
For production, $URI_PREFIX should be replaced with "http://api.pubmatic.com/v1".
HTTP MethodPOST

Request Headers

                        

Header Name
Type
Value
Required
Description
Content-Type
application/json
-
Yes
-
Authorization
String
Bearer ${access_token}
Yes
The access token generated for authentication should be sent in place of ${access_token}.
For more information about access tokens, refer to Getting Started with PubMatic APIs.

Request Query Parameters

                 

Parameter
Type
Required
Validations
Description
entityId
Long
Yes
-
ID of the publisher for which the ad tag needs to be created.

Request Body

                                                                                                            

Body ParameterTypeRequiredValidationsDescription
publisherIdlongYes

This should be a valid Publisher entity present in the PubMatic platform

ID of the publisher for which the ad tag needs to be created.
publisherSiteurlStringYes
  1. This is a mandatory field and must be a valid URL.
  2. Site should be an active entity in the PubMatic platform.

URL of the site for which the ad tag needs to be created. If the user provides a valid site, then its platform will be automatically fetched.


Note: While creating a video ad tag, ensure that this site is marked as API in the PubMatic platform, that is, "apiSetting": true.

adTagNameStringYes
  1. This is a mandatory field.
  2. Validated with Regular expression.
  3. Existing name is not allowed
Name of the new ad tag.
adCodeTypeIdIntegerYes
  1. This is a mandatory field.
  2. Must be a valid ad code type supported in the PubMatic system

Code type of the new ad tag. Valid values are:

  •  0 - IFrame
  • 1 - JavaScript
  • 2 - Mobile
  • 3 - VAST
foldPlacementIdIntegerNo
  1. Must be a valid fold placement type supported in the PubMatic system.
  2. Default value for Fold Placement is 0 (for UNKNOWN).

Fold placement of the new ad tag. Valid values are:

  • 0 - Unknown
  • 1 - Above The Fold
  • 2 - Below The Fold
  • 3 - Partially Above The Fold
adTypeIdIntegerYes

Must be a valid ad type supported in the PubMatic system.

Ad type of the new ad tag. Valid values are:

  • 3 - Text And Image
  • 12 - Native
  • 13 - Video
pagePlacementIdInteger No 
  1. Must be a valid page placement supported in the PubMatic system.
  2. Default value for Page Placement is 6 (for NOT_SURE).

Page placement of the new ad tag. Valid values are:

  • 1 - Top of Page
  • 2 - Bottom of Page
  • 3 - Middle of Page
  • 4 - Left of Page
  • 5 - Right of Page
  • 6 - Not Sure
adExpansionDirectionIdIntegerNo
  1. Must be a valid Ad expansion direction supported in the PubMatic system .
  2. Default value for Ad Expansion Direction is 0 (for UNKNOWN).

Ad expansion direction of the new ad tag. Valid values are:

  • 0 - Unknown
  • 1 - Up
  • 2 - Down
  • 3 - Left
  • 4 - Right
adSizeObjectYes
  1. This is a mandatory field.
  2. This Object represents the ad sizes supported by the PubMatic system.
  3. id field is mandatory in this object.

Ad size of the new ad tag. For retrieving the list of ad sizes, refer Retrieving List of Ad Sizes.

For example,


{
"id": 72,
}
adTagCustomParamMapList of ObjectsNo
  1. The Object of this field has name and macrovalue fields.
  2. For mandatory custom parameters, the default vale of the macrovalue is "".
  3. kadpageurl is a mandatory parameter if the platform of the ad tag is either Web,Mobile Web or Video.
  4. kadudid,kadudidtype and kadudidhash are required in case of Mobile App ad tag.
  5. kadloc and kadlocsource are required for Mobile App or Mobile Web ad tag.
     

Custom parameter definition for the new ad tag using key=value pattern.

Some of the custom parameters are mandatory while creating an ad tag depending upon the ad tag's platform and  ad type. If the publisher supports any of the following custom parameters,please provide corrosponding macroValue as it will be replaced in the ad script at runtime.

For example,


"adTagCustomParamMap": [{
"name": "kadcarrier",
"macroValue": "techno.carrier"
} ]

Valid values for the name field are:

  • kadloc - Location
  • kadstate - State
  • kadcity - City
  • kaddma - DMA
  • kadzip - Postal or Zip code
  • kadyob - Year of birth
  • kadnettype - Type of internet connection
  • kadcarrier - Mobile carrier
  • kadethnicity - Ethnicity
  • kadincome - Income
  • kadcountry - Country
  • kadkw
  • kadgender - Gender
  • kadudid - Mobile user device ID (UDID)
  • kadudidtype - UDID type
  • kadudidhash - UDID hashing algorithm
  • kappname - Mobile app name
  • kappstoreurl - Mobile app store URL
  • kaid - Mobile app ID
  • kbundle - Mobile app bundle ID
  • kcat - Category
  • kapi
  • kadfloor - Floor value
  • authToken
  • targetedDimensions
  • videoPlayerVendor - Video player vendor supported
  • videoPlayerTechnology - Video player technology supported
  • videoFileFormats - Video file format supported
  • kadpageurl - Page URL of the impression
asoTypeObjectNo
  1. This is a mandatory field.
  2. id field is mandatory in this object.
  3. Default value for asoType is 3.

Indicates whether geo targetting for this new ad tag should be enabled or disabled.

Valid values for asoType.id field are:

  • 3 - No Geo targetting
  • 4 - Enable Geo targetting

For example,


"asoType": {
"id": 3
}
adTagPlacementsList<Object>Yes 

Details of the passback placement to be associated with the new ad tag.

While creating a basic ad tag, user needs to either map an existing passback placement or provide the mandatory parameters required to create a passback placement. Refer to the AdTagPlacement table below for more details of this object.

videoPropertiesObjectNo

This Object is required while creating a Video ad tag

Details of the video configuration to be associated with a Video ad tag. For description of the fields present in this object, refer the VideoProperties table below.

nativeAdTagConfigMappingObjectNo
  1. This Object is required while creating a Native ad tag.
  2. nativeAdtagConfigId field is required and this ID must be already registered in the PubMatic system.

Details of the native configuration to be associated with a Native ad tag. nativeAdtagConfigId indicates the ID of the native template which needs to be associated with the ad tag.

For example,


"nativeAdTagConfigMapping": {
"nativeAdtagConfigId": 93
}

 

VideoProperties Bean Description

                                                                                       

Body ParameterTypeRequiredValidationsDescription
idIntegerYes
  1. This value should be 0 while creating new Video ad tag.
  2. During an update operation, this id should not be 0 or null
ID of the Video Properties Bean
hasCompanionBooleanNo

Default value is false.

Indicates whether this new Video ad tag supports companion ads or not.
protocolObjectNo
  1. Must be a valid video protocol supported by the PubMatic system.
  2. id field of this object is required and is of Long Datatype.
  3. Default value for this Object is id=2.

Video protocal to be associated with the new Video ad tag. Valid values for the id field are:

  • 2 - VAST 2.0
  • 3 - VAST 3.0

For example,


"protocol": {
"id": 2
},
videoLinearityInteger 
  1. Default value is 0
  2. Must be a valid video position supported by the PubMatic system

Video ad type supported by this new video ad tag. Linear video ads are ads that play before, after, or during a break in the video content (otherwise known as pre-roll, mid-roll, or post-roll). Non-linear ads appear along with the video content. Overlays, a common non-linear ad format, cover part of the video as it plays.Valid values are:

  • 0 - Any
  • 1 - Linear
  • 2 - Non-Linear
videoPlayerWidthIntegerNo
  1. Default value is 0
Width of the video ad.
videoPlayerHeightIntegerNo
  1. Default value is 0
Height of the video ad.
videoPositionIntegerNo
  1. Default value is 0
  2. Must be a valid video position supported by the PubMatic system
     

Position of the video ad. Valid values are:

  • 1 - Pre-roll
  • 2 - In-roll
  • 3 - Post-roll
vpaidVersionIntegerNo
  1. Default value is 0
  2. Must be a valid VPAID version supported by the PubMatic system
     

VPAID version supported by the video ad tag. Valid values are:

  • 0 - No VPAID support
  • 1 - VPAID 1.0
  • 2 - VPAID 2.0
videoMimeTypesList<Long>Yes
  1. This is a mandatory field.
  2. Must be a valid MIME type supported by the PubMatic system.

MIME type supported by the video ad tag. Valid values are:

  • 1 - mp4
  • 2 - swf
  • 3 - wmv
  • 4 - H.264
  • 5 - webm
  • 6 - JavaScript
  • 7 - ogg
  • 8 - flv
minDurationIntegerNo

Default value is 0

Minimum duration of the video ad in seconds.
maxDurationIntegerNo

Default value is 120

Maximum duration of the video ad in seconds.

AdTagPlacement Object : 

                                       

Body ParameterTypeValidationsDescription
currency Integer
  1. This field is mandatory only if you use an ad script to create a new passback placement for this ad tag.
  2. This should be valid currency supported in the PubMatic system.
ID of the currency to be used for the new passback placement associated with the new ad tag. For a list of supported currencies, refer the Currency table below.
adScript StringThis field is mandatory only if you use an ad script to create a new passback placement for this ad tag.Ad script to be used for the new passback placement associated with the new ad tag.
ecpm Float

This field is mandatory only if you use an ad script to create a new passback placement for this ad tag.

eCPM floor to be used for the new passback placement associated with the new ad tag.

For example,


"adTagPlacements": [{
"adTagPlacementId": 0,
"linkOnlyToGeo": false,
"ecpm": 1,
"adScript": "THIS IS A DEMO SCRIPT",
"currency": 1
}]
placementIdLong
  1. This field is mandatory only if you want to map an existing passback placement to this new ad tag.
  2. This placement ID should be a valid ad network placement entity in the PubMatic system.
ID of the existing passback placement to be associated with the new ad tag.
adNetworkIdLong
  1. This field is mandatory only if you want to map an existing passback placement to this new ad tag.
  2. Ad network should be already associated with the publisher account.
  3. Should be a valid ad network entity in the PubMatic system.

ID of the ad network associated with the passback placement mapped ti the new ad tag.

For example,


"adTagPlacements": [{
"placementId": 206843,
"adNetworkId": 165,
}]

Currency

                                                                                                                                                                                   

Currency ID
Currency
  1
 US dollar            
  2
 Euro                 
  3
 British Pound        
  4
 Canadian dollar      
  5
 Australian dollar    
  6
 Swedish Krona        
  7
 Swiss Franc          
  8
 Czech Koruna         
  9
 Danish Krone         
 10
 Brazilian Real       
 11
 New Zealand Dollar   
 12
 Japanese Yen         
 13
 Malaysian Ringgit    
 14
 Thai Baht            
 15
 Singapore Dollar     
 16
 Indonesian Rupiah    
 17
 Philippine Peso      
 18
 South Korean Won     
 19
 New Taiwan Dollar    
 20
 Hong Kong Dollar     
 21
 Chinese Yuan Renminbi
 22
 UAE Dirham           
 23
 Saudi Arabia Riyal   
 24
 Norwegian Krone      
 25
 Polish Zloty         
 26
 Israeli Shekel       
 27
 Turkish Lira         
 28
 South African Rand   
 29
 Russian Ruble        
 30
 Hungarian Forint     
 31
 Indian Rupee         
 32
 Argentine peso       
 33
 Chilean peso         
 34
 Kuwaiti dinar        
 35
 Mexican peso         
 36
 Bahraini dinar       
 37
 Venezuelan bolivar   
 38
 Colombian Peso       
 39
 Croatian Kuna        
 40
 Mauritian Rupee      
 41
 Omani Rial           
 42
 Qatari Riyal         
 43
 Romanian New Leu     

Sample Request for a Simple Ad Tag with a New Passback Placement and Custom Parameters


URL: ${URI_PREFIX}/inventorymgmt/publisherAdTag?entityId=2685
Method: POST
Request Body:
{
    "publisherId": 2685,
    "publisherSiteurl": "http://example.org",
    "adTagName": "THIS_IS_TEST_DEMAND_5",
    "adCodeTypeId": 1,
    "foldPlacementId": 1,
    "adTypeId": 3,
    "pagePlacementId": 1,
    "adExpansionDirectionId": 1,
    "adSize": {

        "name": null,
        "width": 0,
        "height": 0,
        "id": 9
    },
    "adTagPlacements": [{
        "adTagPlacementId": 0,
        "linkOnlyToGeo": false,
        "ecpm": 1,
        "adScript": "THIS IS DEMO SCRIPT",
        "currency": 1
    }],
    "adTagCustomParamMap": [{
        "name": "kadcarrier",
        "macroValue": "techno.carrier"
    }, {
        "name": "kadcity",
        "macroValue": "geo.city"
    }]
}

Sample Request for a Video Ad Tag with a New Passback Placement


URL: ${URI_PREFIX}/inventorymgmt/publisherAdTag?entityId=2685
Method: POST
Request Body:
{
    "publisherId": 2685,
    "publisherSiteurl": "http://www.example.com/sports2",
    "adTagName": "vidwo_2685_1",
    "adCodeTypeId": 2,
    "adTypeId": 13,
    "foldPlacementId": 0,
    "adExpansionDirectionId": 0,
    "adSize": {
        "height": 0,
        "id": 72,
        "name": "Video N/A",
        "width": 0
    },
    "adTagCustomParamMap": [{
        "macroValue": "ddd",
        "name": "kadpageurl"
    }],
    "adTagPlacements": [{
        "adScript": "rr",
        "adTagPlacementId": 0,
        "currency": "USD",
        "ecpm": 1.1,
        "linkOnlyToGeo": false
    }],
    "videoProperties": {
        "hasCompanion": 0,
        "hasVpaidSupport": true,
        "id": 0,
        "protocol": {
            "id": 2
        },
        "videoLinearity": 0,
        "videoPlayerHeight": 1,
        "videoPlayerWidth": 1,
        "videoPosition": 1,
        "vpaidVersion": 2,
        "videoMimeTypes": [1, 2, 3, 4, 5, 6, 7, 8]
    }
}

Sample Request for a Native Ad Tag with an Existing Passback Placement


URL: ${URI_PREFIX}/inventorymgmt/publisherAdTag?entityId=2685
Method: POST
Request Body:
{
    "publisherId": "2685",
    "publisherSiteurl": "http://example.com",
    "adTagName": "example1_1x1_native_without_url_9",
    "adCodeTypeId": 1,
    "foldPlacementId": 0,
    "adTypeId": 12,
    "pagePlacementId": 6,
    "adExpansionDirectionId": 0,
    "adSize": {
        "name": "Native default size",
        "width": 1,
        "height": 1,
        "id": 138
    },
    "adTagPlacements": [{
        "adTagPlacementId": 0,
        "adTagId": 0,
        "siteId": 81875,
        "placementId": 206843,
        "platformId": 1,
        "adNetworkId": 165,
        "geos": []
    }],
    "adTagCustomParamMap": [{
        "name": "kadcarrier",
        "macroValue": "techno.carrier"
    }, {
        "name": "kadcity",
        "macroValue": "geo.city"
    }],
    "nativeAdTagConfigMapping": {
        "nativeAdtagConfigId": 93

    }
}

Response

Response Body

           

Type
Description
ad tag object
JSON response of the successfully created ad tag

Sample Response for a Simple Ad Tag with a New Passback Placement and Custom Parameters


{
    "adTagName": "THIS_IS_TEST_DEMAND_5",
    "adTagId": 586930,
    "foldPlacementId": 1,
    "adTypeId": 1,
    "adSize": {
        "name": "300x250 - Sidekick",
        "width": 300,
        "height": 250,
        "categoryId": 1,
        "id": 9
    },
    "adCodeTypeId": 1,
    "platformId": 1,
    "adExpansionDirectionId": 1,
    "expansionDirection": "UP",
    "asoType": {
        "id": 3
    },
    "site": {
        "siteId": 11622,
        "publisherId": 2685,
        "siteUrl": "http://example.org",
        "monthlyImpressions": 10000000,
        "isDefault": false,
        "platformId": 1,
        "verticalId": 33,
        "microVerticalId": 33
    },
    "siteId": 11622,
    "publisherSiteurl": "http://example.org",
    "publisherId": 2685,
    "pagePlacementId": 1,
    "pagePlacement": "TOP_OF_PAGE",
    "adTagCustomParamMap": [{
        "name": "kadcarrier",
        "macroValue": "techno.carrier"
    }, {
        "name": "kadcity",
        "macroValue": "geo.city"
    }],
    "adTagScript": "<!-- PubMatic ad tag (Javascript) : THIS_IS_TEST_DEMAND_5 | http://example.org | 300 x 250 Sidekick -->\n<script type=\"text/javascript\">\n\t\tvar pubId=2685;\n\t\tvar siteId=11622;\n\t\tvar kadId=586930;\n\t\tvar kadwidth=300;\n\t\tvar kadheight=250;\n\t\tvar kadtype=1;\n\t\tvar kadcarrier= techno.carrier;\n\t\tvar kadcity= geo.city;\n\t\tvar kadpageurl = \"INSERT_ENCODED_PAGEURL_HERE\";\n</script>\n<script type=\"text/javascript\" src=\"http://ads.pubmatic.com/AdServer/js/showad.js\"></script>",
    "platform": "WEB",
    "adTagPlacements": [{
        "adTagId": 586930,
        "adTagName": "THIS_IS_TEST_DEMAND_5",
        "siteId": 11622,
        "adTagPlacementId": 829368,
        "placementId": 460186,
        "placementName": "passback_THIS_IS_TEST_DEMAND_5_586930",
        "platformId": 1,
        "adNetworkId": 165,
        "adNetworkName": "Publisher Passback 100% fill",
        "adNetworkTypeId": 1,
        "geos": [],
        "linkOnlyToGeo": false,
        "includeForInventorySet": [1, 2],
        "adNetworkType": "IN"
    }],
    "id": 586930
}

Sample Request for a Video Ad Tag with a New Passback Placement


{
    "adTagName": "vidwo_2685_1",
    "adTagId": 586931,
    "foldPlacementId": 0,
    "adTypeId": 13,
    "adSize": {
        "name": "Mobile - 480x60",
        "width": 480,
        "height": 60,
        "categoryId": 2,
        "id": 72
    },
    "adCodeTypeId": 2,
    "platformId": 5,
    "adExpansionDirectionId": 0,
    "expansionDirection": "UNKNOWN",
    "asoType": {
        "id": 3
    },
    "videoProperties": {
        "hasCompanion": false,
        "protocol": {
            "id": 2
        },
        "id": 6109,
        "minDuration": 0,
        "maxDuration": 120,
        "vpaidVersion": 2,
        "videoLinearity": 0,
        "videoPosition": 1,
        "videoPlayerHeight": 1,
        "videoPlayerWidth": 1,
        "videoMimeTypes": [1, 2, 3, 4, 5, 6, 7, 8]
    },
    "site": {
        "siteId": 81963,
        "publisherId": 2685,
        "siteUrl": "http://www.example.com/sports2",
        "monthlyImpressions": 10000000,
        "isDefault": false,
        "platformId": 5,
        "verticalId": 38,
        "microVerticalId": 38
    },
    "siteId": 81963,
    "publisherSiteurl": "http://www.example.com/sports2",
    "publisherId": 2685,
    "pagePlacementId": 6,
    "pagePlacement": "NOT_SURE",
    "adTagCustomParamMap": [{
        "name": "kadpageurl",
        "macroValue": "ddd"
    }],
    "adTagScript": "<!-- PubMatic ad tag (Mobile) : vidwo_2685_1 | http://www.example.com/sports2 | 480 x 60 480x60 -->\n<script type=\"text/javascript\" src=\"http://ads.pubmatic.com/AdServer/js/mshowad.js\"></script>\n<script type=\"text/javascript\">\tPubMatic.showAd({\n\t\t\"pubId\":2685,\n\t\t\"siteId\":81963,\n\t\t\"adId\":586931,\n\t\t\"width\":480,\n\t\t\"height\":60,\n\t\t\"kadpageurl\" : ddd,\n\t\t\"use_html5_location\": true\n\t});\n</script>",
    "platform": "MOBILE_APP_ANDROID",
    "adTagPlacements": [{
        "adTagId": 586931,
        "adTagName": "vidwo_2685_1",
        "siteId": 81963,
        "adTagPlacementId": 829369,
        "placementId": 460187,
        "placementName": "passback_vidwo_2685_1_586931",
        "platformId": 5,
        "adNetworkId": 1379,
        "adNetworkName": "Publisher Passback Android App 100% fill",
        "adNetworkTypeId": 1,
        "geos": [],
        "linkOnlyToGeo": false,
        "includeForInventorySet": [1, 2],
        "adNetworkType": "IN"
    }],
    "id": 586931
}

Sample Response for a Native Ad Tag with an Existing Passback Placement


{
    "adTagName": "example1_1x1_native_without_url_10",
    "adTagId": 586929,
    "foldPlacementId": 0,
    "adTypeId": 12,
    "adSize": {
        "name": "Native default size",
        "width": 1,
        "height": 1,
        "categoryId": 7,
        "id": 138
    },
    "adCodeTypeId": 1,
    "platformId": 1,
    "adExpansionDirectionId": 0,
    "expansionDirection": "UNKNOWN",
    "asoType": {
        "id": 3
    },
    "site": {
        "siteId": 81875,
        "publisherId": 2685,
        "siteUrl": "http://example.com",
        "monthlyImpressions": 10000,
        "isDefault": false,
        "platformId": 1,
        "verticalId": 10,
        "microVerticalId": 10
    },
    "siteId": 81875,
    "publisherSiteurl": "http://example.com",
    "publisherId": 2685,
    "pagePlacementId": 6,
    "pagePlacement": "NOT_SURE",
    "adTagCustomParamMap": [{
        "name": "kadcarrier",
        "macroValue": "techno.carrier"
    }, {
        "name": "kadcity",
        "macroValue": "geo.city"
    }],
    "adTagScript": "<!-- PubMatic ad tag (Javascript) : etsy1_1x1_native_without_url_10 | http://example.com | 1 x 1 Native default size -->\n<script type=\"text/javascript\">\n\t\tvar pubId=2685;\n\t\tvar siteId=81875;\n\t\tvar kadId=586929;\n\t\tvar kadwidth=1;\n\t\tvar kadheight=1;\n\t\tvar kadtype=12;\n\t\tvar pubnativeconfig = {\n\t\t\t\t nativeadslots : \"pubAdI_2685_001\"\n\t\t};\n\t\tvar kadcarrier= techno.carrier;\n\t\tvar kadcity= geo.city;\n\t\tvar kadpageurl = \"INSERT_ENCODED_PAGEURL_HERE\";\n</script>\n<script type=\"text/javascript\" src=\"http://ads.pubmatic.com/AdServer/js/nshowad.js\"></script>",
    "platform": "WEB",
    "adTagPlacements": [{
        "adTagId": 586929,
        "adTagName": "example1_1x1_native_without_url_10",
        "siteId": 81875,
        "adTagPlacementId": 829367,
        "placementId": 206843,
        "placementName": "Mocean_Tag Based AD net Native",
        "platformId": 1,
        "adNetworkId": 165,
        "adNetworkName": "Publisher Passback 100% fill",
        "adNetworkTypeId": 1,
        "geos": [],
        "linkOnlyToGeo": false,
        "includeForInventorySet": [1, 2],
        "adNetworkType": "IN"
    }],
    "nativeAdTagConfigMapping": {
        "adTagId": 586929,
        "publisherId": 2685,
        "nativeAdtagConfigId": 93
    },
    "id": 586929
}

Error Codes

                       

Error CodeError Description
PUB01_0012Invalid Ad tag Name.Tag name should not contain any special character other than \"_\" or \".\" or \"-\"
PUB01_0023Ad tag name should not contain more than 256 characters.
CC01_0002
Missing or invalid {parameter}.Please provide valid {parameter}.
PUB01_0005Ad Tag with same name already exists.

 

 

Retrieving List of Ad Tags

Overview

This API allows you to retrieve the list of ad tags associated with the publisher's account based on the filters provided by the user.

Request

         

URI

${URI_PREFIX}/inventorymgmt/publisherAdTag


Note: For sandbox testing, $URI_PREFIX should be replaced with "http://api-sandbox.pubmatic.com/v1".

 

For production, $URI_PREFIX should be replaced with "http://api.pubmatic.com/v1".
HTTP MethodGET

Request Headers

                        

Header Name
Type
Value
Required
Description
Content-Type
application/json
-
Yes
-
Authorization
String
Bearer ${access_token}
Yes
The access token generated for authentication should be sent in place of ${access_token}.
For more information about access tokens, refer to Getting Started with PubMatic APIs.

Request Query Parameters

                                                                  

Parameter NameTypeRequiredValidationsDescription
pubLongYesThis should be a valid Publisher ID present in the PubMatic platformID of the publisher associated with the list of ad tags which need to be retrieved.
siteLongNoMust be a valid site ID supported in the PubMatic systemID of the site associated with the list of ad tags which need to be retrieved.
adSizeIntegerNoMust be a valid ad size ID supported in the PubMatic systemID of the ad sizes associated with the list of ad tags which need to be retrieved.
adNetworkIdLongNoMust be a valid ad network ID supported in the PubMatic systemID of the ad network associated with the list of ad tags which need to be retrieved.
geoIdIntegerNoMust be a valid geo ID supported in the PubMatic systemID of the geo associated with the list of ad tags which need to be retrieved.
adTypeIntegerNoMust be a valid ad type ID supported in the PubMatic systemID of the ad types associated with the list of ad tags which need to be retrieved.
adTagNameStringNo Name of the ad tag which need to be retrieved.
trafficStatusStringNo Indicates whether the ad tag is receiving active traffic in the PubMatic platform or not. Valid values are "active" and "inactive".

Sample Request


${URI_PREFIX}/inventorymgmt/publisherAdTag?dimensions=modificationTime&filters=pub+eq+32702&filters=site+eq+54584

&filters=adSize+eq+1&filters=geoId+eq+79&filters=adType+eq+3&pageNumber=1&pageSize=10&sort=-modificationTime&trafficStatus=active

 

Response

Response Body

           

Type
Description
ad tag object
JSON response of the ad tag

Sample Response

{
    "adTagName": "kissanime_97VQ_728x90",
    "adTagId": 256280,
    "foldPlacement": {
        "id": 0,
        "name": "Unknown"
    },
    "adType": {
        "id": 3,
        "name": "TextAndImage",
        "displayName": "Banner/Rich Media"
    },
    "adSize": {
        "name": "Leaderboard-728X90",
        "width": 728,
        "height": 90,
        "categoryId": 0,
        "id": 7
    },
    "adcodeType": 1,
    "platformId": 1,
    "adExpansionDirectionId": 0,
    "asoType": {
        "id": 3
    },
    "refreshRate": 0,
    "site": {
        "publisherId": 0,
        "siteId": 73301,
        "siteUrl": "http://example.com",
        "isDefault": false,
        "monthlyImpressions": 0,
        "id": 73301,
        "name": "http://example.com"
    },
    "pub": {
        "publisherId": 32702,
        "id": 32702,
        "idAsString": "32702"
    },
    "deleted": 0,
    "prefetchEnabled": false,
    "creationTime": "2015-04-06 17:53:26",
    "defaultsHandlingThreshold": 4,
    "adPlacementId": 6,
    "dssTypeId": 0,
    "deviceTypeTargetingEnabled": 0,
    "state": 1,
    "modificationTime": "2015-04-06 17:53:26",
    "rtbSkipPercentage": 0,
    "geoLevel": 1,
    "defhandled": 0,
    "adNetworkId": 1067,
    "adNetworkCount": 1,
    "trafficStatus": {
        "id": 256280,
        "impressions": 1,
        "revenue": 0.00021
    },
    "adCodeType": "JAVASCRIPT",
    "adCodeName": "JavaScript",
    "id": 256280,
    "adtype": {
        "id": 3,
        "name": "TextAndImage",
        "displayName": "Banner/Rich Media"
    }
}

 

 

Retrieving Details of an Ad Tag

Overview

This API allows you to retrieve the details of a specific ad tag using its ID.

Request

         

URI

${URI_PREFIX}/inventorymgmt/publisherAdTag/{adTagId}


Note: For sandbox testing, $URI_PREFIX should be replaced with "http://api-sandbox.pubmatic.com/v1".

 

For production, $URI_PREFIX should be replaced with "http://api.pubmatic.com/v1".
HTTP MethodGET

Request Headers

                        

Header Name
Type
Value
Required
Description
Content-Type
application/json
-
Yes
-
Authorization
String
Bearer ${access_token}
Yes
The access token generated for authentication should be sent in place of ${access_token}.
For more information about access tokens, refer to Getting Started with PubMatic APIs.

Request Query Parameters

                 

Parameter
Type
Required
Validations
Description
entityId
Long
Yes
-
ID of the publisher for which the ad tag needs to be created.

Sample Request

URL: ${URI_PREFIX}/inventorymgmt/publisherAdTag/3683?entityId=2685

Response

Response Body

           

Type
Description
ad tag object
JSON response of the ad tag

Sample Response


{
    "adTagName": "Top Leaderboard",
    "adTagId": 3683,
    "foldPlacementId": 0,
    "adTypeId": 1,
    "adSize": {
        "name": "Leaderboard-728X90",
        "width": 728,
        "height": 90,
        "categoryId": 2,
        "id": 7
    },
    "adCodeTypeId": 0,
    "platformId": 1,
    "adExpansionDirectionId": 0,
    "expansionDirection": "UNKNOWN",
    "asoType": {
        "id": 3
    },
    "siteId": 2686,
    "publisherSiteurl": "https://john.blogspot.com",
    "pagePlacementId": 1,
    "pagePlacement": "TOP_OF_PAGE",
    "adTagCustomParamMap": [],
    "platform": "WEB",
    "id": 3683
}

Error Codes

               

Error CodeError Description
CC01_0002Missing or invalid entityId.Please provide valid entityId .
CC03_0001No records found

 

 

Updating an Ad Tag

Overview

This API allows you to update the details of an existing ad tag.

Request

         

URI

${URI_PREFIX}/inventorymgmt/publisherAdTag/{adTagId}


Note: For sandbox testing, $URI_PREFIX should be replaced with "http://api-sandbox.pubmatic.com/v1".

For production, $URI_PREFIX should be replaced with "http://api.pubmatic.com/v1".
HTTP MethodPUT

Request Headers

                        

Header Name
Type
Value
Required
Description
Content-Type
application/json
-
Yes
-
Authorization
String
Bearer ${access_token}
Yes
The access token generated for authentication should be sent in place of ${access_token}.
For more information about access tokens, refer to Getting Started with PubMatic APIs.

Request Query Parameters

                 

Parameter
Type
Required
Validations
Description
entityId
Long
Yes
-
ID of the publisher for which the ad tag needs to be updated.

Request Body

                                                                  

Body ParameterTypeRequiredValidationsDescription
adTagNameStringYes
  1. This is a mandatory field.
  2. Validated with regular expression.
  3. Cannot be same as existing ad tag's name
Name of the ad tag.
foldPlacementIdIntegerNo
  1. Must be a valid fold placement type supported in the PubMatic system.
  2. Default value for Fold Placement is 0 (for UNKNOWN).

Fold placement of the ad tag. Valid values are:

  • 0 - Unknown
  • 1 - Above The Fold
  • 2 - Below The Fold
  • 3 - Partially Above The Fold
 pagePlacementIdInteger No 
  1. Must be a valid page placement supported in the PubMatic system.
  2. Default value for Page Placement is 6 (for NOT_SURE).

Page placement of the new ad tag. Valid values are:

  • 1 - Top of Page
  • 2 - Bottom of Page
  • 3 - Middle of Page
  • 4 - Left of Page
  • 5 - Right of Page
  • 6 - Not Sure
adExpansionDirectionIdIntegerNo
  1. Must be a valid Ad expansion direction supported in the PubMatic system
  2. Default value for Ad Expansion Direction is 0 (for UNKNOWN).

Ad expansion direction of the new ad tag. Valid values are:

  • 0 - Unknown
  • 1 - Up
  • 2 - Down
  • 3 - Left
  • 4 - Right
adTagCustomParamMapList of ObjectsNo
  1. The Object of this field has name and macrovalue fields.
  2. For mandatory custom parameters, the default vale of the macrovalue is "".
  3. kadpageurl is a mandatory parameter if the platform of the ad tag is either Web,Mobile Web or Video.
  4. kadudid,kadudidtype and kadudidhash are required in case of Mobile App ad tag.
  5. kadloc and kadlocsource are required for Mobile App or Mobile Web ad tag.

Custom parameter definition for the new ad tag using key=value pattern.

Some of the custom parameters are mandatory while creating an ad tag depending upon the ad tag's platform and  ad type. If the publisher supports any of the following custom parameters,please provide corrosponding macroValue as it will be replaced in the ad script at runtime.

For example,


"adTagCustomParamMap": [{
"name": "kadcarrier",
"macroValue": "techno.carrier"
} ]

Valid values for the name field are:

  • kadloc - Location
  • kadstate - State
  • kadcity - City
  • kaddma - DMA
  • kadzip - Postal or Zip code
  • kadyob - Year of birth
  • kadnettype - Type of internet connection
  • kadcarrier - Mobile carrier
  • kadethnicity - Ethnicity
  • kadincome - Income
  • kadcountry - Country
  • kadkw
  • kadgender - Gender
  • kadudid - Mobile user device ID (UDID)
  • kadudidtype - UDID type
  • kadudidhash - UDID hashing algorithm
  • kappname - Mobile app name
  • kappstoreurl - Mobile app store URL
  • kaid - Mobile app ID
  • kbundle - Mobile app bundle ID
  • kcat - Category
  • kapi
  • kadfloor - Floor value
  • authToken
  • targetedDimensions
  • videoPlayerVendor - Video player vendor supported
  • videoPlayerTechnology - Video player technology supported
  • videoFileFormats - Video file format supported
  • kadpageurl - Page URL of the impression
asoTypeObjectNo
  1. This is a mandatory field.
  2. id field is mandatory in this object.
  3. Default value for asoType is 3.

Indicates whether geo targetting for this new ad tag should be enabled or disabled.

Valid values for asoType.id field are:

  • 3 - No Geo targetting
  • 4 - Enable Geo targetting

For example,


"asoType": {
"id": 3
}
videoPropertiesObjectNoThis Object is required while updating a Video ad tag

Details of the video configuration to be associated with a Video ad tag. For description of the fields present in this object, refer the VideoProperties table.

nativeAdTagConfigMappingObjectNo
  1. This Object is required while creating a Native ad tag.
  2. nativeAdtagConfigId field is required and this ID must be already registered in the PubMatic system.

Details of the native configuration to be associated with a Native ad tag. nativeAdtagConfigId indicates the ID of the native template which needs to be associated with the ad tag.

For example,


"nativeAdTagConfigMapping": {
"nativeAdtagConfigId": 93
}

Sample Request for Banner Ad Tag


{
    "publisherId": 2685,
    "publisherSiteurl": "http://pubmatic.com/test",
    "asoType": {
        "id": 3
    },
    "platformId": 1,
    "siteId": 152847,
    "adTagName": "pubmatic_980x15",
    "adCodeTypeId": 1,
    "foldPlacementId": 0,
    "adTypeId": 3,
    "pagePlacementId": 6,
    "adExpansionDirectionId": 0,
    "adSize": {
        "name": "Super Leaderboard",
        "width": 980,
        "height": 150,
        "categoryId": 2,
        "id": 111
    },
    "adTagCustomParamMap": [{
        "name": "kadpageurl",
        "macroValue": ""
    }]
}

Sample Request for Video Ad Tag


{
    "publisherId": 2685,
    "publisherSiteurl": "http://google.com/home",
    "asoType": {
        "id": 3
    },
    "platformId": 1,
    "siteId": 103754,
    "adTagName": "try_sec_hascompanion1",
    "adCodeTypeId": 3,
    "foldPlacementId": 0,
    "adTypeId": 13,
    "pagePlacementId": 6,
    "adExpansionDirectionId": 0,
    "adSize": {
        "name": "Video N/A",
        "width": 0,
        "height": 0,
        "categoryId": 6,
        "id": 97
    },
    "adTagCustomParamMap": [{
        "name": "kadpageurl",
        "macroValue": ""
    }],
    "videoProperties": {
        "hasCompanion": false,
        "protocol": {
            "id": 2
        },
        "hasVpaidSupport": true,
        "minDuration": 9,
        "maxDuration": 78,
        "vpaidVersion": 1,
        "videoLinearity": 0,
        "videoPosition": 1,
        "videoMimeTypes": [
            1,
            2,
            3,
            4,
            5,
            6,
            7,
            8
        ]
    }
}

Response

Response Body

           

Type
Description
ad tag object
JSON response of the successfully updated ad tag

Sample Response for Banner Ad Tag


{
    "adTagName": "pubmatic_980x125",
    "adTagId": 769225,
    "foldPlacementId": 0,
    "adTypeId": 3,
    "adSize": {
        "name": "Super Leaderboard",
        "width": 980,
        "height": 150,
        "categoryId": 2,
        "id": 111
    },
    "adCodeTypeId": 1,
    "platformId": 1,
    "adExpansionDirectionId": 0,
    "expansionDirection": "UNKNOWN",
    "asoType": {
        "id": 3
    },
    "site": {
        "siteId": 152847,
        "publisherId": 2685,
        "siteUrl": "http://pubmatic.com/test",
        "monthlyImpressions": 10000,
        "isDefault": false,
        "platformId": 1,
        "verticalId": 1,
        "microVerticalId": 1
    },
    "siteId": 152847,
    "publisherSiteurl": "http://pubmatic.com/test",
    "publisherId": 2685,
    "pagePlacementId": 6,
    "pagePlacement": "NOT_SURE",
    "adTagCustomParamMap": [{
        "name": "kadpageurl",
        "macroValue": ""
    }],
    "adTagScript": "<!-- PubMatic ad tag (Javascript) : pubmatic_980x125 | http://pubmatic.com/test | 980 x 150 Super Leaderboard -->\n<script type=\"text/javascript\">\n\t\tvar pubId=2685;\n\t\tvar siteId=152847;\n\t\tvar kadId=769225;\n\t\tvar kadwidth=980;\n\t\tvar kadheight=150;\n\t\tvar kadtype=1;\n\t\tvar kadpageurl = \"INSERT_ENCODED_PAGEURL_HERE\";\n</script>\n<script type=\"text/javascript\" src=\"http://ads.pubmatic.com/AdServer/js/showad.js\"></script>",
    "platform": "WEB",
    "id": 769225
}

Sample Response for Video Ad Tag


{
    "adTagName": "try_sec_hascompanion2",
    "adTagId": 772572,
    "foldPlacementId": 0,
    "adTypeId": 13,
    "adSize": {
        "name": "Video N/A",
        "width": 0,
        "height": 0,
        "categoryId": 6,
        "id": 97
    },
    "adCodeTypeId": 3,
    "platformId": 1,
    "adExpansionDirectionId": 0,
    "expansionDirection": "UNKNOWN",
    "asoType": {
        "id": 3
    },
    "videoProperties": {
        "hasCompanion": false,
        "protocol": {
            "id": 2
        },
        "id": 7563,
        "minDuration": 9,
        "maxDuration": 78,
        "vpaidVersion": 1,
        "videoLinearity": 0,
        "videoPosition": 1,
        "videoPlayerHeight": 0,
        "videoPlayerWidth": 0,
        "videoMimeTypes": [
            1,
            2,
            3,
            4,
            5,
            6,
            7,
            8
        ]
    },
    "site": {
        "siteId": 103754,
        "publisherId": 2685,
        "siteUrl": "http://google.com/home",
        "monthlyImpressions": 1000,
        "isDefault": false,
        "platformId": 1,
        "verticalId": 10,
        "microVerticalId": 10
    },
    "siteId": 103754,
    "publisherSiteurl": "http://google.com/home",
    "publisherId": 2685,
    "pagePlacementId": 6,
    "pagePlacement": "NOT_SURE",
    "adTagCustomParamMap": [{
        "name": "kadpageurl",
        "macroValue": ""
    }],
    "adTagScript": "http://vpaid.pubmatic.com/ads/video/vadtag.html?adtype=13&pubId=2685&siteId=103754&adId=772572&vadFmt=2&vminl=9&vmaxl=78&vpos=1&vh=PLAYER_HEIGHT&vw=PLAYER_WIDTH&vfmt=1+2+3+4+5+6+7+8&kadpageurl=INSERT_ENCODED_PAGEURL_HERE",
    "platform": "WEB",
    "id": 772572
}

 

Deleting an Ad Tag

Overview

This API allows you to delete a specific ad tag from the PubMatic platform using its ID.

Request

         

URI

${URI_PREFIX}/inventorymgmt/publisherAdTag/{adTagId}


Note: For sandbox testing, $URI_PREFIX should be replaced with "http://api-sandbox.pubmatic.com/v1".

 

For production, $URI_PREFIX should be replaced with "http://api.pubmatic.com/v1".
HTTP MethodDELETE

Request Headers

                        

Header Name
Type
Value
Required
Description
Content-Type
application/json
-
Yes
-
Authorization
String
Bearer ${access_token}
Yes
The access token generated for authentication should be sent in place of ${access_token}.
For more information about access tokens, refer to Getting Started with PubMatic APIs.

Request Query Parameters

                 

Parameter
Type
Required
Validations
Description
entityId
Long
Yes
-
ID of the publisher for which the ad tag needs to be deleted.

Sample Request

URL: ${URI_PREFIX}/inventorymgmt/publisherAdTag/3683?pubId=2685

Response

Response Body

           

Type
Description
ad tag object
JSON response of the successfully deleted ad tag

Sample Response


[{
    "adTagName": "Top Leaderboard Mukul",
    "adTagId": 3683,
    "foldPlacementId": 0,
    "adTypeId": 1,
    "adSize": {
        "name": "Leaderboard-728X90",
        "width": 728,
        "height": 90,
        "categoryId": 2,
        "id": 7
    },
    "adCodeTypeId": 0,
    "platformId": 1,
    "adExpansionDirectionId": 0,
    "expansionDirection": "UNKNOWN",
    "asoType": {
        "id": 3
    },
    "siteId": 2686,
    "publisherSiteurl": "https://john.blogspot.com",
    "publisherId": 2685,
    "pagePlacementId": 1,
    "pagePlacement": "TOP_OF_PAGE",
    "platform": "WEB",
    "id": 3683
}]

 

Deleting Multiple Ad Tags

Overview

This API allows you to delete multiple ad tags from the PubMatic platform using the publisher ID and a comma-separated list of ad tag IDs. 

Request

         

URI

${URI_PREFIX}/inventorymgmt/publisherAdTag


Note: For sandbox testing, $URI_PREFIX should be replaced with "http://api-sandbox.pubmatic.com/v1".

For production, $URI_PREFIX should be replaced with "http://api.pubmatic.com/v1".
HTTP MethodDELETE

Request Headers

                        

Header Name
Type
Value
Required
Description
Content-Type
application/json
-
Yes
-
Authorization
String
Bearer ${access_token}
Yes
The access token generated for authentication should be sent in place of ${access_token}.
For more information about access tokens, refer to Getting Started with PubMatic APIs.

Request Query Parameters

                        

Parameter NameTypeRequiredValidationsDescription
pubIdLongYes ID of the publisher whose ad tags need to be deleted.
adTagIdStringYes Comma-separated list of ad tag IDs which need to be deleted.

Sample Request

URL: ${URI_PREFIX}/inventorymgmt/publisherAdTag?adTagId=586732,586731&pubId=41809

Response

Response Body

           

Type
Description
ad tag object
JSON response of the successfully deleted ad tags

Sample Response

{
    "metaData": {
        "Total AdTags Deleted successfully ": 2,
        "Total AdTags to delete": 2
    },
    "items": [{
        "adTagName": "itunes_728x90_12",
        "adTagId": 586732,
        "foldPlacementId": 0,
        "adTypeId": 3,
        "adSize": {
            "name": "Leaderboard-728X90",
            "width": 728,
            "height": 90,
            "categoryId": 2,
            "id": 7
        },
        "adCodeTypeId": 1,
        "platformId": 4,
        "adExpansionDirectionId": 0,
        "expansionDirection": "UNKNOWN",
        "asoType": {
            "id": 3
        },
        "siteId": 41810,
        "publisherSiteurl": "https://itunes.apple.com/us/app/pubmatic-myreports/id577809796?mt=8",
        "publisherId": 41809,
        "pagePlacementId": 6,
        "pagePlacement": "NOT_SURE",
        "platform": "MOBILE_APP_IOS",
        "id": 586732
    }, {
        "adTagName": "itunes_728x90",
        "adTagId": 586731,
        "foldPlacementId": 0,
        "adTypeId": 3,
        "adSize": {
            "name": "Leaderboard-728X90",
            "width": 728,
            "height": 90,
            "categoryId": 2,
            "id": 7
        },
        "adCodeTypeId": 1,
        "platformId": 4,
        "adExpansionDirectionId": 0,
        "expansionDirection": "UNKNOWN",
        "asoType": {
            "id": 3
        },
        "siteId": 41810,
        "publisherSiteurl": "https://itunes.apple.com/us/app/pubmatic-myreports/id577809796?mt=8",
        "publisherId": 41809,
        "pagePlacementId": 6,
        "pagePlacement": "NOT_SURE",
        "platform": "MOBILE_APP_IOS",
        "id": 586731
    }]
}

Attachments

    Outcomes