Brand Control API

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

The Brand Control API specification provides information using which DSPs can share their Creative Details with PubMatic.

Methods

                                       

Method Path

HTTP Method Type

Description

Link to Definition

/brandcontrol/settings/creativeReviewEnableSites

GET

This end point helps DSPs to obtain the list of PubMatic publishers that are using this feature and their sites.

Get Creative Review-enabled Sites

/brandcontrol/creatives

POST

This end point allows DSPs to submit new creatives to the PubMatic system so that they can be viewed and actioned upon by Publishers.

Create Creatives

/brandcontrol/creativesPUTThis end point allow DSPs to update the details of already submitted creatives.Update Details of Creatives

/brandcontrol/creatives

DELETE

This end point allows DSPs to inform PubMatic the list of creatives which are deleted from their system and will no longer participate in bidding process.

Delete Creatives

/brandcontrol/creatives/preferences

GET

This end point enables DSPs to pull publisher-wise list of creative IDs which are approved and/or rejected by publishers.

Get Creative Preferences

 

 

Get Creative Review-enabled Sites

Overview

This end point helps DSPs to obtain the list of PubMatic publishers that are using this feature and their sites. Note that this API will be applicable for only those publishers and their associated sites which are associated with the given DSP and are enabled for RTB Creative Review.

Request

         

URI

${URI_PREFIX}/v1/brandcontrol/settings/creativeReviewEnableSites

HTTP Method

GET

Request Headers

                 

Header Name

Type

Value

Required

Description

Authorization

String

Bearer ${access_token}

Yes

Need to send the access token generating for authentication at the place of ${access_token}.

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

Response

Response Headers        

Response Header Name

Type

Content-Type

application/json

Response Body                  

Response Body Parameter

Description

publisherId

ID of the publisher.

publisherName

Name of the publisher.

siteList

List of site IDs.

Sample Response JSON

 

[
    {
        "publisherId": 123,
        "publisherName": "xyz",
        "siteList": [
            1234,
            1235,
            1236,
            1237
        ]
    },
    {
        "publisherId": 223,
        "publisherName": "pqr",
        "siteList": [
            2234,
            2235,
            2236,
            2237
        ]
    }
]

 

 

Create Creatives

Overview

This end point allows DSPs to submit new creatives to the PubMatic system so that they can be viewed and acted upon by Publishers.

DSPs should keep sending newly-added creatives frequently to the PubMatic system, so that the publisher can take action on them, thereby allowing DSPs to bid for the right creatives on those publishers.

Request

         

URI

${URI_PREFIX}/v1/brandcontrol/creatives

HTTP Method

POST

Request Headers                      

Header Name

Type

Value

Required

Description

Content-Type

application/json

 

Yes

-

Authorization

String

Bearer ${access_token}

Yes

Need to send the access token generated for authentication at the place of ${access_token}.

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

Request Body                                                                                 

Body Parameter

Type

Required

Validations

Description

creativeId

String

Yes

Yes

Unique Identifier for each creative in the DSP’s system.

This same creativeId should be passed by DSPs during bidding as value of "creativeId" parameter.

adHeight

Integer

Yes

Yes

Height (in pixels) of the particular creative.

adWidth

Integer

Yes

Yes

Width (in pixels) of the particular creative.

creativeText

String

Yes

Yes

Represent the ad tag script, iFrame code, HTML snippet or actual URL of creative from where this creative can be downloaded.

creativeUrlType

String

Yes

Yes

Enum representing the type of creative based on the "creativeText" parameter.

Possible values are:

  • JS
  • IFRAME
  • CTAG
  • URL

landingPageURL

String

Yes

Yes

Advertiser's landing page URL. It is the URL which will be finally loaded if a user clicks on the creative.

advertiserName

String

No

No

Name of the advertiser.

iabCategory

String

No

No

Name of the IAB category.

platform

String

Yes

Yes

Represents the platform on which this particular creative is intended to be displayed.

Possible values are:

  • WEB
  • MOBILE_WEB
  • MOBILE_APP_IOS
  • MOBILE_APP_ANDROID
