Ad Unit API (UAS)

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

Description

Unified Ad Server Ad Unit API enables you to create, update and archive single Ad Units.

For more information about UAS Inventory Management Services APIs, refer to Inventory Management Services (UAS) 

   

 

Service Name: /adunits/

                                             

Method PathHTTP Method TypeDescriptionLink to Definition
/adunitsPOSTCreate an Ad Unit in the PubMatic system.Create an Ad Unit
/adunits/{id}GETRetrieve the details of a specific Ad Unit for the requested Ad Unit ID. Retrieve details for a specific Ad Unit
/adunits/GET

Retrieve the list of Ad Units associated with your account. This provides the ability to apply supported dimensions by Ad Unit, filters and sorting options to fetch a list of Ad Units with a specific set of details according to your requirements. 

Retrieve a List of Ad Units
https://api.pubmatic.com/v1/uas/adunits?dimensions=id,code,name,status,adSizes&sort=id&filters=id eq <specify adunit ids>GET

Retrieve a list that matches specified dimensions and filters

Generic Search
/adunits/{id}PUT

This API method updates a single Ad Unit. 

This method will do a full update. If the request does not contain a value for an attribute, it will be either set to NULL or the default value. However, if the parameter is mandatory, the Ad Unit will not be updated. Ensure that all required attributes are being passed with required attributes.

Update an Ad Unit
/adunits/{id}PATCH

This API method performs a partial update on an object. e.g., Partial update to change the status of a line item.

Currently, it is used for updating the description, status, parent, target window, refresh rate, coppa compliant, and keywords.

Note: This is different than PUT. In a PUT, a full replacement of the object takes place.

Update (Patch) an Ad Unit
/adunits/{id}DELETEThis API method archives an Ad Unit. An archived unit will not be used in Ad Serving.Delete an Ad Unit

 

Create an Ad Unit

 

Overview

This API enables you to create an Ad Unit in PubMatic. On the backend, while creating an Ad Unit the service will create an SSP Site and SSP Ad Tag which will be mapped to the created Ad Unit.

 

You will get the SSP site Id and SSP Ad Tag Id in the response.

Request

           

Request Headers

                        

Header nameType ValueRequiredDescription
Content-TypeStringapplication/jsonYesMedia type for request.
pubTokenString${access_token}Yes

Publisher Token to authenticate and authorize the user calling the Unified Ad Server API. Send the access token generated for authentication at the place of ${access_token} in the request.

 

For more information about access tokens, refer to Getting Started with PubMatic APIs.

Request Body Parameters

                                                                                                                                        

Parameter NameTypeRequiredValidationsDescription
nameStringYes

Name can be of maximum 255 characters consisting of letters, numbers, dashes, hyphens, periods, asterisks, and colons.

Name should be unique for your account.
Ad Unit Name. Name should be descriptive. Example:  Homepage_Sidebar_BTF2_300x250
descriptionStringNo

Maximum 1024 characters.

Default is null.

Description is used to provide more details about the Ad Unit.
statusNumericNo

Status should be valid and exists.

Default is “Active” for newly created ad unit if not provided.

Ad Unit Status.

Refer to Status API for a list of statuses.

The following statuses are supported for an Ad Unit:

1=Active
2=Inactive
4=Archived
parentNumericNo
A child can be added in a multilevel hierarchy up to 5 levels

Ad Units can have a single Parent. An ad unit with no parent is assumed to be a network-level ad unit.
targetWindowStringNo

Target_window can be of maximum of 16 characters.

Only “_blank” and “top” are allowed.

Default is “_blank”

Target window is used to indicate where to open a page if user performs a URL click action.

_blank = Opens the linked URL in a new window or tab

_top =  Opens the linked URL in the full body of the window

Note: This parameter is for future use and is currently not used in the system
refreshRateNumericNoShould be in the range of 15 to 120 seconds.

Refresh rate will be used when sending an ad request in a specified interval.

Note: This parameter is for future use and is currently not used in the system.
coppaCompliantBooleanNoDefault is false
Should be true if your inventory is COPPA (Children’s Online Privacy Protection Act) compliant. 
adSizesJSON Array of IntegerYesIdentifiers representing ad sizes. (Should already exist in the system.)

Supported ad sizes for the ad unit.

 

This is a mandatory parameter for a banner type of AdUnit.

adUnitGroupsJSON Array of IntegerNoIdentifiers representing ad groups. (Should already exist in the system.)

Ad group is grouping of ad units.

Note: To remove associated ad unit groups, pass an empty array, i.e., [ ]

To create/edit/retrieve a list of Ad Unit Groups, use Ad Unit Groups APIs
adUnitFormatsJSON Array of IntegerYesIdentifiers representing ad unit formats. (Should already exist in the system.)

Ad format supported by ad unit.

