Creative API (UAS)

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

Description

The Creative API will be responsible for Creating, Updating and getting the Creatives. It will support the generic search for getting the Creative details with different criteria.

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

Supported Operations

                                                                               

Method Path

HTTP MethodType

DescriptionLink to Definition
/creatives/POST

This API method will create only one Creative per request. This will be in transaction.

Create Creative
/creatives/nativePOSTThis API method is used to create Native Creatives.This will be in transaction.Create Native Creative
/creatives/video/redirectPOSTThis API method is used to create Video Creatives. This will be in transaction.Create Video Creative
/creatives/{id}GET

Retrieve the details of a specific Creative for requested Creative Id.

Retrieve Details of a Creative
/creatives/GET

Retrieve the list of Line Items associated with your account.

You can apply supported dimensions, filters and sorting option to fetch list of Creatives with a specific set of details.

Retrieve a List of Creatives
/creatives/{id}PUT

The API method is exposed to update single Creative. This will be in transaction.

  1. This method will do full update. If the request does not contain value for an attribute then it will be either set to NULL/default value. But if the parameter is mandatory then it will fail an no Creative will be updated
  2. Client must ensure that it passing all the required attributes with required values.
Update Creative
/creatives/native/{id}PUT

The API method is exposed to update single Native Creative. This will be in transaction.

  1. This method will do full update. If the request does not contain value for an attribute then it will be either set to NULL/default value. But if the parameter is mandatory then it will fail an no Creative will be updated
  2. Client must ensure that it passing all the required attributes with required values.
Update Native Creative 
/creatives/video/redirect/{creativeId} PUT

The API method is exposed to update single Video Creative. This will be in transaction.

  1. This method will do full update. If the request does not contain value for an attribute then it will be either set to NULL/default value. But if the parameter is mandatory then it will fail an no Creative will be updated
  2. Client must ensure that it passing all the required attributes with required values.
Update Video Creative   
/creatives/html5POSTThis API method is used to create HTML5 Creatives. This will be in transaction.Create HTML5 Creative
/creatives/html5/{id}PUT

This API method is exposed to update a single Creative. This will be in transaction.

  • This method will do a full update. If the request does not contain a value for an attribute then it will be either set to NULL/default value. However, if the parameter is mandatory then it will fail and no Creative will be updated.
  • Ensure that it is passing all the required attributes with required values.
Update HTML5 Creative
/creatives/{id}PATCH

The API method is exposed to perform partial update on an object. e.g. If we want to change the status of the Creative then use partial update.

Currently it is assumed that it will be used only for

  1. Updating the status of the Creatives

NOTE : It is different than PUT. In PUT full replacement of the Object takes place.

Patch Creative
/creatives/{id}DELETE

This API method is used for archiving the Creative.

Archival of the Creative indicates that it will not be used in Ad Serving.

Delete Creative

 

Create a Creative

 

Overview

This API enables the creation of a Creative. Only one Creative can be included in each request. 

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 NameTypeRequiredValidationsDescriptions
nameStringYes

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

Name should be unique for your account.

Creative Name. Name should be descriptive.
descriptionStringNoDescription can be a maximum of 1024 characters. Default is null.Description to store more details about Creative.
accountNumericYesAccount of publisher for which this Creative is created.Account of the Publisher.
advertiserIntegerYes

Advertiser should be valid and exist.  

Advertiser for the Creative. You can create/edit/retrieve a list of advertiser using the Advertising API.
creativeTypeIntegerYesCreativeType should be valid and exists.Type of Creative. You can retrieve the list of creative types using the Creative Type API.
adSizeIntegerYesAdSize should be valid and exist.Size for creative.
sslCompatibilityIntegerYesValue should be 0 ( non- secured ) or 1 ( Secured )

SSL Compatibility for the creative:

               
IdName
0If creative is expected to be non-secured.
1If creative is expected to be secured.

Important note:

If the creative marked as SSP Compatible as 1, The Creative API check and validate to make sure all assets like Image URL, File URL ( HTML 5 Creative and Remote file URL starts with HTTPS only.

API will check and validate the all third party tracking pixel should be start with HTTPS else throws error response. ( Please refer to error codes ).

API does not perform any validation for Click Through URL if mentioned.

For Remote file & Third Party Tracking Pixel it's user responsibility to make the remote file is accessible over HTTPS when sslCompatibility = 1.

API does not validate the URL within the content / scripts for Video ( VAST XML ), HTML5 File and Rich Media those are getting executed dynamically while rendering the creative. User who is setting the creative has to make sure all the reference URL within Content / Scripts are using HTTPS.

statusNumericNoStatus should be valid and exists. Default is "Active" for newly created Creative if not provided.Status of the Creative. You can retrieve teh list of status using the Status API.
userStringYesUser ID of the user who is creating this Creative.User ID of the user. You can create/edit/retrieve list of Operational User details using the User API.
frequencyCapNumericNoFrequency should be valid.Frequency cap of Creative.
creativeAssets ArrayYes

A creative should have at least one asset.

Validations for assetValue based on creativeAssetType:

Image File:

  • Valid URL (e.g., http//$URI_PREFIX/{apiVersion}/{fileLocation})
  • File extensions should be one of the following: JPEG, JPG, GIF, PNG

Alt Text:

  • assetValue length should be less than 255 characters.

Click-through URL:

  • Valid URL (e.g., http://$URI_PREFIX/{apiversion}/...)
  • We currently support the following CTU protocols:
  • For tel: protocol we support phone numbers in the following formats:
    • 1234567890
    • 123-456-7890
    • 123-456-7890 x1234
    • 123-456-7890 ext1234
    • (123)-456-7890
    • 123.456.7890
    • 123 456 7890
  • We don't perform any validation for custom protocol

Creative Title:

  • assetValue length should be less than 255 characters

Creative Description:

  • assetValue length should be less than 1024 characters

Native Asset:

  • assetValue for Native Creative Asset depends on its nativeAssetTypeId:
    • Image:
      • Valid URL (e.g., http://$URI_PREFIX/{apiVersion}/{fileLocation})
      • File extensions should be one of the following: JPEG, JPG, GIF, PNG, TIFF
    • Title:
      • assetValue length should be less than that defined in corresponding asset of the selected template.
    • Data:
      • assetValue length should be less than that defined in corresponding asset of the selected template.

User also needs to provide "nativeAssetId" field in creative asset object which should be the "assetId" from asset object in native template. This is required to define the mapping of creative asset object against the corresponding asset object in native template.

Rich Media Tag:

  • No Validations

Video Protocol:

  • Should be one of the following protocols:
    • VAST 2.0
    • VAST 3.0

VPAID Support:

  • Should be one of the following protocols:
    • No VPAID Support
    • VPAID 1.0
    • VPAID 2.0

HTML FIle:

  • Should be the path of the HTML file hosted on the server.
  • The following extensions are supported:
    • HTML
    • HTM

Assets of Creative. You can retreive the list of Asset Types using the Creative Asset Type API. 

Refer to the Creative Asset Type table below for the required Creative Assets for a particular Creative Type.

 

Refer to the Native Creative Assets table below. (Only applicable for Native Creative.)

lineitemsArrayNo 

Line Items Associated with Creative.

Note: This field is used to provide information and not used while creating or updating the creative.

You can retrieve the list of Asset Types using Line Item API  

trackingEventsArrayNo
  • Tracking Event should be valid and exist.
  • Click Tracking is supported for all creative types. There should be only one Click Tracking for any creative. Other tracking events can be added multiple times.
  • Valid tracking event URL should start with either of the following protocols:

Tracking events associated with the Creatives.

You can retrieve the list of Asset Types using Tracking Events API

Important note:

If creative does not have click through URL configured, the configured Third Party Click Tracking at Creative Level will not execute / triggered.

Refer to the Tracking Events table below for valid tracking events for different types of creatives

Creative Asset Type 

                                                                                                   

IDCreative TypeCreative Asset IDCreative Asset TypeMandatory*
2Image1Image FileTrue
  2Alt TextFalse
  3Click-through URLFalse
4Text3Click-through URLFalse
  4Creative TitleTrue
  6Creative DescriptionFalse
6Video8VAST Tag URLTrue
  11Video ProtocolTrue
  12VPAID SupportTrue
7Rich Media3Click-through URLFalse
  10Rich Media TagTrue
8HTML513HTML FileTrue
  3Click Through URLFalse

*If Mandatory is False, it means you should have the field but it can contain an empty value.

Native Creative Assets

                                                                                   

NativeAssetTypeIdNatveAssetSubTypeIdName
21icon
22logo
23main
31sponsored 
32desc
33rating
34likes
35downloads
36price
37saleprice
38phone
39address
310desc2
311displayurl
312ctatext

Tracking Events

                                                                                                                     

IDCreative TypeTracking Event IDTracking Event Name
2Image1Click Tracking
  9Impression Tracking
3Native1Click Tracking
  9Impression Tracking
4Text1Click Tracking
  9Impression Tracking
6Video1Click Tracking
  2Complete
  3Creative View
  4Custom Click
  5First Quartile
  6Mid Point
  7Start
  8Third Quartile
7Rich Media1Click Tracking
  9Impression Tracking
8HTML51Click Tracking
  9Impression Tracking
 

Sample Request URL

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

Sample Request JSON

    

{
    "account": {
        "id": 118385
    },
    "name": "Test-Creative-Image",
    "description": "Test",
    "status": {
        "id": 1
    },
    "advertiser": {
        "id": 13
    },
    "creativeType": {
        "id": 2
    },
    "adSize": {
        "id": 2
    },
    "sslCompatibility": 0,
    "creativeAssets": [{
        "creativeAssetType": {
            "id": 1
        },
        "assetValue": "{filePath}/Logo.png"
    }, {
        "creativeAssetType": {
            "id": 2
        },
        "assetValue": "Alt Text"
    }, {
        "creativeAssetType": {
            "id": 3
        },
        "creativeAssetProperties":{
        
            "clickThroughUrlProtocol": 1
        },
        "assetValue": "http://test.com"
    }],
    "frequencyCaps": [{
        "frequencyCapPeriod": {
            "id": 1
        },
        "periodValue": 1,
        "capValue": 123
    }]
}
Response

Sample Response JSON

    

{  
    "id": 433,
    "name": "Test-Creative-Image",
    "description": "Test",
    "account": {
        "id": 118385,
        "name": "PubMatic Inc.",
        "url": "http://api.pubmatic.com/v1/uas/"
    },
    "advertiser": {
        "id": 13,
        "name": "Advertiser-13",
        "url": "http://api.pubmatic.com/v1/uas/"
    },
    "creativeType": {
        "id": 2,
        "name": "Image",
        "url": "http://api.pubmatic.com/v1/uas/creativetypes/2"
    },
    "adSize": {
        "id": 2,
        "name": "Super Leaderboard - 970x90",
        "url": "http://api.pubmatic.com/v1/uas/adsizes/2"
    },
    "sslCompatibility": 0,
    "status": {
        "id": 1,
        "name": "Active",
        "url": "http://api.pubmatic.com/v1/uas/status/1"
    },
    "user": {
        "id": 18280,
        "url": "http://api.pubmatic.com/v1/uas/users/18280"
    },
    "frequencyCaps": [{
        "frequencyCapPeriod": {
            "id": 1,
            "url":"http://api.pubmatic.com/v1/uas/frequencycapperiods/1"
        },
        "capValue": 123,
        "periodValue": 1
    }],
    "creativeAssets": [{
        "id": 2721,
        "creativeAssetType": {
            "id": 1,
            "name": "Image File"
        },
        "creativeAssetProperties":{},
        "assetValue": "{filePath}/Logo.png"
    }, {
        "id": 2722,
        "creativeAssetType": {
            "id": 2,
            "name": "Alt Text"
        },
        "creativeAssetProperties":{},
        "assetValue": "Alt Text"
    }, {
        "id": 2723,
        "creativeAssetType": {
            "id": 3,
            "name": "Click-through URL"
        },
        "creativeAssetProperties":
        {
            "clickThroughUrlProtocol": 1
        },
        "assetValue": "http://test.com"
    }],
    "lineItems": []
}

  

 

Create a Native Creative

Overview

This API enables the creation of a Native Creative. Only one Creative per request. 

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 NameTypeRequiredValidationsDescriptions
nameStringYes

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

Name should be unique for your account.

Creative Name. Name should be descriptive.
descriptionStringNoDescription can be a maximum of 1024 characters. Default is null.Description to store more details about Creative.
accountNumericYesAccount of publisher for which this Creative is created.Account of the Publisher.
advertiserIntegerYes

Advertiser should be valid and exist.

Advertiser for the Creative. You can create/edit/retrieve a list of advertiser using the Advertising API.
creativeTypeIntegerYesCreativeType should be valid and exists.Type of Creative. You can retrieve the list of creative types using the Creative Type API.
adSizeIntegerYesAdSize should be valid and exist.Size for creative.
sslCompatibilityIntegerYesValue should be 0 ( non- secured ) or 1 ( Secured )

SSL Compatibility for the creative:

               
IdName
0If creative is expected to be non-secured.
1If creative is expected to be secured.

Important note:

If the creative marked as SSP Compatible as 1, The Creative API check and validate to make sure all assets like Image URL, File URL ( HTML 5 Creative and Remote file URL starts with HTTPS only.

API will check and validate the all third party tracking pixel should be start with HTTPS else throws error response. ( Please refer to error codes ).

API does not perform any validation for Click Through URL if mentioned.

For Remote file & Third Party Tracking Pixel it's user responsibility to make the remote file is accessible over HTTPS when sslCompatibility = 1.

API does not validate the URL within the content / scripts for Video ( VAST XML ), HTML5 File and Rich Media those are getting executed dynamically while rendering the creative. User who is setting the creative has to make sure all the reference URL within Content / Scripts are using HTTPS.

statusNumericNoStatus should be valid and exists. Default is "Active" for newly created Creative if not provided.Status of the Creative. You can retrieve teh list of status using the Status API.
userStringYesUser ID of the user who is creating this Creative.User ID of the user. You can create/edit/retrieve list of Operational User details using the User API.
frequencyCapNumericNoFrequency should be valid.Frequency cap of Creative.
creativeAssets ArrayYes

A creative should have at least one asset.

Validations for assetValue based on creativeAssetType:

Image File:

  • Valid URL (e.g., http//$URI_PREFIX/{apiVersion}/{fileLocation})
  • File extensions should be one of the following: JPEG, JPG, GIF, PNG

Alt Text:

  • assetValue length should be less than 255 characters.

Click-through URL:

  • Valid URL (e.g., http://$URI_PREFIX/{apiversion}/...)
  • We currently support the following CTU protocols:
  • For tel: protocol we support phone numbers in the following formats:
    • 1234567890
    • 123-456-7890
    • 123-456-7890 x1234
    • 123-456-7890 ext1234
    • (123)-456-7890
    • 123.456.7890
    • 123 456 7890
  • We don't perform any validation for custom protocol

Creative Title:

  • assetValue length should be less than 255 characters

Creative Description:

  • assetValue length should be less than 1024 characters

Native Asset:

  • assetValue for Native Creative Asset depends on its nativeAssetTypeId:
    • Image:
      • Valid URL (e.g., http://$URI_PREFIX/{apiVersion}/{fileLocation})
      • File extensions should be one of the following: JPEG, JPG, GIF, PNG, TIFF
    • Title:
      • assetValue length should be less than that defined in corresponding asset of the selected template.
    • Data:
      • assetValue length should be less than that defined in corresponding asset of the selected template.

User also needs to provide "nativeAssetId" field in creative asset object which should be the "assetId" from asset object in native template. This is required to define the mapping of creative asset object against the corresponding asset object in native template.

Rich Media Tag:

  • No Validations

Video Protocol:

  • Should be one of the following protocols:
    • VAST 2.0
    • VAST 3.0

VPAID Support:

  • Should be one of the following protocols:
    • No VPAID Support
    • VPAID 1.0
    • VPAID 2.0

HTML FIle:

  • Should be the path of the HTML file hosted on the server.
  • The following extensions are supported:
    • HTML
    • HTM

Assets of Creative. You can retreive the list of Asset Types using the Creative Asset Type API. 

Refer to the Creative Asset Type table below for the required Creative Assets for a particular Creative Type.

 

Refer to the Native Creative Assets table below. (Only applicable for Native Creative.)

lineitemsArrayNo 

Line Items Associated with Creative.

Note: This field is used to provide information and not used while creating or updating the creative.

You can retrieve the list of Asset Types using Line Item API  

trackingEventsArrayNo
  • Tracking Event should be valid and exist.
  • Click Tracking is supported for all creative types. There should be only one Click Tracking for any creative. Other tracking events can be added multiple times.
  • Valid tracking event URL should start with either of the following protocols:

Tracking events associated with the Creatives.

You can retrieve the list of Asset Types using Tracking Events API

Important note:

If creative does not have click through URL configured, the configured Third Party Click Tracking at Creative Level will not execute / triggered.

Refer to the Tracking Events table below for valid tracking events for different types of creatives

Creative Asset Type 

                                                                                                   

IDCreative TypeCreative Asset IDCreative Asset TypeMandatory*
2Image1Image FileTrue
  2Alt TextFalse
  3Click-through URLFalse
4Text3Click-through URLFalse
  4Creative TitleTrue
  6Creative DescriptionFalse
6Video8VAST Tag URLTrue
  11Video ProtocolTrue
  12VPAID SupportTrue
7Rich Media3Click-through URLFalse
  10Rich Media TagTrue
8HTML513HTML FileTrue
  3Click Through URLFalse

*If Mandatory is False, it means you should have the field but it can contain an empty value.

Native Creative Assets

                                                                                   

NativeAssetTypeIdNatveAssetSubTypeIdName
21icon
22logo
23main
31sponsored 
32desc
33rating
34likes
35downloads
36price
37saleprice
38phone
39address
310desc2
311displayurl
312ctatext

Tracking Events

                                                                                                                     

IDCreative TypeTracking Event IDTracking Event Name
2Image1Click Tracking
  9Impression Tracking
3Native1Click Tracking
  9Impression Tracking
4Text1Click Tracking
  9Impression Tracking
6Video1Click Tracking
  2Complete
  3Creative View
  4Custom Click
  5First Quartile
  6Mid Point
  7Start
  8Third Quartile
7Rich Media1Click Tracking
  9Impression Tracking
8HTML51Click Tracking
  9Impression Tracking
 

Additional Request Body Parameters for Native Creative

                 

Parameter NameTypeRequiredValidationDescription
nativeTemplateConfigIntegerYes

This is a mandatory parameter for Native Creative.

Only valid template config id should be passed.


User defined Native Template configuration which is used to select the assets applicable. Native Creative is associated to one Native Template Configuration.

Sample Request URL

https://api.pubmatic.com/v1/uas/creatives/native/ 

Sample Request JSON

    

{
    "account": {
        "id": 118385
    },
    "name": "Test-Creative-Native",
    "description": "Test",
    "status": {
        "id": 1
    },
    "advertiser": {
        "id": 13
    },
    "creativeType": {
        "id": 3
    },
    "sslCompatibility": 0,
    "creativeAssets": [{
        "creativeAssetType": {
            "id": 3
        },
        "properties":{
            "clickThroughUrlProtocol": 1
        },
        "assetValue": "http://test.com"
    }, {
        "id": 9,
        "creativeAssetType": {
            "id": 9
        },
        "assetValue": "Title",
        "nativeAssetTypeId": 1,
        "nativeAssetId": 1
    }, {
        "id": 10,
        "creativeAssetType": {
            "id": 9
        },
        "assetValue": "{filePath}/Logo.png",
        "nativeAssetTypeId": 2,
        "nativeAssetSubTypeId": 1,
        "nativeAssetId": 2
    }, {
        "id": 11,
        "creativeAssetType": {
            "id": 9
        },
        "assetValue": "CTA Text",
        "nativeAssetTypeId": 3,
        "nativeAssetSubTypeId": 12,
        "nativeAssetId": 3
    }, {
        "id": 12,
        "creativeAssetType": {
            "id": 9
        },
        "assetValue": "6",
        "nativeAssetTypeId": 3,
        "nativeAssetSubTypeId": 3,
        "nativeAssetId": 4
    }],
    "frequencyCaps": [{
        "frequencyCapPeriod": {
            "id": 1
        },
        "periodValue": 1,
        "capValue": 123
    }],
    "nativeTemplateConfig": {
        "id": 9
    }
}
Response

Sample Response JSON

    

{   "id": 432,
    "name": "Test-Creative-Native",
    "description": "Test",
    "account": {
        "id": 118385,
        "name": "PubMatic Inc."
    },
    "advertiser": {
        "id": 13,
        "name": "Advertiser-13"
    },
    "creativeType": {
        "id": 3,
        "name": "Native"
    },
    "sslCompatibility": 0,
    "status": {
        "id": 1,
        "name": "Active"
    },
    "user": {
        "id": 18280
    },
    "frequencyCaps": [{
        "frequencyCapPeriod": {
            "id": 1
        },
        "capValue": 123,
        "periodValue": 1
    }],
    "creativeAssets": [{
        "id": 2716,
        "creativeAssetType": {
            "id": 3,
            "name": "Click-through URL"
        },
        "properties":{
            "clickThroughUrlProtocol": 1
        },
        "assetValue": "http://test.com"
    }, {
        "id": 2717,
        "creativeAssetType": {
            "id": 9,
            "name": "Native Asset"
        },
        "properties":{},
        "nativeAssetTypeId": 1,
        "assetValue": "Title",
        "nativeAssetId": 1
    }, {
        "id": 2718,
        "creativeAssetType": {
            "id": 9,
            "name": "Native Asset"
        },
        "properties":{
                "w": "20",
                "mime": "image/png",
                "h": "20"
        },
        "nativeAssetTypeId": 2, 
        "nativeAssetSubTypeId": 1,
        "assetValue": "{filePath}/Logo.png",
        "nativeAssetId": 2
    }, {
        "id": 2719,
        "creativeAssetType": {
            "id": 9,
            "name": "Native Asset"
        },
        "properties":{},
        "nativeAssetTypeId": 3,
        "nativeAssetSubTypeId": 12,     
        "assetValue": "CTA Text",
        "nativeAssetId": 3
    }, {
        "id": 2720,
        "creativeAssetType": {
            "id": 9,
            "name": "Native Asset"
        },
        "properties":{},
        "nativeAssetTypeId": 3,
        "nativeAssetSubTypeId": 3,
        "assetValue": "6",
        "nativeAssetId": 4
    }],
    "lineItems": [],
    "nativeTemplateConfig": {
        "id": 9,
        "url": "http://api.pubmatic.com/v1/uas/"
    }
}

 

 

Create a Video Creative

Overview

This API enables the creation of a Video Creative. Only one Creative per request. 

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 NameTypeRequiredValidationsDescriptions
nameStringYes

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

Name should be unique for your account.

Creative Name. Name should be descriptive.
descriptionStringNoDescription can be a maximum of 1024 characters. Default is null.Description to store more details about Creative.
accountNumericYesAccount of publisher for which this Creative is created.Account of the Publisher.
advertiserIntegerYes

Advertiser should be valid and exist.

Advertiser for the Creative. You can create/edit/retrieve a list of advertiser using the Advertising API.
creativeTypeIntegerYesCreativeType should be valid and exists.Type of Creative. You can retrieve the list of creative types using the Creative Type API.
adSizeIntegerYesAdSize should be valid and exist.Size for creative.
sslCompatibilityIntegerYesValue should be 0 ( non- secured ) or 1 ( Secured )

SSL Compatibility for the creative:

               
IdName
0If creative is expected to be non-secured.
1If creative is expected to be secured.

Important note:

If the creative marked as SSP Compatible as 1, The Creative API check and validate to make sure all assets like Image URL, File URL ( HTML 5 Creative and Remote file URL starts with HTTPS only.

API will check and validate the all third party tracking pixel should be start with HTTPS else throws error response. ( Please refer to error codes ).

API does not perform any validation for Click Through URL if mentioned.

For Remote file & Third Party Tracking Pixel it's user responsibility to make the remote file is accessible over HTTPS when sslCompatibility = 1.

API does not validate the URL within the content / scripts for Video ( VAST XML ), HTML5 File and Rich Media those are getting executed dynamically while rendering the creative. User who is setting the creative has to make sure all the reference URL within Content / Scripts are using HTTPS.

statusNumericNoStatus should be valid and exists. Default is "Active" for newly created Creative if not provided.Status of the Creative. You can retrieve teh list of status using the Status API.
userStringYesUser ID of the user who is creating this Creative.User ID of the user. You can create/edit/retrieve list of Operational User details using the User API.
frequencyCapNumericNoFrequency should be valid.Frequency cap of Creative.
creativeAssets ArrayYes

A creative should have at least one asset.

Validations for assetValue based on creativeAssetType:

Image File:

  • Valid URL (e.g., http//$URI_PREFIX/{apiVersion}/{fileLocation})
  • File extensions should be one of the following: JPEG, JPG, GIF, PNG

Alt Text:

  • assetValue length should be less than 255 characters.

Click-through URL:

  • Valid URL (e.g., http://$URI_PREFIX/{apiversion}/...)
  • We currently support the following CTU protocols:
  • For tel: protocol we support phone numbers in the following formats:
    • 1234567890
    • 123-456-7890
    • 123-456-7890 x1234
    • 123-456-7890 ext1234
    • (123)-456-7890
    • 123.456.7890
    • 123 456 7890
  • We don't perform any validation for custom protocol

Creative Title:

  • assetValue length should be less than 255 characters

Creative Description:

  • assetValue length should be less than 1024 characters

Native Asset:

  • assetValue for Native Creative Asset depends on its nativeAssetTypeId:
    • Image:
      • Valid URL (e.g., http://$URI_PREFIX/{apiVersion}/{fileLocation})
      • File extensions should be one of the following: JPEG, JPG, GIF, PNG, TIFF
    • Title:
      • assetValue length should be less than that defined in corresponding asset of the selected template.
    • Data:
      • assetValue length should be less than that defined in corresponding asset of the selected template.

User also needs to provide "nativeAssetId" field in creative asset object which should be the "assetId" from asset object in native template. This is required to define the mapping of creative asset object against the corresponding asset object in native template.

Rich Media Tag:

  • No Validations

Video Protocol:

  • Should be one of the following protocols:
    • VAST 2.0
    • VAST 3.0

VPAID Support:

  • Should be one of the following protocols:
    • No VPAID Support
    • VPAID 1.0
    • VPAID 2.0

HTML FIle:

  • Should be the path of the HTML file hosted on the server.
  • The following extensions are supported:
    • HTML
    • HTM

Assets of Creative. You can retreive the list of Asset Types using the Creative Asset Type API. 

Refer to the Creative Asset Type table below for the required Creative Assets for a particular Creative Type.

 

Refer to the Native Creative Assets table below. (Only applicable for Native Creative.)

lineitemsArrayNo 

Line Items Associated with Creative.

Note: This field is used to provide information and not used while creating or updating the creative.

You can retrieve the list of Asset Types using Line Item API  

trackingEventsArrayNo
  • Tracking Event should be valid and exist.
  • Click Tracking is supported for all creative types. There should be only one Click Tracking for any creative. Other tracking events can be added multiple times.
  • Valid tracking event URL should start with either of the following protocols:

Tracking events associated with the Creatives.

You can retrieve the list of Asset Types using Tracking Events API

Important note:

If creative does not have click through URL configured, the configured Third Party Click Tracking at Creative Level will not execute / triggered.

Refer to the Tracking Events table below for valid tracking events for different types of creatives

Creative Asset Type 

                                                                                                   

IDCreative TypeCreative Asset IDCreative Asset TypeMandatory*
2Image1Image FileTrue
  2Alt TextFalse
  3Click-through URLFalse
4Text3Click-through URLFalse
  4Creative TitleTrue
  6Creative DescriptionFalse
6Video8VAST Tag URLTrue
  11Video ProtocolTrue
  12VPAID SupportTrue
7Rich Media3Click-through URLFalse
  10Rich Media TagTrue
8HTML513HTML FileTrue
  3Click Through URLFalse

*If Mandatory is False, it means you should have the field but it can contain an empty value.

Native Creative Assets

                                                                                   

NativeAssetTypeIdNatveAssetSubTypeIdName
21icon
22logo
23main
31sponsored 
32desc
33rating
34likes
35downloads
36price
37saleprice
38phone
39address
310desc2
311displayurl
312ctatext

Tracking Events

                                                                                                                     

IDCreative TypeTracking Event IDTracking Event Name
2Image1Click Tracking
  9Impression Tracking
3Native1Click Tracking
  9Impression Tracking
4Text1Click Tracking
  9Impression Tracking
6Video1Click Tracking
  2Complete
  3Creative View
  4Custom Click
  5First Quartile
  6Mid Point
  7Start
  8Third Quartile
7Rich Media1Click Tracking
  9Impression Tracking
8HTML51Click Tracking
  9Impression Tracking

Sample Request URL

https://api.pubmatic.com/v1/uas/creatives/video/redirect/ 

Sample Request JSON

    

{
    "account": {
        "id": 118385
    },
    "name": "Test-Creative-Video",
    "description": "Test",
    "status": {
        "id": 1
    }
    "advertiser": {
        "id": 13
    },
    "creativeType": {
        "id": 6
    },
    "adSize": {
        "id": 51
    },
    "sslCompatibility": 0,
    "creativeAssets": [{
        "creativeAssetType": {
            "id": 8
        },
        "assetValue": "http://$URI_PREFIX/{apiVersion}/test_vast/vast1.xml"
    }, {
        "creativeAssetType": {
            "id": 11
        },
        "assetValue": "3"
    }, {
        "creativeAssetType": {
            "id": 12
        },
        "assetValue": "2"
    }],
    "frequencyCaps": [{
        "frequencyCapPeriod": {
            "id": 1
        },
        "periodValue": 1,
        "capValue": 123
    }],
    "trackingEvents": [{
        "id": 1,
        "trackingUrl": "http://test.com"
    }, {
        "id": 5,
        "trackingUrl": "http://test.com"
    }]
}
Response

Sample Response JSON

    

{
    "id": 431,
    "name": "Test-Creative-Video",
    "description": "Test",
    "account": {
        "id": 118385,
        "name": "PubMatic Inc."
    },
    "advertiser": {
        "id": 13,
        "name": "Advertiser-13"
    },
    "creativeType": {
        "id": 6,
        "name": "Video"
    },
    "adSize": {
        "id": 51,
        "name": "Video - 400 x 300"
    },
    "sslCompatibility": 0,
    "status": {
        "id": 1,
        "name": "Active"
    },
    "user": {
        "id": 18280
    },
    "frequencyCaps": [{
        "frequencyCapPeriod": {
            "id": 1
        },
        "capValue": 123,
        "periodValue": 1
    }],
    "creativeAssets": [{
        "id": 2713,
        "creativeAssetType": {
            "id": 8,
            "name": "VAST Tag URL"
        },
        "assetValue": "https://api.pubmatic.com/v1/uas/creatives/video/test_vast/vast1.xml"
    }, {
        "id": 2714,
        "creativeAssetType": {
            "id": 11,
            "name": "Video Protocol"
        },
        "assetValue": "3"
    }, {
        "id": 2715,
        "creativeAssetType": {
            "id": 12,
            "name": "VPAID Support"
        },
        "assetValue": "2"
    }],
    "lineItems": [],
    "trackingEvents": [{
        "id": 1,
        "name": "Click Tracking",
        "trackingUrl": "http://test.com"
    }, {
        "id": 5,
        "name": "First Quartile",
        "trackingUrl": "http://test.com"
    }],
    "companionAds": {
        "imageCompanionAds": [],
        "thirdPartyCompanionAds": [],
        "textCompanionAds": []
    }
}

  

 

Retrieving Details of a Creative

 

Overview

This API fetches the details for the specified Creative.

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 URL

https://api.pubmatic.com/v1/uas/creatives/433 

 

Response

Sample Response JSON

    

{ 
    "id": 433,
    "name": "Test-Creative-Image",
    "description": "Test",
    "account": {
        "id": 118385,
        "name": "PubMatic Inc.",
        "url": "http://api.pubmatic.com/v1/uas/"
    },
    "advertiser": {
        "id": 13,
        "name": "Advertiser-13",
        "url": "http://api.pubmatic.com/v1/uas/"
    },
    "creativeType": {
        "id": 2,
        "name": "Image",
        "url": "http://api.pubmatic.com/v1/uas/creativetypes/2"
    },
    "adSize": {
        "id": 2,
        "name": "Super Leaderboard - 970x90",
        "url": "http://api.pubmatic.com/v1/uas/adsizes/2"
    },
    "sslCompatibility": 3,
    "status": {
        "id": 1,
        "name": "Active",
        "url": "http://api.pubmatic.com/v1/uas/status/1"
    },
    "user": {
        "id": 18280,
        "url": "http://api.pubmatic.com/v1/uas/users/18280"
    },
    "frequencyCaps": [{
        "frequencyCapPeriod": {
            "id": 1,
            "url":"http://api.pubmatic.com/v1/uas/frequencycapperiods/1"
        },
        "capValue": 123,
        "periodValue": 1
    }],
    "creativeAssets": [{
        "id": 2721,
        "creativeAssetType": {
            "id": 1,
            "name": "Image File"
        },
        "creativeAssetProperties":{},
        "assetValue": "{filePath}/Logo.png"
    }, {
        "id": 2722,
        "creativeAssetType": {
            "id": 2,
            "name": "Alt Text"
        },
        "creativeAssetProperties":{},
        "assetValue": "Alt Text"
    }, {
        "id": 2723,
        "creativeAssetType": {
            "id": 3,
            "name": "Click-through URL"
        },
        "creativeAssetProperties":{
            "clickThroughUrlProtocol": 1
        },
        "assetValue": "http://test.com"
    }],
    "lineItems": []
}

 

 

Retrieve a List of Creatives

Overview

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

Request

           

URIHTTP Method
https://api.pubmatic.com/v1/uas/creatives/GET

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 URL

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

Response

Sample Response JSON

    

The API will return all creatives associated with your account.

 

 

Update a Creative

 

Overview

This API enables you to Update a Creative.

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 NameTypeRequiredValidationsDescriptions
nameStringYes

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

Name should be unique for your account.

Creative Name. Name should be descriptive.
descriptionStringNoDescription can be a maximum of 1024 characters. Default is null.Description to store more details about Creative.
accountNumericYesAccount of publisher for which this Creative is created.Account of the Publisher.
advertiserIntegerYes

Advertiser should be valid and exist.

Advertiser for the Creative. You can create/edit/retrieve a list of advertiser using the Advertising API.
creativeTypeIntegerYesCreativeType should be valid and exists.Type of Creative. You can retrieve the list of creative types using the Creative Type API.
adSizeIntegerYesAdSize should be valid and exist.Size for creative.
sslCompatibilityIntegerYesValue should be 0 ( non- secured ) or 1 ( Secured )

SSL Compatibility for the creative:

               
IdName
0If creative is expected to be non-secured.
1If creative is expected to be secured.

Important note:

If the creative marked as SSP Compatible as 1, The Creative API check and validate to make sure all assets like Image URL, File URL ( HTML 5 Creative and Remote file URL starts with HTTPS only.

API will check and validate the all third party tracking pixel should be start with HTTPS else throws error response. ( Please refer to error codes ).

API does not perform any validation for Click Through URL if mentioned.

For Remote file & Third Party Tracking Pixel it's user responsibility to make the remote file is accessible over HTTPS when sslCompatibility = 1.

API does not validate the URL within the content / scripts for Video ( VAST XML ), HTML5 File and Rich Media those are getting executed dynamically while rendering the creative. User who is setting the creative has to make sure all the reference URL within Content / Scripts are using HTTPS.

statusNumericNoStatus should be valid and exists. Default is "Active" for newly created Creative if not provided.Status of the Creative. You can retrieve teh list of status using the Status API.
userStringYesUser ID of the user who is creating this Creative.User ID of the user. You can create/edit/retrieve list of Operational User details using the User API.
frequencyCapNumericNoFrequency should be valid.Frequency cap of Creative.
creativeAssets ArrayYes

A creative should have at least one asset.

Validations for assetValue based on creativeAssetType:

Image File:

  • Valid URL (e.g., http//$URI_PREFIX/{apiVersion}/{fileLocation})
  • File extensions should be one of the following: JPEG, JPG, GIF, PNG

Alt Text:

  • assetValue length should be less than 255 characters.

Click-through URL:

  • Valid URL (e.g., http://$URI_PREFIX/{apiversion}/...)
  • We currently support the following CTU protocols:
  • For tel: protocol we support phone numbers in the following formats:
    • 1234567890
    • 123-456-7890
    • 123-456-7890 x1234
    • 123-456-7890 ext1234
    • (123)-456-7890
    • 123.456.7890
    • 123 456 7890
  • We don't perform any validation for custom protocol

Creative Title:

  • assetValue length should be less than 255 characters

Creative Description:

  • assetValue length should be less than 1024 characters

Native Asset:

  • assetValue for Native Creative Asset depends on its nativeAssetTypeId:
    • Image:
      • Valid URL (e.g., http://$URI_PREFIX/{apiVersion}/{fileLocation})
      • File extensions should be one of the following: JPEG, JPG, GIF, PNG, TIFF
    • Title:
      • assetValue length should be less than that defined in corresponding asset of the selected template.
    • Data:
      • assetValue length should be less than that defined in corresponding asset of the selected template.

User also needs to provide "nativeAssetId" field in creative asset object which should be the "assetId" from asset object in native template. This is required to define the mapping of creative asset object against the corresponding asset object in native template.

Rich Media Tag:

  • No Validations

Video Protocol:

  • Should be one of the following protocols:
    • VAST 2.0
    • VAST 3.0

VPAID Support:

  • Should be one of the following protocols:
    • No VPAID Support
    • VPAID 1.0
    • VPAID 2.0

HTML FIle:

  • Should be the path of the HTML file hosted on the server.
  • The following extensions are supported:
    • HTML
    • HTM

Assets of Creative. You can retreive the list of Asset Types using the Creative Asset Type API. 

Refer to the Creative Asset Type table below for the required Creative Assets for a particular Creative Type.

 

Refer to the Native Creative Assets table below. (Only applicable for Native Creative.)

lineitemsArrayNo 

Line Items Associated with Creative.

Note: This field is used to provide information and not used while creating or updating the creative.

You can retrieve the list of Asset Types using Line Item API  

trackingEventsArrayNo
  • Tracking Event should be valid and exist.
  • Click Tracking is supported for all creative types. There should be only one Click Tracking for any creative. Other tracking events can be added multiple times.
  • Valid tracking event URL should start with either of the following protocols:

Tracking events associated with the Creatives.

You can retrieve the list of Asset Types using Tracking Events API

Important note:

If creative does not have click through URL configured, the configured Third Party Click Tracking at Creative Level will not execute / triggered.

Refer to the Tracking Events table below for valid tracking events for different types of creatives

Creative Asset Type 

                                                                                                   

IDCreative TypeCreative Asset IDCreative Asset TypeMandatory*
2Image1Image FileTrue
  2Alt TextFalse
  3Click-through URLFalse
4Text3Click-through URLFalse
  4Creative TitleTrue
  6Creative DescriptionFalse
6Video8VAST Tag URLTrue
  11Video ProtocolTrue
  12VPAID SupportTrue
7Rich Media3Click-through URLFalse
  10Rich Media TagTrue
8HTML513HTML FileTrue
  3Click Through URLFalse

*If Mandatory is False, it means you should have the field but it can contain an empty value.

Native Creative Assets

                                                                                   

NativeAssetTypeIdNatveAssetSubTypeIdName
21icon
22logo
23main
31sponsored 
32desc
33rating
34likes
35downloads
36price
37saleprice
38phone
39address
310desc2
311displayurl
312ctatext

Tracking Events

                                                                                                                     

IDCreative TypeTracking Event IDTracking Event Name
2Image1Click Tracking
  9Impression Tracking
3Native1Click Tracking
  9Impression Tracking
4Text1Click Tracking
  9Impression Tracking
6Video1Click Tracking
  2Complete
  3Creative View
  4Custom Click
  5First Quartile
  6Mid Point
  7Start
  8Third Quartile
7Rich Media1Click Tracking
  9Impression Tracking
8HTML51Click Tracking
  9Impression Tracking

Sample Request URL

https://api.pubmatic.com/v1/uas/creatives/native/432 

Sample Request JSON

    

{
    "id": 433,
    "name": "Test-Creative-Image",
    "description": "Test Description",
    "account": {
        "id": 118385,
        "name": "PubMatic Inc.",
        "url": "http://api.pubmatic.com/v1/uas/"
    },
    "advertiser": {
        "id": 13,
        "name": "Advertiser-13",
        "url": "http://api.pubmatic.com/v1/uas/"
    },
    "creativeType": {
        "id": 2,
        "name": "Image",
        "url": "http://api.pubmatic.com/v1/uas/creativetypes/2"
    },
    "adSize": {
        "id": 2,
        "name": "Super Leaderboard - 970x90",
        "url": "http://api.pubmatic.com/v1/uas/adsizes/2"
    },
    "sslCompatibility": 0,
    "status": {
        "id": 1,
        "name": "Active",
        "url": "http://api.pubmatic.com/v1/uas/status/1"
    },
    "user": {
        "id": 18280,
        "url": "http://api.pubmatic.com/v1/uas/users/18280"
    },
    "frequencyCaps": [{
        "frequencyCapPeriod": {
            "id": 1,
            "url":"http://api.pubmatic.com/v1/uas/frequencycapperiods/1"
        },
        "capValue": 123,
        "periodValue": 1
    }],
    "creativeAssets": [{
        "id": 2721,
        "creativeAssetType": {
            "id": 1,
            "name": "Image File"
        },
        "assetValue": "{filePath}/Logo.png"
    }, {
        "id": 2722,
        "creativeAssetType": {
            "id": 2,
            "name": "Alt Text"
        },
        "assetValue": "Alt Text"
    }, {
        "id": 2723,
        "creativeAssetType": {
            "id": 3,
            "name": "Click-through URL"
        },
        "creativeAssetProperties":
        {
            "clickThroughUrlProtocol": 1
        },
        "assetValue": "http://test.com"
    }],
    "lineItems": []
}
Response

Sample Response JSON

    

{
    "id": 433,
    "name": "Test-Creative-Image",
    "description": "Test",
    "account": {
        "id": 118385,
        "name": "PubMatic Inc.",
        "url": "http://api.pubmatic.com/v1/uas/"
    },
    "advertiser": {
        "id": 13,
        "name": "Advertiser-13",
        "url": "http://api.pubmatic.com/v1/uas/"
    },
    "creativeType": {
        "id": 2,
        "name": "Image",
        "url": "http://api.pubmatic.com/v1/uas/creativetypes/2"
    },
    "adSize": {
        "id": 2,
        "name": "Super Leaderboard - 970x90",
        "url": "http://api.pubmatic.com/v1/uas/adsizes/2"
    },
    "sslCompatibility": 0,
    "status": {
        "id": 1,
        "name": "Active",
        "url": "http://api.pubmatic.com/v1/uas/status/1"
    },
    "user": {
        "id": 18280,
        "url": "http://api.pubmatic.com/v1/uas/users/18280"
    },
    "frequencyCaps": [{
        "frequencyCapPeriod": {
            "id": 1,
            "url":"http://api.pubmatic.com/v1/uas/frequencycapperiods/1"
        },
        "capValue": 123,
        "periodValue": 1
    }],
    "creativeAssets": [{
        "id": 2721,
        "creativeAssetType": {
            "id": 1,
            "name": "Image File"
        },
        "creativeAssetProperties":{},
        "assetValue": "{filePath}/Logo.png"
    }, {
        "id": 2722,
        "creativeAssetType": {
            "id": 2,
            "name": "Alt Text"
        },
        "creativeAssetProperties":{},
        "assetValue": "Alt Text"
    }, {
        "id": 2723,
        "creativeAssetType": {
            "id": 3,
            "name": "Click-through URL"
        },
        "creativeAssetProperties":{
            "clickThroughUrlProtocol": 1
        },
        "assetValue": "http://test.com"
    }],
    "lineItems": []
}</