pmCatIdIntegerNoYesID of the PubMatic category. For a list of its values, refer the table below.
 

                                                                                                                                                                               

pmCatId values
Description
1
Alcohol
2
Auto
3
Consumer Products & Goods
4
Cosmetic Procedures
5
Dating/Personals
6
Drugs & Supplements
7
Education
8
Entertainment
9
Fashion
10
Finance
11
Military
12
News
13
Politics
14
Public service announcements
15
Religion
16
Ringtones & Downloadable
17
Sexual & Reproductive Health
18
Shopping
19
Sports
20
Survey (includes IQ tests)
21
Technology
22
Telecommunications
23
Tobacco
24
Travel
25
Video Games (Casual & Online)
26
Weight Loss
27
Consumer Services
28
Gambling
29
Online Media Services
30
Toys/Games
31
Consumer Packaged Goods
32
Manufacturing
33
Real Estate
34
Restaurants/ Fast food
35
Hospitals
36
Coupons & Deals
37
Pets
38
Job portals
39
Personal Care Toiletries and Cosmetics
40
Insurance
41
Legal Services
43
Uncategorized

Sample Request JSON

 

[
    {
        "creativeId": "creative_10",
        "adHeight": 90,
        "adWidth": 728,
        "creativeText": "http://www.google.com/abc.png",
        "creativeUrlType": "URL",
        "landingPageURL": "http://www.google.com/abc",
        "advertiserName": "google",
        "iabCategory": "iab1",
        "platform": "WEB"
    },
    {
        "creativeId": "creative_20",
        "adHeight": 90,
        "adWidth": 728,
        "creativeText": "<script>http://www.google.com/pqr.png</script>",
        "creativeUrlType": "JS",
        "landingPageURL": "http://www.google.com/pqr",
        "advertiserName": "google",
        "iabCategory": "iab2",
        "platform": "WEB"
    }
]

Response 

Response Headers

           

Response Header Name

Type

Content-Type

application/json

Sample Response JSON

 

There are four possible outcomes of this request.

  1. All creatives are successfully submitted.
  2. Some creatives are not submitted.
  3. None of the creatives are submitted.
  4. Any other server error.

 

1. All creatives are successfully submitted.

Output sample:

 

{
  "success": "true",
  "failedCreativeList": []
}

 

2. Some creatives are not submitted.

Output sample:


{
    "success": "true",
    "failedCreativeList": [
        {
            "creativeId": "creative_20",
            "adHeight": 90,
            "adWidth": 728,
            "creativeText": "<script>http://www.google.com/pqr.png</script>",
            "creativeUrlType": "JS",
            "landingPageURL": "http://www.google.com/pqr",
            "advertiserName": "google",
            "iabCategory": "iab2",
            "platform": "WEB",
            "errorCode": "CREATIVE_ALREADY_EXITS"
        }
    ]
}

 

3. None of the creatives are submitted.

Output sample:


{
    "success": "true",
    "failedCreativeList": [
        {
            "creativeId": "creative_10",
            "adHeight": -1,
            "adWidth": 728,
            "creativeText": "http://www.google.com/abc.png",
            "creativeUrlType": "URL",
            "landingPageURL": "http://www.google.com/abc",
            "advertiserName": "google",
            "iabCategory": "iab1",
            "platform": "WEB",
            "errorCode": "INVALID_ADHEIGHT"
        },
        {
            "creativeId": "creative_20",
            "adHeight": 90,
            "adWidth": 728,
            "creativeText": "<script>http://www.google.com/pqr.png</script>",
            "creativeUrlType": "JS",
            "landingPageURL": "google.com/pqr",
            "advertiserName": "google",
            "iabCategory": "iab2",
            "platform": "WEB",
            "errorCode": "INVALID_LANDING_PAGE_URL"
        }
    ]
}

 

4. Any other server error

   1. Output sample:


[
    {
        "errorCode": "SECURITY_401",
        "error": "Unauthorized"
    }
]

2. Output sample:


[
    {
        "errorCode": "INTERNAL_SERVER_ERROR",
        "error": "Fatal Error while serving the request. Please contact support team"
    }
]

Error Codes

Error Codes specific to this API method:

                                           

Error Code

Error Description

INVALID_ADHEIGHT

Invalid creative adHeight passed.

INVALID_ADWIDTH

Invalid creative adWidth passed.

INVALID_ADSIZE

Invalid combination of adWidth and adHeight passed.

INVALID_CREATIVE_ID

Invalid/Empty creative ID passed.

INVALID_LANDING_PAGE_URL

Invalid/Empty landing page URL passed.

CREATIVE_ALREADY_EXISTS

Creative already exists in the PubMatic system.

INVALID_CREATIVE_TEXT

Invalid creative text

SECURITY_401

Unauthorized access

INTERNAL_SERVER_ERROR

Internal server error

 

 

Update Details of Creatives

Overview

 

This end point allow DSPs to update the details of already submitted creatives.

Request 

         
URI${URI_PREFIX}/v1/brandcontrol/creatives
HTTP MethodPUT

Request Headers

 

                      

Header Name

Type

Value

Required

Description

Content-Type

application/json

 

Yes

-

Authorization

String

Bearer ${access_token}

Yes

Need to send the access token generating for authentication at the place of ${access_token}.

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

Request Body

 

                                             
Body Parameter
Type
Required
Validations
Description
creativeIdStringYesYes

Unique Identifier of each creative in the DSP’s system.

This same creativeId should be passed by the DSPs during bidding as value of the "creativeId" parameter.

landingPageURLStringNoYes

URL of the advertiser's landing page. It is the URL which will finally get loaded if a user clicks on the creative.

advertiserNameStringNoNoName of the advertiser.
iabCategoryStringNoNoName of the IAB category.
pmCatIdIntegerNoyesID of the PubMatic category. For a list of its values, refer the table below.
 
                                                                                                                                                                               
pmCatId value
Category
1Alcohol
2Auto
3Consumer Products & Goods
4Cosmetic Procedures
5Dating/Personals
6Drugs & Supplements
7Education
8Entertainment
9Fashion
10Finance
11Military
12News
13Politics
14Public service announcements
15Religion
16Ringtones & Downloadable
17Sexual & Reproductive Health
18Shopping
19Sports
20Survey (includes IQ tests)
21Technology
22Telecommunications
23Tobacco
24Travel
25Video Games (Casual & Online)
26Weight Loss
27Consumer Services
28Gambling
29Online Media Services
30Toys/Games
31Consumer Packaged Goods
32Manufacturing
33Real Estate
34Restaurants/ Fast food
35Hospitals
36Coupons & Deals
37Pets
38Job portals
39Personal Care Toiletries and Cosmetics
40Insurance
41Legal Services
43Uncategorized

Response 

Response Headers

           
Response Header Name
Type
Content-Type
application/json

 

Error Codes

Error Codes specific to this API method.

                       
Error Code
Error Description
INVALID_CREATIVE_IDInvalid/Empty creative ID passed.
INVALID_LANDING_PAGE_URLInvalid/Empty landing page URL passed.
SECURITY_401Unauthorized access
INTERNAL_SERVER_ERRORInternal server error

 

Examples

Sample Request JSON:
  1. Update PubMatic category id


    [
        {
            "creativeId": "creative_id_1",
            "pmCatId": 3
        }
    ]
  2. Update advertiser name


    [
        {
            "creativeId": "creative_id_1",
            "advertiserName": "google"
        }
    ]
  3. Update landing page URL

[ 
{ "
creativeId": "creative_id_1",
"landingPageURL": "http://www.yahoo.com"
}
]
  1. Update PubMatic category Id and advertiser
    [
        {
            "creativeId": "creative_id_1",
            "pmCatId": 3,
            "advertiserName": "google",
            "iabCategory": "",
            "landingPageURL": ""
        }
    ]
Sample Response JSON

 

  1. All creatives updated successfully .

Output sample:

{ 
"success": "true",
"failedCreativeList": []
}
  1. Invalid creatives were submitted for updation.

Output sample:

{ 
"success": "true",
"failedCreativeList": [
{
"creativeId": "test_1",
"landingPageURL": "http://c@@@@@hevy.com",
"advertiserName": "advertiser",
"iabCategory": "IAB17",
"errorCode": "INVALID_LANDING_PAGE_URL"
}
]
}
  1. Any other server error

1. Output sample

[ 
{
"errorCode": "SECURITY_401",
"error": "Unauthorized"
}
]

2. Output sample

[ 
{
"errorCode": "INTERNAL_SERVER_ERROR",
"error": "Fatal Error while serving the request. Please contact support team"
}
]

 

 

Delete Creatives

Overview

This endpoint allows DSPs to inform PubMatic about the list of creatives which are deleted from their system and will no longer participate in the bidding process.

Request

         

URI

${URI_PREFIX}/v1/brandcontrol/creatives

HTTP Method

DELETE

Request Headers

Header Name

Type

Required

Validations

Description

Content-Typeapplication/jsonYes--

Authorization

String

Bearer ${access_token}

Yes

Need to send the access token generating for authentication at the place of ${access_token}.

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

Sample Request JSON

 

[
    "creative_1",
    "creative_2",
    "creative_3",
    "creative_4"
]

 

Response

Sample Response JSON

 

For successful response:

{
   "success" : " true"
}

 

Examples

Request

[
    "creative_1",
    "creative_2",
    "creative_3",
    "creative_4"
]

Response

For successful request:

{
    "success": " true"
}

 

For failed request:

[
  {
    "errorCode": "INTERNAL_SERVER_ERROR",
    "error": "Fatal Error while serving the request. Please contact support team"
  }
]

 

 

Get Creative Preferences

Overview

This end point enables DSPs to pull the publisher-wise list of creative IDs which are approved and/or rejected by publishers.

DSPs can fetch the list of Publishers who are using RTB Creative Review by using the Get Creative Review-enabled Sites end point.

Every publisher has default preference for creatives. This can be either APPROVE or REJECT all creatives, by default.

This means all the creatives on which publisher has not taken any specific action, that is, neither approved nor rejected, the default creative preference (APPROVED/REJECTED) will be applied to them.

This API will return the publisher/site-wise list of approved and/or rejected creatives. All those creatives which are submitted by a DSP and are not part of publishers approved/rejected list will be applied with that publisher's default creative preference.

Request

         

URI

${URI_PREFIX}/v1/brandcontrol/creatives/preferences?publisherId=123&siteId=0&creativeStatus=ALL&sinceThisTimeStamp=0

HTTP Method

GET

Request Headers

                           

Header Name

Type

Value

Required

Validations

Description

Content-Type

application/json

-

Yes

-

-

Authorization

String

Bearer ${access_token}

Yes

 

Need to send the access token generating for authentication at the place of ${access_token}.

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

Request Query Parameters

                                      

Parameter Name

Type

Required

Validations

Description

publisherId

Long

Yes

Yes

Publisher ID for which the DSP wants the preferences of creatives they have submitted to the PubMatic system.

“publisherId=123” indicates that the data needs to be fetched for publisher 123.

Note: Publisher ID should belong from the list of valid publishers retrieved through the Get Creative Review-enabled Sites API.

siteId

Long

Yes

Yes

Site ID for which DSPs need creative preferences.

“siteId=0” indicates that data needs to be fetched for all sites of given publisherId.

Note: Site ID should belong from the list of valid publishers' sites retrieved through the Get Creative Review-enabled Sites API.

sinceThisTimeStamp

Integer

Optional

Yes

POSIX time (in seconds). If this value is specified, the result will return all the creatives’ preferences since this timestamp.

If this field’s value is null/empty/zero, then the preferences for all the creatives submitted till now will be returned.

creativeStatus

String

Required

Yes

Type of creative’s preference which the DSP needs as a part of the response.

Possible values are:

  • APPROVED
  • REJECTED
  • ALL