To retrieve a list of Ad Unit Formats using Ad Unit Format APIs

accountNumericYesAccount of the publisher for which this ad unit is created.Account of the Publisher
frequencyCapNumericNoFrequency should be valid.Frequency cap of the Ad Unit
nativeConfigList of Native Template Config OptionsNo (unless ad unit contains Native Ad Unit format)If ad unit format contains a Native ad unit format, then nativeConfig is mandatory in the request.

Native Config contains native templates.

To create/edit/retrieve a list of Native Config details, refer to Native APIs.
videoConfigVideo Config Object
No (unless ad unit contains video ad unit format)

If ad unit format contains video ad unit format, then video config is mandatory in the request.

VideoConfig contains various video attributes.

The additional inventory attributes (SkippableOffset, minDuration, maxDuration, autoPlay, companionAdSizes, playerSizes ) is recommended as it may increase the auction bid. Additional attributes are not considered in delivery of creative on Guaranteed inventory.

Example:

    

"videoConfig": {
   "id": 153,
   "protocol": {
     "id": 2
   },
   "vpaid": {
     "id": 0
   },
   "skippableOffset": 5,
   "minDuration": 15,
   "maxDuration": 15,
   "autoPlay": false,
   "companionAdSizes": [],
   "playerSizes": [
     {
       "id": 198
     }
   ]
}
iabCategoriesList of IAB Categories ObjectYes

There should be exactly one Primary IAB Category and at most 3 (but at least 1) Secondary IAB categories associated with Ad Unit.
 

The 0th index category id will be primary category, which is mandatory. In given example (below) id:279 will be primary category and rest will be secondary category which is optional.

IAB Category of Ad Unit.

Example:

    

"iabCategories": [{
       "id": 279
    }, {
        "id": 291
    }, {
        "id": 288
    }, {
        "id": 194
    }]
labelsList of label ObjectNo

Label should be valid and exist in system.

Only Ad Exclusion label should be valid for ad unit, Not Competitive Exclusion.

Labels applied on Ad Unit.

To create/edit/retrieve list of Labels, use Label Exclusion API.

You can use the field "excluded" along with "id" if you want to remove the inherited label for present Ad Unit. eg. "excluded": 1.

Note: To remove associated labels, pass an empty array i.e. [ ]. Only inherited labels (if any) will be associated.
userNumericYes
User ID of the user who is creating/updating/retrieving this Ad unit.

User ID of User.

To create/edit/retrieve a list of Operational User details, refer to User API

supportsDynamicSize' flag is no longer supported at the AdUnit level.

     

Video Configuration Dimension

Video configuration attributes are mandatory when Ad Unit expected to support Video Ad Format else not. Following are list attributes user has to provide with valid values while creating / updating the Ad Unit.

 

UAS ad server can accept the video parameters in the ad request too and in this case UAS ad server gives higher preference to parameter received in the request and retrieves missing parameter details from video configuration provided at Ad unit Level.

Important note: Ad Server consider protocol and vpaid parameter only while filtering the Guaranteed video redirect creative. All parameter will get pass to programmatic channel to get better monetization from Video DSP.

Parameter Name/DimensionsTypeRequiredValidationsDescription
protocolNumericYesShould be valid and exist in the system

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

IDName
2VAST 2.0
3VAST 3.0

The list of support video protocols can be retrieved using the Common Video Protocol API.

vpaidNumericYesShould be valid and exist in the system.

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

IDName
0No VPAID support
1VPAID 1.0
2VPAID 2.0
videoMimeTypesJSON array of integerYesShould be a valid list of support mime types and exist in the system.

Supported Video Mime Types:

IDName
1mp4
2swf
3wmv
4H.264
5webm
6JavaScript
7ogg
8fav
companionAdSupportedBooleanYesTrue if supports companion Ad; else false.True if supplied video inventory has support for companion Ads.
playerSizesJSON array of integerYesShould be valid and exist in the systemYou can retrieve the supported sizes using Size API for video Ad Unit Format.
skippableOffsetNumericNo

If provided, should be in range of 1-5.

If not passed, considered as inventory is not skippable.

 

minDuration

maxDuration

NumericYes

Should be positive.

Max should be greater than equal Minimum duration.

Video minimum and maximum duration in secons.
autoPlayBooleanYesTrue if supports autoplay; else false.If inventory supports auto play video creatives.

 

 

 

Sample Request URL

https://api.pubmatic.com/v1/uas/adunits/ 

Sample JSON Request

    

