- Created by Phil Ayoub, last modified by Apurva Patil on Feb 04, 2019
The Creative API lets you Create, Update and get Creatives. It supports generic search with varied criteria to get Creative details.
Third party Creatives can associate to only the wrapper lineitem type. Third party Creatives cannot associate with standard, sponsorship, house, pmp, or rtb lineitem types.
Targetings can be associated to creatives while they are being linked to a line item. See Creative Targeting API for more details.
Supported Operations
Method Path | HTTP Method Type | Description | Link to Definition |
---|---|---|---|
/creatives/ | POST | This API method will create only one Creative per request. This will be in transaction. | Create Creative |
/creatives/native | POST | This API method is used to create Native Creatives.This will be in transaction. | Create Native Creative |
/creatives/video/redirect | POST | This 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.
| Update Creative |
/creatives/native/{id} | PUT | The API method is exposed to update single Native Creative. This will be in transaction.
| Update Native Creative |
/creatives/video/redirect/{creativeId} | PUT | The API method is exposed to update single Video Creative. This will be in transaction.
| Update Video Creative |
/creatives/html5 | POST | This 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.
| Update HTML5 Creative |
/creatives/thirdparty | POST | This API method is used to create Third Party Creatives. This will be in transaction. | Create Third Party Creative |
/creatives/thirdparty/{id} | PUT | This API method is exposed to update a single Creative. This will be in transaction.
| Update Third Party Creative |
/creatives/{id} | PATCH | The API method is exposed to perform partial update on an object; for example, 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
This is different than PUT, in that PUT fully replaces Objects. | 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 |
Request Headers and Parameters
The following tables list all headers and parameters used by the supported operations listed above.
Request Headers
Header name | Type | Value | Required | Description |
---|---|---|---|---|
Content-Type | String | application/json | Yes | Media type for request. |
Authorization | String | Bearer ${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 Name | Type | Required | Validations | Descriptions | ||||||
---|---|---|---|---|---|---|---|---|---|---|
name | String | Yes | 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. | ||||||
description | String | No | Description can be a maximum of 1024 characters. Default is null. | Description to store more details about Creative. | ||||||
account | Numeric | Yes | Account of publisher for which this Creative is created. | Account of the Publisher. | ||||||
advertiser | Integer | Yes | Advertiser should be valid and exist. | Advertiser for the Creative. You can create/edit/retrieve a list of advertiser using the Advertising API. | ||||||
creativeType | Integer | Yes | CreativeType should be valid and exists. | Type of Creative. You can retrieve the list of creative types using the Creative Type API. | ||||||
adSize | Integer | Yes | AdSize should be valid and exist. | Size for creative. | ||||||
sslCompatibility | Integer | Yes | Value should be 0 ( non- secured ) or 1 ( Secured ) | SSL Compatibility for the creative:
Important Notes:
| ||||||
status | Numeric | No | Status should be valid and exists. Default is "Active" for newly created Creative if not provided. | Status of the Creative. You can retrieve the list of status using the Status API. | ||||||
user | String | Yes | User 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. | ||||||
frequencyCap | Numeric | No | Frequency should be valid. | Frequency cap of Creative. Frequency Caps are not supported for third party creatives. | ||||||
creativeAssets | Array | Yes | A creative should have at least one asset. Validations for assetValue based on creativeAssetType: Image File:
Alt Text:
Click-through URL:
Creative Title:
Creative Description:
Native Asset:
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:
Video Protocol:
VPAID Support:
HTML FIle:
Code Snippet :
| Assets of Creative. You can retrieve the list of Asset Types using the Creative Asset Type API. See the Creative Asset Type table below to view the required Creative Assets for a particular Creative Type. See the Native Creative Assets table below for applicable Native Creative options. | ||||||
lineitems | Array | No | Line Items Associated with Creative. Use this field to provide information, not when creating or updating a creative. You can retrieve the list of Asset Types using Line Item API. | |||||||
trackingEvents | Array | No |
| Tracking events associated with the Creatives. You can retrieve the list of Asset Types using Tracking Events API If a creative is not configured for a click through URL, the configured Third Party Click Tracking at Creative Level will not execute/trigger. See Tracking Events table below for valid tracking events for different types of creatives. |
Creative Asset Type
ID | Creative Type | Creative Asset ID | Creative Asset Type | Mandatory* |
2 | Image | 1 | Image File | True |
2 | Alt Text | False | ||
3 | Click-through URL | False | ||
4 | Text | 3 | Click-through URL | False |
4 | Creative Title | True | ||
6 | Creative Description | False | ||
6 | Video | 8 | VAST Tag URL | True |
11 | Video Protocol | True | ||
12 | VPAID Support | True | ||
7 | Rich Media | 3 | Click-through URL | False |
10 | Rich Media Tag | True | ||
8 | HTML5 | 13 | HTML File | True |
3 | Click Through URL | False | ||
5 | Third Party | 5 | Code Snippet | True |
*If Mandatory is False, it means you may have the field but it may contain an empty value.
Native Creative Assets
NativeAssetTypeId | NatveAssetSubTypeId | Name |
---|---|---|
2 | 1 | icon |
2 | 2 | logo |
2 | 3 | main |
3 | 1 | sponsored |
3 | 2 | desc |
3 | 3 | rating |
3 | 4 | likes |
3 | 5 | downloads |
3 | 6 | price |
3 | 7 | saleprice |
3 | 8 | phone |
3 | 9 | address |
3 | 10 | desc2 |
3 | 11 | displayurl |
3 | 12 | ctatext |
Tracking Events
ID | Creative Type | Tracking Event ID | Tracking Event Name |
---|---|---|---|
2 | Image | 1 | Click Tracking |
9 | Impression Tracking | ||
3 | Native | 1 | Click Tracking |
9 | Impression Tracking | ||
4 | Text | 1 | Click Tracking |
9 | Impression Tracking | ||
6 | Video | 1 | Click Tracking |
2 | Complete | ||
3 | Creative View | ||
4 | Custom Click | ||
5 | First Quartile | ||
6 | Mid Point | ||
7 | Start | ||
8 | Third Quartile | ||
7 | Rich Media | 1 | Click Tracking |
9 | Impression Tracking | ||
8 | HTML5 | 1 | Click Tracking |
9 | Impression Tracking | ||
5 | Third Party | 9 | Impression Tracking |
Operations and Samples
The following sections describe the Creative API operations and provide sample code to demonstrate usage. Unless otherwise noted in the operation definition, each operation uses the request headers and request body parameters listed above.
Create a Creative
This API lets you create a Creative. You can include only one Creative in each request.
Request
URI | HTTP Method |
---|---|
https://api.pubmatic.com/v1/uas/creatives/ | POST |
Notes:
- See Request Headers above for request header requirements.
- See Request Body Parameters for parameters available to use in this request.
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
This API lets you create a Native Creative. You can create only one Creative per request.
Request
URI | HTTP Method |
---|---|
https://api.pubmatic.com/v1/uas/creatives/native | POST |
Notes:
- See Request Headers above for request header requirements.
- See Request Body Parameters for parameters available to use in this request.
Additional Request Body Parameter for Native Creative
Parameter Name | Type | Required | Validation | Description |
---|---|---|---|---|
nativeTemplateConfig | Integer | Yes | 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
This API enables the creation of a Video Creative. Only one Creative per request.
Request
URI | HTTP Method |
---|---|
https://api.pubmatic.com/v1/uas/creatives/video/redirect | POST |
Notes:
- See Request Headers above for request header requirements.
- See Request Body Parameters for parameters available to use in this request.
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
This API fetches the details for the specified Creative.
Request
URI | HTTP Method |
---|---|
https://api.pubmatic.com/v1/uas/creatives/{creativeid} | GET |
Notes:
- See Request Headers above for request header requirements.
- The creative id is the only required parameter for this request.
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
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
URI | HTTP Method |
---|---|
https://api.pubmatic.com/v1/uas/creatives/ | GET |
Notes:
- See Request Headers above for request header requirements.
- There is no required parameter for this request.
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
This API enables you to Update a Creative.
Request
URI | HTTP Method |
---|---|
https://api.pubmatic.com/v1/uas/creatives/{creativeid} | PUT |
Notes:
- See Request Headers above for request header requirements.
- See Request Body Parameters for parameters available to use in this request.
Sample Request URL
https://api.pubmatic.com/v1/uas/creatives/native/433
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": [] }
Update Native Creative
This API enables you to update a Native Creative.
Request
URI | HTTP Method |
---|---|
https://api.pubmatic.com/v1/uas/creatives/native/{creativeid} | PUT |
Notes:
- See Request Headers above for request header requirements.
- See Request Body Parameters for parameters available to use in this request.
Additional Request Body Parameters for Native Creative
Parameter Name | Type | Required | Validation | Description |
---|---|---|---|---|
nativeTemplateConfig | Integer | Yes | 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/432
Sample Request JSON
{ "id": 432, "name": "Test-Creative-Native", "description": "Test Description", "account": { "id": 118385 }, "advertiser": { "id": 13 }, "creativeType": { "id": 3 }, "sslCompatibility": 0, "status": { "id": 1 }, "frequencyCaps": [{ "frequencyCapPeriod": { "id": 1 }, "capValue": 123, "periodValue": 1 }], "creativeAssets": [{ "id": 2716, "creativeAssetType": { "id": 3 }, "properties": { "clickThroughUrlProtocol": 1 }, "assetValue": "http://test.com" }, { "id": 2717, "creativeAssetType": { "id": 9 }, "nativeAssetTypeId": 1, "assetValue": "Title", "nativeAssetId": 1 }, { "id": 2718, "creativeAssetType": { "id": 9 }, "nativeAssetTypeId": 2, "nativeAssetSubTypeId": 1, "assetValue": "{filePath}/Logo.png", "nativeAssetId": 2 }, { "id": 2719, "creativeAssetType": { "id": 9 }, "nativeAssetTypeId": 3, "nativeAssetSubTypeId": 12, "assetValue": "CTA Text", "nativeAssetId": 3 }, { "id": 2720, "creativeAssetType": { "id": 9 }, "nativeAssetTypeId": 3, "nativeAssetSubTypeId": 3, "assetValue": "6", "nativeAssetId": 4 }], "lineItems": [], "nativeTemplateConfig": { "id": 9 "url": "http://api.pubmatic.com/v1/uas" } }
Response
Sample Response JSON
{ "id": 432, "name": "Test-Creative-Native", "description": "Test Description", "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://$URI_PREFIX/{apiVersion}/phoenix" } }
Update Video Creative
This API lets you update a Video Creative.
Request
URI | HTTP Method |
---|---|
https://api.pubmatic.com/v1/uas/creatives/video/redirect/{creativeid} | PUT |
Notes:
- See Request Headers above for request header requirements.
- See Request Body Parameters for parameters available to use in this request.
Sample Request URL
https://api.pubmatic.com/v1/uas/creatives/video/redirect/431
Sample Request JSON
{ "id": 431, "name": "Test-Creative-Video", "description": "Test Description", "account": { "id": 118385 }, "advertiser": { "id": 13 }, "creativeType": { "id": 6 }, "adSize": { "id": 51 }, "sslCompatibility": 0, "status": { "id": 1 }, "frequencyCaps": [{ "frequencyCapPeriod": { "id": 1 }, "capValue": 123, "periodValue": 1 }], "creativeAssets": [{ "id": 2713, "creativeAssetType": { "id": 8 }, "assetValue": "https://api.pubmatic.com/v1/uas/test_vast/vast1.xml" }, { "id": 2714, "creativeAssetType": { "id": 11 }, "assetValue": "3" }, { "id": 2715, "creativeAssetType": { "id": 12 }, "assetValue": "2" }], "lineItems": [], "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 Description", "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" }, "creativeAssetProperties":{}, "assetValue": "https://api.pubmatic.com/v1/uas/test_vast/vast1.xml" }, { "id": 2714, "creativeAssetType": { "id": 11, "name": "Video Protocol" }, "creativeAssetProperties":{}, "assetValue": "3" }, { "id": 2715, "creativeAssetType": { "id": 12, "name": "VPAID Support" }, "creativeAssetProperties":{}, "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": [] } }
Create HTML5 Creative
This API lets you create an HTML5 Creative.
Request
URI | HTTP Method |
---|---|
https://api.pubmatic.com/v1/uas/creatives/html5 | POST |
Notes:
- See Request Headers above for request header requirements.
- See Request Body Parameters for parameters available to use in this request.
Sample Request URL
https://api.pubmatic.com/v1/uas/creatives/html5
Sample Request JSON
{ "name": "Demo_HTML5", "description": "", "status": { "id": 1 }, "account": { "id": 118385 }, "advertiser": { "id": 3 }, "creativeType": { "id": 8 }, "adSize": { "id": 113 }, "sslCompatibility": 0, "creativeAssets": [{ "id": 5138, "creativeAssetType": { "id": 13 }, "assetValue": "http://phoenixorigin.pubmatic.com/files/publisher/118385/18280/PubMaticAdServer/Creative/a1e17698-9b97-4865-8b2b-59ef8f19a2b5/three_index.htm", "properties": {} }, { "id": 5139, "creativeAssetType": { "id": 3 }, "assetValue": "three.com", "properties": { "clickThroughUrlProtocol": 1 } }], "frequencyCaps": [], "trackingEvents": [{ "id": 1, "trackingUrl": "http://clicktracker.com" }, { "id": 9, "trackingUrl": "http://imptracker.com" }], "lineItems": [] }
Response
Sample Response JSON
{ "id": 1335, "name": "Demo_HTML5", "description": "", "account": { "id": 118385 }, "advertiser": { "id": 3, "name": "Pepsi" }, "creativeType": { "id": 8, "name": "HTML5" }, "adSize": { "id": 113, "name": "Micro Bar - 88x31" }, "sslCompatibility": 0, "status": { "id": 1, "name": "Active" }, "user": { "id": 18280 }, "frequencyCaps": [], "creativeAssets": [{ "id": 5138, "creativeAssetType": { "id": 13, "name": "HTML5 File" }, "assetValue": "http://phoenixorigin.pubmatic.com/files/publisher/118385/18280/PubMaticAdServer/Creative/a1e17698-9b97-4865-8b2b-59ef8f19a2b5/three_index.htm", "properties": {} }, { "id": 5139, "creativeAssetType": { "id": 3, "name": "Click-through URL" }, "assetValue": "three.com", "properties": { "clickThroughUrlProtocol": 1 } }], "lineItems": [], "trackingEvents": [{ "id": 1, "name": "Click Tracking", "trackingUrl": "http://clicktracker.com" }, { "id": 9, "name": "Impression Tracking", "trackingUrl": "http://imptracker.com" }] }
Update HTML5 Creative
This API updates the specified HTML5 Creative.
Request
URI | HTTP Method |
---|---|
https://api.pubmatic.com/v1/uas/creatives/html5/{creativeId} | PUT |
Notes:
- See Request Headers above for request header requirements.
- See Request Body Parameters for parameters available to use in this request.
Sample Request URL
https://api.pubmatic.com/v1/uas/creatives/html5/433
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": [] }
Create Third Party Creative
This API enables the creation of an Third Party Creative.
Request
URI | HTTP Method |
---|---|
https://api.pubmatic.com/v1/uas/creatives/thirdparty | POST |
Notes:
- See Request Headers above for request header requirements.
- See Request Body Parameters for parameters available to use in this request.
Sample Request URL
https://api.pubmatic.com/v1/uas/creatives/thirdparty
Sample Request JSON
{ "name": "RD_Creative_Wrapper_Target_728x90_copy", "description": "RD_Creative_Wrapper_Target_728x90", "status": { "id": 1 }, "account": { "id": 130917 }, "creativeType": { "id": 5 }, "adSize": { "id": 7 }, "sslCompatibility": 0, "creativeAssets": [{ "id": 83484, "creativeAssetType": { "id": 5 }, "assetValue": "<script type='text/javascript'>\nvar i = 0, w = window.self;\nwhile(w!== window.top && !(w.PWT && w.PWT.displayCreative) && i<10){\n w = window.self.parent; i++;\n}\ntry{ w.PWT.displayCreative(document, '%%VAR_pwtsid%%'); } catch(e){}\n</script>\n\nRD_TEXT=%%VAR_RD_TEXT%%", "properties": {} }], "frequencyCaps": [], "trackingEvents": [{ "id": 9, "trackingUrl": "http://www.imdb.com?AU=%%AD_UNIT_ID%%&PROTO=%%PROTOCOL%%&AU_URL=%%AD_UNIT_URL_ESC%%&CC=%%COPPA_COMPLIANT%%&IP=%%IP%%&UA=%%USERAGENT%%&TIME=%%TIMESTAMP%%&TZ=%%TIMEZONE%%&SEC=%%IS_SECURE%%&RD_Numbers=%%VAR_RD_Numbers%%&RD_TEXT=%%VAR_RD_TEXT%%" }], "advertiser": { "id": 10000001 }
Response
Sample Response JSON
{ "id": 433, "name": "RD_Creative_Wrapper_Target_728x90_copy", "description": "RD_Creative_Wrapper_Target_728x90", "status": { "id": 1 }, "account": { "id": 130917 }, "creativeType": { "id": 5 }, "adSize": { "id": 7 }, "sslCompatibility": 0, "creativeAssets": [{ "id": 83484, "creativeAssetType": { "id": 5 }, "assetValue": "<script type='text/javascript'>\nvar i = 0, w = window.self;\nwhile(w!== window.top && !(w.PWT && w.PWT.displayCreative) && i<10){\n w = window.self.parent; i++;\n}\ntry{ w.PWT.displayCreative(document, '%%VAR_pwtsid%%'); } catch(e){}\n</script>\n\nRD_TEXT=%%VAR_RD_TEXT%%", "properties": {} }], "frequencyCaps": [], "trackingEvents": [{ "id": 9, "trackingUrl": "http://www.imdb.com?AU=%%AD_UNIT_ID%%&PROTO=%%PROTOCOL%%&AU_URL=%%AD_UNIT_URL_ESC%%&CC=%%COPPA_COMPLIANT%%&IP=%%IP%%&UA=%%USERAGENT%%&TIME=%%TIMESTAMP%%&TZ=%%TIMEZONE%%&SEC=%%IS_SECURE%%&RD_Numbers=%%VAR_RD_Numbers%%&RD_TEXT=%%VAR_RD_TEXT%%" }], "advertiser": { "id": 10000001 } }
Update Third Party Creative
This API updates the specified Third Party Creative.
Request
URI | HTTP Method |
---|---|
https://api.pubmatic.com/v1/uas/creatives/thirdparty/{creativeId} | PUT |
Notes:
- See Request Headers above for request header requirements.
- See Request Body Parameters for parameters available to use in this request.
Sample Request URL
https://api.pubmatic.com/v1/uas/creatives/thirdparty/433
Sample Request JSON
{ "id": 433, "name": "RD_Creative_Wrapper_Target_728x90_copy", "description": "RD_Creative_Wrapper_Target_728x90", "status": { "id": 1 }, "account": { "id": 130917 }, "creativeType": { "id": 5 }, "adSize": { "id": 7 }, "sslCompatibility": 0, "creativeAssets": [{ "id": 83484, "creativeAssetType": { "id": 5 }, "assetValue": "<script type='text/javascript'> \nvar i = 0, w = window.self; \nwhile(w!== window.top && !(w.PWT && w.PWT.displayCreative) && i<10){ \n w = window.self.parent; i++; \n} \ntry{ w.PWT.displayCreative(document, '%%VAR_pwtsid%%'); } catch(e){} \n</script> \n \nRD_TEXT=%%VAR_RD_TEXT%%", "properties": {} }], "frequencyCaps": [], "trackingEvents": [{ "id": 9, "trackingUrl": "http://www.imdb.com?AU=%%AD_UNIT_ID%%&PROTO=%%PROTOCOL%%&AU_URL=%%AD_UNIT_URL_ESC%%&CC=%%COPPA_COMPLIANT%%&IP=%%IP%%&UA=%%USERAGENT%%&TIME=%%TIMESTAMP%%&TZ=%%TIMEZONE%%&SEC=%%IS_SECURE%%&RD_Numbers=%%VAR_RD_Numbers%%&RD_TEXT=%%VAR_RD_TEXT%%" }], "advertiser": { "id": 10000001 } }
Response
Sample Response JSON
{ "id": 433, "name": "RD_Creative_Wrapper_Target_728x90_copy", "description": "RD_Creative_Wrapper_Target_728x90", "status": { "id": 1 }, "account": { "id": 130917 }, "creativeType": { "id": 5 }, "adSize": { "id": 7 }, "sslCompatibility": 0, "creativeAssets": [{ "id": 83484, "creativeAssetType": { "id": 5 }, "assetValue": "<script type='text/javascript'> \nvar i = 0, w = window.self; \nwhile(w!== window.top && !(w.PWT && w.PWT.displayCreative) && i<10){ \n w = window.self.parent; i++; \n} \ntry{ w.PWT.displayCreative(document, '%%VAR_pwtsid%%'); } catch(e){} \n</script> \n \nRD_TEXT=%%VAR_RD_TEXT%%", "properties": {} }], "frequencyCaps": [], "trackingEvents": [{ "id": 9, "trackingUrl": "http://www.imdb.com?AU=%%AD_UNIT_ID%%&PROTO=%%PROTOCOL%%&AU_URL=%%AD_UNIT_URL_ESC%%&CC=%%COPPA_COMPLIANT%%&IP=%%IP%%&UA=%%USERAGENT%%&TIME=%%TIMESTAMP%%&TZ=%%TIMEZONE%%&SEC=%%IS_SECURE%%&RD_Numbers=%%VAR_RD_Numbers%%&RD_TEXT=%%VAR_RD_TEXT%%" }], "advertiser": { "id": 10000001 } }
Patch a Creative
This API updates only the requested Order attributes for the given creative ID.
Request
URI | HTTP Method |
---|---|
https://api.pubmatic.com/v1/uas/creatives/ | PATCH |
Notes:
- See Request Headers above for request header requirements.
- See Request Body Parameters for parameters available to use in this request.
Sample Request URL
https://api.pubmatic.com/v1/uas/creatives/
Sample Request JSON
{ "name": "creative updated patch" }
Response
Sample Response JSON
{ "id": 433, "name": "creative updated patch", "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" }, "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": [] }
Delete a Creative
This API deletes a Creative (changes the status to "archived").
Request
URI | HTTP Method |
---|---|
https://api.pubmatic.com/v1/uas/creatives/{creativeid} | DELETE |
Notes:
- See Request Headers above for request header requirements.
- The creative id is the only required parameter for this request.
Request URL
https://api.pubmatic.com/v1/uas/creatives/1
Response
Sample Response JSON
Returns true if successful; false if unsuccessful. |
Error Codes For Unified Ad Server Creative API
Sr. No | Error Codes | Description |
---|---|---|
1. | PH_MISSING_OR_INVALID_PARAMETER | It can occur in following cases
|
2. | PH_DUPLICATE_ENTITY | It can occur in the Name field. |
3. | PH_PARAMETER_VALUE_TOO_LARGE | It can occur in the Name field. |
4. | PH_UNSUPPORTED_VALUE | This error occurs when a user tries to enter an unsupported value for a particular field. It can occur for the 'status' field. |
5. | PH_CANNOT_CREATE_RECORD_FOR_SSP_ADVERTISER | This error occurs when user tries to create a creative for SSP type of Advertiser. |
6. | PH_UNSUPPORTED_TRACKING_EVENT_IN_REQUEST | This error occurs when a user provides unsupported tracking event. |
7. | PH_DUPLICATE_TRACKING_EVENT_NOT_ALLOWED | This error occurs when user provides duplicate tracking events. |
8. | PH_MASTER_CREATIVE_NOT_SUPPORTED_FOR_CREATIVE_TYPE | This error occurs when user provides a master creative for a non-video type of creative. |
9. | PH_ENTITY_NOT_BELONGS_TO_ACCOUNT | This error occurs when a user provides an account different than that of its Advertiser. |
10. | PH_ATLEAST_ONE_CREATIVE_ASSET_REQUIRED | This error occurs when user does not provide any creative assets. |
11. | PH_DUPLICATE_ENTRIES_FOUND | This error occurs when a user provides duplicate creative assets. |
12. | PH_UNSUPPORTED_CREATIVE_TYPE_IN_REQUEST | This error occurs when a user provides an unsupported creative asset for a particular creative type. |
13. | PH_MISSING_CREATIVE_ASSET_IN_REQUEST | This error occurs when a user does not provide a required creative asset for a particular creative type. |
14. | PH_INVALID_CREATIVE_ASSET_PROPERTIES | This can occur in the following cases:
|
15. | PH_INCORRECT_NATIVE_ASSET_TYPE_SUB_TYPE | This error occurs if user provides the wrong combination of nativeAssetId and its nativeAssetTypeId and nativeAssetSubTypeId as defined in the asset object of the corresponding native template. |
16. | PH_INCORRECT_ONE_CLICK_TRACKING_EVENT_ALLOWED | This error occurs if a Click Tracking Event is provided more than once for any Creative. |
17. | PH_INVALID_RATING_VALUE | This error occurs if a user provides the Native Creative Rating either <0, >5.0 or Non-Numeric. |
18. | PH_UNSUPPORTED_PROTOCOL | This error occurs if a user provides HTTP protocol for Image URL, File URL path if the creative is marked as SSL Compatible. |
19. | PH_UNSUPPORTED_URL | This error occurs if user provides unsupported URL format in the Tracking Events URL Valid URLs start with one of the following protocols:
|
20. | PH_UNSUPPORTED_FIELD_FOR_ENTITY_TYPE | This error occurs when trying to configure frequencyCaps for third party creative. |
Third party Creatives can associate to only the wrapper lineitem type. Third party Creatives cannot associate with standard, sponsorship, house, pmp, or rtb lineitem types.