Sample Request JSON


${URI_PREFIX}/v1/brandcontrol/creatives/preferences?publisherId=123456&siteId=0&creativeStatus=ALL&sinceThisTimeStamp=0

Response Headers

           

Response Header Name

Type

Content-Type

application/json

 

Sample Response JSON

 

Case 1:

  • DSP1 submits creative1 and creative2.
  • Publisher1 has Site1.
  • Publisher1's default creative preference is APPROVED.
  • Publisher1 does not review creatives manually.
  • DSP1 obtains the result that is empty.
  • DSP1 can bid on Site1's inventory with creative1 or creative2.

pubId = 12345
siteId = 23456

Sample API Response for - creatives/preferences?publisherId=12345&siteId=23456&creativeStatus=ALL&sinceThisTimeStamp=0
{
  "publisherId": 12345,
  "publisherName": "Publisher1",
  "defaultCreativePreference": "APPROVED",
  "siteList": []
}

Sample API Response for - creatives/preferences?publisherId=12345&siteId=23456&creativeStatus=APPROVED&sinceThisTimeStamp=0
{
  "publisherId": 12345,
  "publisherName": "Publisher1",
  "defaultCreativePreference": "APPROVED",
  "siteList": []
}

Sample API Response for - creatives/preferences?publisherId=12345&siteId=23456&creativeStatus=REJECTED&sinceThisTimeStamp=0
{
  "publisherId": 12345,
  "publisherName": "Publisher1",
  "defaultCreativePreference": "APPROVED",
  "siteList": []
}

 

Case 2:

  • DSP1 submits creative1 and creative2.
  • Publisher1 has Site1.
  • Publisher1's default creative preference is APPROVED.
  • Publisher1 approved creative1 manually.
  • DSP1 obtains the result in which creative 1 is approved.
  • DSP1 can bid on Site1's inventory with creative1 or creative2.

pubId = 12345
siteId = 23456
creativeId = 008fd044c1fcda5af45275d673eaf35a

Sample API Response -
{
  "publisherId": 12345,
  "publisherName": "Publisher1",
  "defaultCreativePreference": "APPROVED",
  "siteList": [
    {
      "siteId": 23456,
      "siteName": "http://www.example.com",
      "approvedCreativeList": [
        "008fd044c1fcda5af45275d673eaf35a"
      ]
    }
  ]
}

 

Case 3:

  • DSP1 submits creative1 and creative2.
  • Publisher1 has Site1.
  • Publisher1's default creative preference is APPROVED.
  • Publisher1 rejected creative1 manually.
  • DSP1 obtains the result in which creative1 is rejected.
  • DSP1 can bid on Site1's inventory with creative2.

pubId = 12345
siteId = 23456
creativeId = 2c31ad319d90eb7038438716d4049eb3

Sample API Response -
{
  "publisherId": 12345,
  "publisherName": "Publisher1",
  "defaultCreativePreference": "APPROVED",
  "siteList": [
    {
      "siteId": 23456,
      "siteName": "http://www.example.com/tier1",
      "rejectedCreativeList": [
        "2c31ad319d90eb7038438716d4049eb3"
      ]
    }
  ]
}

 

Case 4:

  • DSP1 submits creative1 and creative2.
  • Publisher1 has Site1.
  • Publisher1's default creative preference is APPROVED.
  • Publisher1 approved creative1 manually.
  • Publisher1 rejected creative2 manually.
  • DSP1 obtains the result in which creative1 is approved and creative2 is rejected.
  • DSP1 can bid on Site1's inventory with creative1.

pubId = 12345
siteId = 23456
creative1 = c6b7b76010bbb65f088090bf0a45346c
creative2 = 115c08cd38c0a5654c4e3a9e5a9e2d31

Sample API Response -
{
  "publisherId": 12345,
  "publisherName": "Publisher1",
  "defaultCreativePreference": "APPROVED",
  "siteList": [
    {
      "siteId": 23456,
      "siteName": "http://www.example.com/special",
      "approvedCreativeList": [
        "c6b7b76010bbb65f088090bf0a45346c"
      ],
      "rejectedCreativeList": [
        "115c08cd38c0a5654c4e3a9e5a9e2d31"
      ]
    }
  ]
}

 