{
    "account": {
        "id": 118385
    },
    "name": "US_Mobile_Sports_All_Formats",
    "description": "Geo:US, Source:Mobile, Category:Sport, Type:Banner",
    "parent": {
        "id": null
    },
    "adUnitGroups": [{
        "id": 54
    }],
    "supportsDynamicSize": false,
    "adSizes": [{
        "id": 31
    }, {
        "id": 54
    }, {
        "id": 55
    }],
    "adUnitFormats": [{
        "id": 3
    }, {
        "id": 12
    }, {
        "id": 13
    }],
    "iabCategories": [{
        "id": 279
    }, {
        "id": 291
    }, {
        "id": 288
    }, {
        "id": 194
    }],
    "labels": [{
        "id": 30,
        "isInherited": false
    }],
    "videoConfig": {
        "minDuration": 15,
        "maxDuration": 15,
        "skippableOffset": 5,
        "autoPlay": false,
        "companionAdSizes": [],
        "playerSizes": [{
            "id": 198
        }],
        "protocol": {
            "id": 2
        },
        "vpaid": {
            "id": 0
        }
    },
    "nativeConfig": {
        "templates": [{
            "id": 242
        }]
    },
    "frequencyCaps": [{
        "frequencyCapPeriod": {
            "id": 2
        },
        "periodValue": 1,
        "capValue": 1
    }, {
        "frequencyCapPeriod": {
            "id": 3
        },
        "periodValue": 1,
        "capValue": 3
    }],
    "status": {
        "id": 1
    },
    "coppaCompliant": false,
    "targetWindow": "_blank",
    "refreshRate": null
}

Response

Sample Response JSON

    

{
  "id": 896,
  "account": {
    "id": 118385,
    "url": "http://api.pubmatic.com/v1/uas/"
  },
  "name": "US_Mobile_Sports_All_Formats",
  "description": "Geo:US, Source:Mobile, Category:Sport, Type:Banner",
  "status": {
    "id": 1,
    "name": "Active",
    "url": "http://api.pubmatic.com/v1/uas/status/1"
  },
  "targetWindow": "_blank",
  "coppaCompliant": false,
  "supportsDynamicSize": false,
  "user": {
    "id": 18312,
    "url": "http://api.pubmatic.com/v1/uas/users/18312"
  },
  "adSizes": [
    {
      "id": 31
    },
    {
      "id": 54
    },
    {
      "id": 55
    }
  ],
  "adUnitGroups": [
    {
      "id": 54
    }
  ],
  "adUnitFormats": [
    {
      "id": 3
    },
    {
      "id": 12
    },
    {
      "id": 13
    }
  ],
  "frequencyCaps": [
    {
      "frequencyCapPeriod": {
        "id": 2
      },
      "capValue": 1,
      "periodValue": 1
    },
    {
      "frequencyCapPeriod": {
        "id": 3
      },
      "capValue": 3,
      "periodValue": 1
    }
  ],
  "iabCategories": [
    {
      "id": 194
    },
    {
      "id": 279
    },
    {
      "id": 288
    },
    {
      "id": 291
    }
  ],
  "labels": [
    {
      "id": 30,
      "name": "Test_exclusion_Ad_001",
      "account": {
        "id": 118385
      },
      "labelType": {
        "id": 1,
        "name": "Ad Exclusion"
      },
      "isInherited": false
    }
  ],
  "sspSite": {
    "id": 119108
  },
  "sspAdTag": {
    "id": 418992
  },
  "videoConfig": {
             "id": 153,
             "protocol": {
                 "id": 2
             },
             "vpaid": {
                 "id": 0
             },
             "companionAdSupported": false,
             "skippableOffset": 5,
             "minDuration": 15,
             "maxDuration": 15,
             "autoPlay": false,
             "companionAdSizes": [],
             "playerSizes": [{
                 "id": 198
             }],
             "videoMimeTypes": [{
                 "id": 1
             }, {
                 "id": 2
             }, {
                 "id": 3
             }, {
                 "id": 4
             }, {
                 "id": 6
             }, {
                 "id": 8
             }]
  },
  "nativeConfig": {
    "templates": [
      {
        "id": 242,
        "name": "Sports_News_Mobile"
      }
    ]
  }
}

Retrieve details for a specific Ad Unit

 

Overview

This API enables you to retrieve the details of a specific Ad Unit for the requested Ad Unit Id.

Request

           

Request Headers

                        

Header nameType ValueRequiredDescription
Content-TypeStringapplication/jsonYesMedia type for request.
pubTokenString${access_token}Yes

Publisher Token to authenticate and authorize the user calling the Unified Ad Server API. Send the access token generated for authentication at the place of ${access_token} in the request.

 

For more information about access tokens, refer to Getting Started with PubMatic APIs.

Sample Request URL

https://api.pubmatic.com/v1/uas/adunits/896 

Response

Sample Response JSON

    

{
    "id": 896,
    "account": {
        "id": 118385,
        "url": "http://api.pubmatic.com/v1/uas/"
    },
    "name": "US_Mobile_Sports_All_Formats-New",
    "description": "Geo:US, Source:Mobile, Category:Sport, Type:Banner, Video, Native",
    "status": {
        "id": 1,
        "name": "Active",
        "url": "http://api.pubmatic.com/v1/uas/status/1"
    },
    "targetWindow": "_blank",
    "coppaCompliant": true,
    "supportsDynamicSize": false,
    "user": {
        "id": 1,
        "url": "http://api.pubmatic.com/v1/uas/users/1"
    },
    "adSizes": [{
        "id": 31
    }, {
        "id": 54
    }],
    "adUnitGroups": [{
        "id": 54
    }],
    "adUnitFormats": [{
        "id": 3
    }, {
        "id": 12
    }, {
        "id": 13
    }],
    "frequencyCaps": [{
        "frequencyCapPeriod": {
            "id": 2
        },
        "capValue": 1,
        "periodValue": 1
    }, {
        "frequencyCapPeriod": {
            "id": 3
        },
        "capValue": 3,
        "periodValue": 1
    }],
    "iabCategories": [{
        "id": 194
    }, {
        "id": 279
    }, {
        "id": 288
    }, {
        "id": 291
    }],
    "labels": [{
        "id": 30,
        "name": "Test_exclusion_Ad_001",
        "account": {
            "id": 118385
        },
        "labelType": {
            "id": 1,
            "name": "Ad Exclusion"
        },
        "isInherited": false
    }],
    "sspSite": {
        "id": 119108
    },
    "sspAdTag": {
        "id": 418992
    },
   "videoConfig": {
             "id": 153,
             "protocol": {
                 "id": 2
             },
             "vpaid": {
                 "id": 0
             },
             "companionAdSupported": false,
             "skippableOffset": 5,
             "minDuration": 15,
             "maxDuration": 15,
             "autoPlay": false,
             "companionAdSizes": [],
             "playerSizes": [{
                 "id": 198
             }],
             "videoMimeTypes": [{
                 "id": 1
             }, {
                 "id": 2
             }, {
                 "id": 3
             }, {
                 "id": 4
             }, {
                 "id": 6
             }, {
                 "id": 8
             }]
     },
    "nativeConfig": {
        "templates": [{
            "id": 242,
            "name": "Sports_News_Mobile"
        }]
    }
}

Retrieve a List of Ad Units

 

Overview

This API enables you to retrieve a full list of Ad Units associated with your Account. In the query, you can also apply supported dimensions, filters and sorting options to retrieve a list of Ad Units with a specific set of details according to your requirements.

Request

           

Request Headers

                        

Header nameType ValueRequiredDescription
Content-TypeStringapplication/jsonYesMedia type for request.
pubTokenString${access_token}Yes

Publisher Token to authenticate and authorize the user calling the Unified Ad Server API. Send the access token generated for authentication at the place of ${access_token} in the request.

 

For more information about access tokens, refer to Getting Started with PubMatic APIs.

Sample Request URL

https://api.pubmatic.com/v1/uas/adunits/ 

Response

Sample Response JSON

    

This will return all ad units associated with your account.

Generic Search

Filter Parameter NameTypeRequiredValidationsDescription
adSizesNumericNoN/A

This filter will return a list of Banner/Rich Media as well as Video Player Sizes mapped to Ad Unit.

This filter parameter will also search for specific player sizes for the ad units mapped to Video Ad Unit Format.

Refer to "Filters" for more information.

Request

 

Sample Request

https://api.pubmatic.com/v1/uas/adunits?dimensions=id,code,name,status,adSizes&sort=id&filters=id eq 10000001

 

Query ParameterTypeRequiredValidationsDescription
parentInformationRequiredBooleanNo

Default - false.

1. Allowed values are "true" or "false."

If true, API will return all hierarchy of parent Ad units.

Response will contain key as parentAdUnitPath

listChildrenBooleanNo

Default - false.

1. Allowed values are "true" or "false."

If true, API will return hierarchy of children Ad units.

Response will contain key as children object with id, name, status and url attribute for every children.

E.g. For given ad unit following is children hierarchy at different level.

"children": [{
    "id": 10000000,
    "name": "AdUnit_10000000",
    "url": "http://api.pubmatic.com/v1/uas/adunits/110000000",
    "status": {
        "id": 1
    },
    "children": [{
        "id": 10000002,
        "name": "AdUnit_10000002",
        "url": "http://api.pubmatic.com/v1/uas/adunits/10000002",
        "status": {
            "id": 1
        },
        "children": [{
            "id": 10000003,
            "name": "AdUnit_10000003",
            "url": "http://api.pubmatic.com/v1/uas/adunits/10000003",
            "status": {
                "id": 1
            }
        }]
    }]
}]
childLevelIntegerNo

Default value = 1

Possible values are 1 to 5