Case 5:

  • DSP1 submits creative1 and creative2.
  • Publisher1 has Site1.
  • Publisehr1's default creative preference is REJECTED.
  • Publisher1 does not review creatives manually.
  • DSP1 obtains the result that is empty.
  • DSP1 cannot bid on Site1's inventory.

pubId = 12345
siteId = 23456

Sample API Response -
{
  "publisherId": 12345,
  "publisherName": " Publisher1",
  "defaultCreativePreference": "REJECTED",
  "siteList": []
}

 

Case 6:

  • DSP1 submits creative1 and creative2.
  • Publisher1 has Site1.
  • Publisher1's default creative preference is REJECTED.
  • Publisher1 approved creative1 manually.
  • DSP1 obtains the result in which creative 1 is approved.
  • DSP1 can bid on Site1's inventory with creative1.

pubId = 12345
siteId = 23456
creativeId = f77303e44ccbbd71387efe6ac9006f89

Sample API Response -
{
  "publisherId": 12345,
  "publisherName": " Publisher1",
  "defaultCreativePreference": "REJECTED",
  "siteList": [
    {
      "siteId": 23456,
      "siteName": "http://www.example.com/",
      "approvedCreativeList": [
        "f77303e44ccbbd71387efe6ac9006f89"
      ]
    }
  ]
}

 

Case 7:

  • DSP1 submits creative1 and creative2.
  • Publisher1 has Site1.
  • Publisher1's default creative preference is REJECTED.
  • Publisher1 rejected creative1 manually.
  • DSP1 obtains the result in which creative1 is rejected.
  • DSP1 cannot bid on Site1's inventory.

pubId = 12345
siteId = 23456
creativeId = 0cd16bca7a0aa1ae2a54718a2cd268cc

Sample API Response -
{
  "publisherId": 12345,
  "publisherName": " Publisher1",
  "defaultCreativePreference": "REJECTED",
  "siteList": [
    {
      "siteId": 23456,
      "siteName": "http://www.example.com",
      "rejectedCreativeList": [
        "0cd16bca7a0aa1ae2a54718a2cd268cc"
      ]
    }
  ]
}

 

Case 8:

  • DSP1 submits creative1 and creative2.
  • Publisher1 has Site1.
  • Publisher1's default creative preference is REJECTED.
  • Publisher1 approved creative1 manually.
  • Publisher1 rejected creative2 manually.
  • DSP1 obtains the result in which creative1 is approved and creative2 is rejected
  • DSP1 can bid on Site1's inventory with creative1.
pubId = 12345
siteId = 23456
creative1 = d9e0963c83281f71afa9cab40920edef
creative2 = b8f414c9a2ac762a9b200c281a57766c

Sample API Response -
{
  "publisherId": 12345,
  "publisherName": " Publisher1",
  "defaultCreativePreference": "REJECTED",
  "siteList": [
    {
      "siteId": 23456,
      "siteName": "http://www.example.com/Mweb",
      "approvedCreativeList": [
        "d9e0963c83281f71afa9cab40920edef"
      ],
      "rejectedCreativeList": [
        "b8f414c9a2ac762a9b200c281a57766c"
      ]
    }
  ]
}

Error Codes

Error Codes specific to this API method:

                       

Error Code

Error Description

INVALID_PUBLISHER_ID

Invalid publisher ID passed.

INVALID_SITE_ID

Invalid Site ID passed.

SECURITY_401

Unauthorized

INTERNAL_SERVER_ERROR

Fatal Error while serving the request. Please contact support team

 

Error sample 1:

 

[
    {
        "errorCode": "INVALID_PUBLISHER_ID",
        "error": ""
    }
]

 

Error sample 2:

[
    {
        "errorCode": "SECURITY_401",
        "error": "Unauthorized"
    }
]

Attachments

    Outcomes