API will return hierarchy of children Ad Units till specified childLevel.

 

If user specified "childLevel" query parameter without "listChildren" parameter or listChildren=false in the request, API will return an error. Please check the error code.

 

Sample Response

It will return all ad units associated with your account.

 

Update an Ad Unit

 

Overview

This API enables you to update a single Ad Unit.

Note:

  • Ad Unit Code, Account Id and User Id are read-only fields and will not be available for update.
  • When you update name or IAB Categories in anAd Unit, the corresponding URL/name or IAB Categories will be updated in SSP Site and SSP AdTag respectively on the backend.

Request

           

Request Headers

                        

Header nameType ValueRequiredDescription
Content-TypeStringapplication/jsonYesMedia type for request.
pubTokenString${access_token}Yes

Publisher Token to authenticate and authorize the user calling the Unified Ad Server API. Send the access token generated for authentication at the place of ${access_token} in the request.

 

For more information about access tokens, refer to Getting Started with PubMatic APIs.

 

Request Body Parameters

                                                                                                                                        

Parameter NameTypeRequiredValidationsDescription
nameStringYes

Name can be of maximum 255 characters consisting of letters, numbers, dashes, hyphens, periods, asterisks, and colons.

Name should be unique for your account.
Ad Unit Name. Name should be descriptive. Example:  Homepage_Sidebar_BTF2_300x250
descriptionStringNo

Maximum 1024 characters.

Default is null.

Description is used to provide more details about the Ad Unit.
statusNumericNo

Status should be valid and exists.

Default is “Active” for newly created ad unit if not provided.

Ad Unit Status.

Refer to Status API for a list of statuses.

The following statuses are supported for an Ad Unit:

1=Active
2=Inactive
4=Archived
parentNumericNo
A child can be added in a multilevel hierarchy up to 5 levels

Ad Units can have a single Parent. An ad unit with no parent is assumed to be a network-level ad unit.
targetWindowStringNo

Target_window can be of maximum of 16 characters.

Only “_blank” and “top” are allowed.

Default is “_blank”

Target window is used to indicate where to open a page if user performs a URL click action.

_blank = Opens the linked URL in a new window or tab

_top = Opens the linked URL in the full body of the window

Note: This parameter is for future use and is currently not used in the system
refreshRateNumericNoShould be in the range of 15 to 120 seconds.

Refresh rate will be used when sending an ad request in a specified interval.

Note: This parameter is for future use and is currently not used in the system.
coppaCompliantBooleanNoDefault is false
Should be true if your inventory is COPPA (Children’s Online Privacy Protection Act) compliant. 
adSizesJSON Array of IntegerYesIdentifiers representing ad sizes. (Should already exist in the system.)

Supported ad sizes for the ad unit.

This is a mandatory parameter for banner type of AdUnit.

adUnitGroupsJSON Array of IntegerNoIdentifiers representing ad groups. (Should already exist in the system.)

Ad group is grouping of ad units.

Note: To remove associated ad unit groups, pass an empty array, i.e., [ ]

To create/edit/retrieve a list of Ad Unit Groups, use Ad Unit Groups APIs
adUnitFormatsJSON Array of IntegerYesIdentifiers representing ad unit formats. (Should already exist in the system.)

Ad format supported by ad unit.

To retrieve a list of Ad Unit Formats using Ad Unit Format APIs

accountNumericYesAccount of publisher for which this ad unit is createdAccount of the Publisher
frequencyCapNumericNoFrequency should be valid.Frequency cap of the Ad Unit
nativeConfigList of Native Template Config OptionsNo (unless ad unit contains Native Ad Unit format)If ad unit format contains a Native ad unit format, then nativeConfig is mandatory in the request.

Native Config contains native templates.

To create/edit/retrieve a list of Native Config details, refer to Native APIs.
videoConfigVideo Config Object
No (unless ad unit contains video ad unit format)

If ad unit format contains video ad unit format, then video config is mandatory in the request.

VideoConfig contains various video attributes.

The additional inventory attributes (SkippableOffset, minDuration, maxDuration, autoPlay, companionAdSizes, playerSizes ) is recommended as it may increase the auction bid. Additional attributes are not considered in delivery of creative on Guaranteed inventory.

Example:

    

"videoConfig": {
   "id": 153,
   "protocol": {
     "id": 2
   },
   "vpaid": {
     "id": 0
   },
   "skippableOffset": 5,
   "minDuration": 15,
   "maxDuration": 15,
   "autoPlay": false,
   "companionAdSizes": [],
   "playerSizes": [
     {
       "id": 198
     }
   ]
}
 
iabCategoriesList of IAB Categories ObjectYes

There should be exactly one Primary IAB Category and at most 3 (but at least 1) Secondary IAB categories associated with Ad Unit.
 

The 0th index category id will be primary category, which is mandatory. In given example (below) id:279 will be primary category and rest will be secondary category which is optional.

IAB Category of Ad Unit.

Example:

    

"iabCategories": [{
       "id": 279
    }, {
        "id": 291
    }, {
        "id": 288
    }, {
        "id": 194
    }]
labelsList of label ObjectNo

Label should be valid and exist in system.

Only Ad Exclusion label should be valid for ad unit, Not Competitive Exclusion.

Labels applied on Ad Unit.

To create/edit/retrieve list of Labels, use Label Exclusion API.

You can use the field "excluded" along with "id" if you want to remove the inherited label for present Ad Unit. eg. "excluded": 1.

Note: To remove associated labels, pass an empty array i.e. [ ]. Only inherited labels (if any) will be associated.
userNumericYes
User ID of the user who is creating/updating/retrieving this Ad unit.

User ID of User.

To create/edit/retrieve a list of Operational User details, refer to User API

'supportsDynamicSize' flag is no longer supported at the AdUnit level.

     

Video Configuration Dimension

Video configuration attributes are mandatory when Ad Unit expected to support Video Ad Format else not. Following are list attributes user has to provide with valid values while creating / updating the Ad Unit.

 

UAS ad server can accept the video parameters in the ad request too and in this case UAS ad server gives higher preference to parameter received in the request and retrieves missing parameter details from video configuration provided at Ad unit Level.

Important note: Ad Server consider protocol and vpaid parameter only while filtering the Guaranteed video redirect creative. All parameter will get pass to programmatic channel to get better monetization from Video DSP.

Parameter Name/DimensionsTypeRequiredValidationsDescription
protocolNumericYesShould be valid and exist in the system

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

IDName
2VAST 2.0
3VAST 3.0

The list of support video protocols can be retrieved using the Common Video Protocol API.

vpaidNumericYesShould be valid and exist in the system.

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

IDName
0No VPAID support
1VPAID 1.0
2VPAID 2.0
videoMimeTypesJSON array of integerYesShould be a valid list of support mime types and exist in the system.

Supported Video Mime Types:

IDName
1mp4
2swf
3wmv
4H.264
5webm
6JavaScript
7ogg
8fav
companionAdSupportedBooleanYesTrue if supports companion Ad; else false.True if supplied video inventory has support for companion Ads.
playerSizesJSON array of integerYesShould be valid and exist in the systemYou can retrieve the supported sizes using Size API for video Ad Unit Format.
skippableOffsetNumericNo

If provided, should be in range of 1-5.

If not passed, considered as inventory is not skippable.

 

minDuration

maxDuration

NumericYes

Should be positive.

Max should be greater than equal Minimum duration.

Video minimum and maximum duration in secons.
autoPlayBooleanYesTrue if supports autoplay; else false.If inventory supports auto play video creatives.

 

Sample Request URL

https://api.pubmatic.com/v1/uas/adunits/896 

Sample JSON Request

    

{
    "account": {
        "id": 118385
    },
    "name": "US_Mobile_Sports_All_Formats-New",
    "description": "Geo:US, Source:Mobile, Category:Sport, Type:Banner, Video, Native",
    "parent": {
        "id": null
    },
    "adUnitGroups": [{
        "id": 54
    }],
    "supportsDynamicSize": false,
    "adSizes": [{
        "id": 31
    }, {
        "id": 54
    }],
    "adUnitFormats": [{
        "id": 3
    }, {
        "id": 12
    }, {
        "id": 13
    }],
    "iabCategories": [{
        "id": 279
    }, {
        "id": 291
    }, {
        "id": 288
    }, {
        "id": 194
    }],
    "labels": [{
        "id": 30,
        "isInherited": false
    }],
    "videoConfig": {
        "minDuration": 15,
        "maxDuration": 15,
        "skippableOffset": 5,
        "autoPlay": false,
        "companionAdSizes": [],
        "playerSizes": [{
            "id": 198
        }],
        "protocol": {
            "id": 2
        },
        "vpaid": {
            "id": 0
        }
    },
    "nativeConfig": {
        "templates": [{
            "id": 242
        }]
    },
    "status": {
        "id": 1
    },
    "frequencyCaps": [{
        "frequencyCapPeriod": {
            "id": 2
        },
        "periodValue": 1,
        "capValue": 1
    }, {
        "frequencyCapPeriod": {
            "id": 3
        },
        "periodValue": 1,
        "capValue": 3
    }],
    "coppaCompliant": true,
    "targetWindow": "_blank",
    "refreshRate": null

}

Response

Sample Response JSON

    

{
    "id": 896,
    "account": {
        "id": 118385,
        "url": "api.pubmatic.com/v1/uas/"
    },
    "name": "US_Mobile_Sports_All_Formats-New",
    "description": "Geo:US, Source:Mobile, Category:Sport, Type:Banner, Video, Native",
    "status": {
        "id": 1,
        "name": "Active",
        "url": "http://api.pubmatic.com/v1/uas/status/1"
    },
    "targetWindow": "_blank",
    "coppaCompliant": true,
    "supportsDynamicSize": false,
    "user": {
        "id": 1,
        "url": "http://api.pubmatic.com/v1/uas/users/1"
    },
    "adSizes": [{
        "id": 31,
        "name": "Mobile - 320x50"
    }, {
        "id": 54,
        "name": "Mobile - 320x48"
    }],
    "adUnitGroups": [{
        "id": 54
    }],
    "adUnitFormats": [{
        "id": 3
    }, {
        "id": 12
    }, {
        "id": 13
    }],
    "frequencyCaps": [{
        "frequencyCapPeriod": {
            "id": 2
        },
        "capValue": 1,
        "periodValue": 1
    }, {
        "frequencyCapPeriod": {
            "id": 3
        },
        "capValue": 3,
        "periodValue": 1
    }],
    "iabCategories": [{
        "id": 194
    }, {
        "id": 279
    }, {
        "id": 288
    }, {
        "id": 291
    }],
    "labels": [{
        "id": 30,
        "name": "Test_exclusion_Ad_001",
        "account": {
            "id": 118385
        },
        "labelType": {
            "id": 1,
            "name": "Ad Exclusion"
        },
        "isInherited": false
    }],
    "sspSite": {
        "id": 119108
    },
    "sspAdTag": {
        "id": 418992
    },
    "videoConfig": {
             "id": 153,
             "protocol": {
                 "id": 2
             },
             "vpaid": {
                 "id": 0
             },
             "companionAdSupported": false,
             "skippableOffset": 5,
             "minDuration": 15,
             "maxDuration": 15,
             "autoPlay": false,
             "companionAdSizes": [],
             "playerSizes": [{
                 "id": 198
             }],
             "videoMimeTypes": [{
                 "id": 1
             }, {
                 "id": 2
             }, {
                 "id": 3
             }, {
                 "id": 4
             }, {
                 "id": 6
             }, {
                 "id": 8
             }]
     },
    "nativeConfig": {
        "templates": [{
            "id": 242,
            "name": "Sports_News_Mobile"
        }]
    }
}

Update (Patch) an Ad Unit

 

Overview

This API updates only the requested attribute for a specific Ad Unit. This API does a partial update of the Ad Unit, not a full replacement of the AD Unit.

Request

           

Request Headers

                        

Header nameType ValueRequiredDescription
Content-TypeStringapplication/jsonYesMedia type for request.
pubTokenString${access_token}Yes

Publisher Token to authenticate and authorize the user calling the Unified Ad Server API. Send the access token generated for authentication at the place of ${access_token} in the request.

 

For more information about access tokens, refer to Getting Started with PubMatic APIs.

Sample Request URL

https://api.pubmatic.com/v1/uas/adunits/896 /external-link.jspa?url=https%3A%2F%2F%24URI_PREFIX%2F

Sample Request JSON

    

{
    "status": {
        "id": 2
    }
}

Response

Sample Response JSON

    

{
  "id": 896,
  "account": {
    "id": 118385,
    "url": "http://api.pubmatic.com/v1/uas/"
  },
  "name": "US_Mobile_Sports_All_Formats-New",
  "description": "Geo:US, Source:Mobile, Category:Sport, Type:Banner, Video, Native",
  "status": {
    "id": 2,
    "name": "Inactive",
    "url": "http://api.pubmatic.com/v1/uas/status/2"
  },
  "parentAdUnitPath": [],
  "targetWindow": "_blank",
  "coppaCompliant": true,
  "supportsDynamicSize": false,
  "user": {
    "id": 1,
    "url": "http://api.pubmatic.com/v1/uas/users/1"
  },
  "adSizes": [
    {
      "id": 31,
      "name": "Mobile - 320x50"
    },
    {
      "id": 54,
      "name": "Mobile - 320x48"
    }
  ],
  "adUnitGroups": [
    {
      "id": 54
    }
  ],
  "adUnitFormats": [
    {
      "id": 3
    },
    {
      "id": 12
    },
    {
      "id": 13
    }
  ],
  "frequencyCaps": [
    {
      "frequencyCapPeriod": {
        "id": 2,
        "url": "http://api.pubmatic.com/v1/uas/frequencycapperiods/2"
      },
      "capValue": 1,
      "periodValue": 1
    },
    {
      "frequencyCapPeriod": {
        "id": 3,
        "url": "http://api.pubmatic.com/v1/uas/frequencycapperiods/3"
      },
      "capValue": 3,
      "periodValue": 1
    }
  ],
  "iabCategories": [
    {
      "id": 194
    },
    {
      "id": 279
    },
    {
      "id": 288
    },
    {
      "id": 291
    }
  ],
  "labels": [
    {
      "id": 30,
      "name": "Test_exclusion_Ad_001",
      "account": {
        "id": 118385,
        "url": "http://api.pubmatic.com/v1/uas/"
      },
      "labelType": {
        "id": 1,
        "name": "Ad Exclusion",
        "url": "http://api.pubmatic.com/v1/uas/labeltype/1"
      },
      "isInherited": false
    }
  ],
  "sspSite": {
    "id": 119108
  },
  "sspAdTag": {
    "id": 418992
  },
"videoConfig": {
             "id": 153,
             "protocol": {
                 "id": 2
             },
             "vpaid": {
                 "id": 0
             },
             "companionAdSupported": false,
             "skippableOffset": 5,
             "minDuration": 15,
             "maxDuration": 15,
             "autoPlay": false,
             "companionAdSizes": [],
             "playerSizes": [{
                 "id": 198
             }],
             "videoMimeTypes": [{
                 "id": 1
             }, {
                 "id": 2
             }, {
                 "id": 3
             }, {
                 "id": 4
             }, {
                 "id": 6
             }, {
                 "id": 8
             }]
     },
  "nativeConfig": {
    "templates": [
      {
        "id": 242,
        "name": "Sports_News_Mobile"
      }
    ]
  }
}

 

Delete an Ad Unit

Overview

This API enables you to archive an ad unit. (Status will be changed to 'archived.')

The corresponding SSP Site and SSP AdTag will be archived as well.

Request

           

Request Headers

                        

Header nameType ValueRequiredDescription
Content-TypeStringapplication/jsonYesMedia type for request.
pubTokenString${access_token}Yes

Publisher Token to authenticate and authorize the user calling the Unified Ad Server API. Send the access token generated for authentication at the place of ${access_token} in the request.

 

For more information about access tokens, refer to Getting Started with PubMatic APIs.

Sample Request URL

https://api.pubmatic.com/v1/uas/adunits/896

Response

Sample Response JSON

    

Returns True if archive is successful; False if unsuccessful.

 

Error Codes For Unified Ad Server Ad Unit

                                                        

Sr. No

Error Codes

Description

1.

PH_MISSING_OR_INVALID_PARAMETER

This error occurs when a mandatory field is missing or its value is not valid (not present in database).

It can occur in following cases

  1. Ad Unit Id
  2. Account Id
  3. Name
  4. Status
  5. User Id
  6. Ad Sizes
  7. Ad Unit Groups
  8. Ad Unit Formats
  9. Parent Ad Unit Id
  10. IAB Categories
  11. Native Template Config Id
  12. Label Id
  13. If user specified "childLevel" query parameter without "listChildren" parameter or listChildren-=false in the request.
  14. If not provided video configuration attributes like videoMimeTypes, companionAdSupported, etc.
 2.PH_DUPLICATE_ENTITY

This error occurs when value already exists in database for an unique identifier field.

It can occur in following cases

  1. Name
  2. Ad Sizes
  3. Ad Unit Groups
  4. Ad Unit Formats
  5. Labels
3.PH_PARAMETER_VALUE_TOO_LARGE

This error occurs when input exceeds permitted number of characters.

It can occur in following cases

  1. Name
  2. Description
  3. Target Window
4.PH_ONLY_X_CHARACTERS_ARE_ALLOWED

It can occur in following cases

  1. Target Window
5.

PH_ENTITY_HAS_REACHED_LIMIT_OF_MAX_LEVELS

This error occurs when Parent Ad Unit is at maximum allowed level.

6.

PH_ENTITY_MUST_BE_BETWEEN_MIN_MAX_VALUES

This error occurs when input provided is not between required range of minimum and maximum values.

 

It can occur in following cases

  1. Refresh Rate
7.PH_CAN_NOT_LINK_PARENT_HAVING_CHILDRENThis error occurs when user tries to link a parent Ad Unit to an Ad Unit having children.
8.PH_CYCLIC_DEPENDANCY_NOT_ALLOWEDThis error occurs when user tries to add a parent Ad Unit which is already in parent hierarchy and becomes cyclic dependency.
9.PH_UNSUPPORTED_VALUE

This error occurs when user tried to provide unsupported value for a field.

It can occur for the following for the following fields:

 

Status

  • childLevel, if user specified childLevel apart from 1 to 5.
10.PH_INVALID_RANGE_VALUES

Video Ad Unit Config Skippable. Must be between 1 and 5.

 

Version 76

 

 

Unified Ad Server References

Common Request Query Parameters for Web Services

Supported Operations for Filters

HTTP Status Codes

Unified Ad Server Specific Error Codes

Attachments

    Outcomes