AG Creatives APIs

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

Note: Creatives cannot be approved or rejected, therefore, the status of creatives will remain as "pending," regardless of actual status. This feature is expected to be updated in future iterations of Automated Guaranteed.

                   

Creatives are the image, video, or other medium assigned to a line item in an order for display within the ad unit when the publisher's ad server delivers the impressions. Currently, only creative tags are supported which will be tags that point to an advertiser's ad server and will serve the creative directly into the publisher's ad server. Creatives may be assigned to multiple line items and orders without limitation. They may also be assigned to line items after an order is approved, or during the negotiation process. 

 

Within PubMatic, creatives have to be approved by the publisher before they can be trafficked to a webpage. Creatives can be assigned or removed from a line item for purposes of updating the creative at any time, even after the order is approved and contract signed. However, the creative entity itself cannot be edited once the creative is approved by the publisher. Before it is approved, any of its properties may be edited, but not after. This is because the approve/reject status is held at the overall creative level. Therefore, if the creative is already approved, we don't want to have the creative potentially changed while it is delivering impressions. Instead, the creative on the line item should be disassociated with the line item and the new creative should be assigned to the line item and go through the approval process with the publisher. A change request is not needed to do this. 

 

Methods

                                                               

Method PathHTTP Method TypeDescriptionLink to Definition
/creatives/POSTCreate a new AG creative 

Creating a Creative

/creatives/allGETFind all AG creativesFinding all Creatives
/creatives/associatePOSTAssociates an AG creative with a publisherAssociating a Creative with a Publisher
/creatives/bulkAssociatePOSTAssociates an AG creative with a publisherAssociating a List of Creatives with a Publisher
/creatives/findGETFind an AG creativeFinding a Creative
/creatives/statusGETGet AG creative status by publisherGet Creatives Status by Publisher
/creatives/statusPUTApprove or reject an AG creativeApprove or Reject an AG Creative
/creatives/status/allGETFind all AG creative statusesFind all AG Creatives Statuses
/creatives/{id}GETGet AG creativeGet an AG Creative

 

 

Creating an AG Creative

 

Overview

This API enables the creation of an AG creative in the PubMatic system by Demand Partners (not Publishers).

Request       

URIHTTP Method

$URI_PREFIX/creatives

POST

Request Headers                               

Header NameTypeValueRequiredDescription
pubTokenString

${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

resourceId

Integer 

Yes

Resource ID (Owner ID)

resourceTypeId 

Integer 

Yes

Type of Resource (e.g., Demand Partner = 5)

Request Body Parameters                                                                        

Body Parameter

Type

Required

Validations

Description

externalID

String

Yes

 ID used by external service
nameStringNo Name of the creative
advertiserStringYes Name of the advertiser
widthIntegerYes Width of the creative

height

Integer

Yes

 

Height of creative

tagStringYes Tag associated with the creative
urlStringYes URL of creative

ownerId

Integer

Yes

Owner ID should be valid. Value should already exist in the system.

Resource ID of the creator of the creative

ownerTypeId

Integer

Yes

Demand Partner (5).

Resource type ID of the creator of this creative. Only demand partners (Type 5) can create a creative.

Request URL     

GET $URI_PREFIX/creatives/

Sample Request JSON

{
  "externalId": "Advert_101",
  "name": "Creative Name",
  "advertiser": "Advert_Co",
  "width": 728,
  "height": 90,
  "tag": "test_tag",
  "url": "htttp://www.google.com",
  "ownerId": 301,
  "ownerTypeId": 5
}

Response

Response Code

         

TypeDescription
200 Success

Response Header          

Response Header NameType
Content-typeapplication/json

Sample Response JSON    

{
  "id": 41,
  "externalId": "new creative 7616-1-3",
  "advertiser": "Advertiser Co",
  "width": 728,
  "height": 90,
  "tag": "tag",
  "url": "http://www.ourdomain.com",
  "ownerId": 737,
  "ownerTypeId": 5
}

Error Codes

StatusReasonDescription
401UnauthorizedAuthentication or Authorization failure. Check the response body for specific details.
403ForbiddenThe request was a valid request, but the server is refusing to respond to it. 403 error semantically means "unauthorized", i.e. the user does not have the necessary permissions for the resource.
404Not FoundThe requested resource could not be found.

Find All AG Creatives

Overview

This API allows you to find all AG Creatives from PubMatic.

Request           

URIHTTP Method

$URI_PREFIX/creatives/all

GET

Request Headers             

Header NameTypeValueRequiredDescription
pubTokenString${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

resourceId

Integer 

Yes

Resource ID (Owner ID)

resourceTypeId 

Integer 

Yes

Type of Resource (e.g., Publisher = 1)

Request Query Parameters                           

ParameterTypeRequiredDescription
pageNumberIntegerNoThe page number the response should begin (in the case of multiple pages). Default value is 1.
pageSizeIntegerNoMaximum number of records to be included in the response. Its default value is 100.
filtersArray[string]No

Filters list, filter syntax:[field operation value], valid operations: eq noteq like notlike. See Filter Parameter Details for more information.

Note that multiple Ids can be entered in a filter to retrieve details for more than one ID.

Sample Request URL

GET $URI_PREFIX/creatives/all?{pageNumber}&{pageSize}

Response

Sample Response JSON

    

{
  "content": [
    {
      "id": 27,
      "externalId": "Creative-Leaderboard-728X90",
      "advertiser": "365Loans.com",
      "width": 728,
      "height": 90,
      "tag": "< >",
      "url": "http://www.ourdomain.com",
      "ownerId": 31445,
      "ownerTypeId": 1
    },
   
  ],
  "last": false,
  "totalPages": 1,
  "totalElements": 2,
  "sort": [
    {
      "direction": "DESC",
      "property": "id",
      "ignoreCase": false,
      "nullHandling": "NATIVE",
      "ascending": false
    }
  ],
  "numberOfElements": 2,
  "first": true,
  "size": 2,
  "number": 0
}

Response Code

           

TypeDescription
200OK

Response Header

             
Response Header Name
Type
Description
content-Typeapplication/jsonMedia type that is to be returned in search/sort operation

 

Error Codes

                       

Status

Error Message

Description

401

Unauthorized

Authentication or Authorization failure. Check the response body for specific details.

403

Forbidden

You are not subscribed to this feature of the Platform.
404Not FoundThe requested resource could not be found but may be available in the future. Subsequent requests are permissible.

 

 

Associate an AG Creative with a Publisher

 

Overview

This API allows you to associate an AG Creative with a publisher.

 

Request

URIHTTP Method

$URI_PREFIX//creatives/associate

POST

 

Request Headers     

Header NameTypeValueRequiredDescription
pubTokenString$(access_token)YesNeed 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

resourceId

Integer 

Yes

Resource ID (Owner ID)

resourceTypeId 

Integer 

Yes

Type of Resource (e.g., Publisher=1)

 

Request Body Parameters         

Body ParameterTypeRequiredValidationsDescription
publisherIdIntegerYesValid IDPublisher ID
creativeIdIntegerYesValid IDCreative ID

Request URL

GET $URI_PREFIX/creatives/associate

Sample Request JSON

{
  "publisherId": 31445,
  "creativeId": 34
}

Response 

Sample Response JSON

{
  "id": 23,
  "publisherId": 31445,
  "creative": {
    "id": 34,
    "externalId": "NTcreative 12345",
    "name": "NT Creative ",
    "advertiser": "Advertiser",
    "width": 728,
    "height": 90,
    "tag": "tag",
    "url": "http://www.ourdomain.com",
    "ownerId": 737,
    "ownerTypeId": 5
  },
  "creativeStatus": "PENDING"
}

Response Parameters

Body ParameterTypeDescription
idIntegerGenerated ID of the publisher that needs to approve/rejet the creative
publisherIdIntegerPublisher ID
creativeIdIntegerID of the Creative
externalIdStringID used by external service
nameStringName of Creative
advertiserStringName of Advertiser
widthIntegerWidth of the Creative
heightIntegerHeight of the Creative
tagStringTag associated with the Creative
urlStringURL of creative
ownerIdIntegerOwner ID (Resource ID) of the creator of the creative
ownerTypeIdIntegerType of Owner (Resource) of the creative
creativeStatusStringThe assigned status of the creative (e.g., PENDING, REJECTED, APPROVED)

Response Code

TypeDescription
200 Success

 

Sample Response JSON

{
  "id": 20,
  "publisherId": 301,
  "creative": {
    "id": 29,
    "externalId": "Advert_101",
    "name": "string",
    "advertiser": "Advert_Company",
    "width": 0,
    "height": 0,
    "tag": "string",
    "url": "string",
    "ownerId": 301,
    "ownerTypeId": 1
  },
  "creativeStatus": "APPROVED"
}

                        

Response Messages

StatusReasonDescription
201CreatedThe request has been fulfilled, resulting in the creation of a new resource.
401UnauthorizedAuthentication or Authorization failure. Check the response body for specific details.
403ForbiddenThe request was a valid request, but the server is refusing to respond to it. 403 error semantically means "unauthorized", i.e. the user does not have the necessary permissions for the resource.
404Not FoundThe requested resource could not be found.

 

 

Associate a List of AG Creatives with a Publisher

 

Overview

This API allows you to associate a list of AG creatives for a publisher.

Request           

URI

HTTP Method

$URI_PREFIX/creatives/bulkAssociate

POST

Request Headers                              

Header NameTypeValueRequiredDescription
pubTokenString$(access_token)YesNeed 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

resourceId

Integer 

Yes

Resource ID (Owner ID)

resourceTypeId 

Integer 

Yes

Type of Resource (e.g., Publisher=1)

Request Body Parameters                      

Body ParameterTypeRequiredValidationsDescription
publisherIdIntegerYesValid IDPublisher ID
creativeIdIntegerYesValid IDCreative ID

Request URL    

GET $URI_PREFIX/creatives/bulkAssociate

Sample Request JSON  

[
  {
    "publisherId": 31445,
    "creativeId": 34
  },
  {
    "publisherId": 31445,
    "creativeId": 33
  }
]

Response

Sample Response JSON

 

[
  {
    "id": 23,
    "publisherId": 31445,
    "creative": {
      "id": 34,
      "externalId": "new test creative 12345",
      "name": "new test creative 12345",
      "advertiser": "Advertiser",
      "width": 728,
      "height": 90,
      "tag": "tag",
      "url": "http://www.google.com",
      "ownerId": 737,
      "ownerTypeId": 5
    },
    "creativeStatus": "PENDING"
  },
  {
    "id": 22,
    "publisherId": 31445,
    "creative": {
      "id": 33,
      "externalId": "123456",
      "advertiser": " 247RealEstateLoans.com",
      "width": 728,
      "height": 90,
      "tag": "<>",
      "url": "http://google.com",
      "ownerId": 31445,
      "ownerTypeId": 1
    },
    "creativeStatus": "APPROVED"
  }
]

                                                                     

Response Parameters

Body ParameterTypeDescription
idIntegerGenerated ID of the publisher that needs to approve/rejet the creative
publisherIdIntegerPublisher ID
creativeIdIntegerID of the Creative
externalIdStringID used by external service
nameStringName of Creative
advertiserStringName of Advertiser
widthIntegerWidth of the Creative
heightIntegerHeight of the Creative
tagStringTag associated with the Creative
urlStringURL of creative
ownerIdIntegerOwner ID (Resource ID) of the creator of the creative
ownerTypeIdIntegerType of Owner (Resource) of the creative
creativeStatusStringThe assigned status of the creative (e.g., PENDING, REJECTED, APPROVED)

Response Code           

TypeDescription
200

 Success

Response Header           

Response Header NameType
content-typeapplication/json

Messages              

StatusReasonDescription
201CreatedThe request has been fulfilled, resulting in the creation of a new resource.
401UnauthorizedAuthentication or Authorization failure. Check the response body for specific details.
403ForbiddenThe request was a valid request, but the server is refusing to respond to it. 403 error semantically means "unauthorized", i.e. the user does not have the necessary permissions for the resource.
404Not FoundThe requested resource could not be found.

 

 

Find an AG Creative

 

Overview

This API allows you to find an AG Creative.

Request

URIHTTP Method

$URI_PREFIX/creatives/find

GET

Request Headers                           

Header NameTypeValueRequiredDescription
pubTokenString${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

resourceId

Integer 

Yes

Resource ID (Owner ID)

resourceTypeId 

Integer 

Yes

Type of Resource (e.g., Publisher = 1)

Request Query Parameters    

Parameter NameTypeRequiredDescription
externalIdStringYesID used by external service
ownerIdLongYesResource ID of the creator of the creative

 

Request URL

GET $URI_PREFIX/creatives/find?{externalId}&{ownerId}

Response

Sample JSON Response

{
  "id": 33,
  "externalId": "123456",
  "advertiser": " 247Loans.com",
  "width": 728,
  "height": 90,
  "tag": "<>",
  "url": "http://ourdomain.com",
  "ownerId": 31445,
  "ownerTypeId": 1
}

         

Response Code

TypeDescription
200OK

Response Header

             
Response Header Name
Type
Description
content-typeapplication/jsonMedia type that is to be returned in search/sort operation

 

Error Codes

                       

Status

Error Message

Description

401

Unauthorized

Authentication or Authorization failure. Check the response body for specific details.

403

Forbidden

You are not subscribed to this feature of the Platform.
404Not FoundThe requested resource could not be found.

 

Get AG Creatives Status by Publisher

Overview

This API enables you to get status of AG creatives by publisher.

Note: Creatives cannot be approved or rejected, therefore, the status of creatives will remain as "pending," regardless of actual status. This feature is expected to be updated in future iterations of Automated Guaranteed.

Request           

URIHTTP Method

$URI_PREFIX/creatives/status

GET

Request Headers                              

Header NameTypeValueRequiredDescription
pubTokenString${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

resourceId

Integer 

Yes

Resource ID (Owner ID)

resourceTypeId 

Integer 

Yes

Type of Resource (e.g., Publisher=1)

Request Body Parameters                  

Parameter NameTypeRequiredDescription
publisherIdIntegerYesThe resource ID of the publisher that needs to approve/reject the creative.

creativeId

CreativeYesThe creative ID

Request URL   

GET $URI_PREFIX/creatives/status?{publisherId}&{creativeId}

Response

Sample Response JSON

{
  "id": 13,
  "publisherId": 301,
  "creative": {
    "id": 16,
    "externalId": "creative_3",
    "advertiser": "1",
    "width": 100,
    "height": 100,
    "tag": "tag",
    "url": "http://www.ourdomain.com",
    "ownerId": 301,
    "ownerTypeId": 1
  },
  "creativeStatus": "PENDING"
}

Response

Response Code           

TypeDescription
200OK

 

             
Response Header Name
Type
Description
content-typeapplication/jsonMedia type that is to be returned in search/sort operation

 

Error Codes

                       

Status

Error Message

Description

401

Unauthorized

Authentication or Authorization failure. Check the response body for specific details.

403

Forbidden

You are not subscribed to this feature of the Platform.
404Not FoundThe requested resource could not be found.

 

 

 

Approve or Reject an AG Creative

 

Overview

This API allows you to approve or reject an AG Creative. 

 

Note: Creatives cannot be approved or rejected, therefore, the status of creatives will remain as "pending," regardless of actual status. This feature is expected to be updated in future iterations of Automated Guaranteed.

 

Request           

URIHTTP Method

$URI_PREFIX/creatives/status

PUT

Request Headers                               

Header NameTypeValueRequiredDescription
pubTokenString 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

resourceId

Integer 

Yes

Resource ID (Owner ID)

resourceTypeId 

Integer 

Yes

Type of Resource (e.g., Publisher=1)

Request Body Parameters                                                                                                     

Body ParameterTypeRequiredValidationsDescription
idIntegerYes Generated ID of the publisher that needs to approve/reject the creative
publisherIdIntegerYesValid IDPublisher ID
creativeIdIntegerYesValid IDID of the Creative
externalIdStringYes ID used by external service
nameStringNo Name of Creative
advertiserStringYes Name of Advertiser
widthIntegerYes Width of the Creative
heightIntegerYes Height of the Creative
tagStringYes Tag associated with the Creative
urlStringYes URL of creative
ownerIdIntegerYesValid IDOwner ID (Resource ID) of the creator of the creative
ownerTypeIdIntegerYesValid IDType of Owner (Resource) of the creative
creativeStatusStringYesPENDING, REJECTED, APPROVEDThe status you want to assign to the creative

Request URL    

GET $URI_PREFIX/creatives/status

Sample Request JSON

{
      "id": 24,
      "publisherId": 31445,
      "creative": {
        "id": 35,
        "externalId": "Gio's test Ü€Ê܉_Ü€š \"'@ä‰å/",
        "name": "",
        "advertiser": "Advertiser",
        "width": 728,
        "height": 90,
        "tag": "tag",
        "url": "http://www.google.com",
        "ownerId": 737,
        "ownerTypeId": 5
      },
      "creativeStatus": "APPROVED"
    }

Response

 

Response Code         

TypeDescription
200 Success

Response Header           

Response Header NameType
content-typeapplication/json

Response Messages

                          

StatusReasonDescription
201CreatedThe request has been fulfilled, resulting in the creation of a new resource.
401UnauthorizedAuthentication or Authorization failure. Check the response body for specific details.
403ForbiddenThe request was a valid request, but the server is refusing to respond to it. 403 error semantically means "unauthorized", i.e. the user does not have the necessary permissions for the resource.
404Not FoundThe requested resource could not be found.

Finding All AG Creatives Statuses

Overview

This API allows you to find all AG Creatives in the PubMatic system.

Note: Creatives cannot be approved or rejected, therefore, the status of creatives will remain as "pending," regardless of actual status. This feature is expected to be updated in future iterations of Automated Guaranteed.

Request           

URIHTTP Method

$URI_PREFIX/creatives/status/all

GET

Request Headers                               

Header NameTypeValueRequiredDescription
pubTokenString${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

resourceId

Integer 

Yes

Resource ID (Owner ID)

resourceTypeId 

Integer 

Yes

Type of Resource (e.g., Publisher = 1)

Request Query Parameters                           

ParameterTypeRequiredDescription
pageNumberIntegerNoPage number to be fetches in case of multiple pages. Its default value is 100.

pageSize

IntegerNoMaximum number of rows to be included in the response. Its default value is 1.
filtersArray[string]No

Filters list, filter syntax:[field operation value], valid operations: eq noteq like notlike.
Example: To filter list of all creatives by the status APPROVED:
&filters=creativeStatus eq APPROVED

 See Filter Parameter Details for more information.

Note that multiple Ids can be entered in a filter to retrieve a status for more than one ID.

Request URL    

GET $URI_PREFIX/creatives/status/all?{pageNumber}&{pageSize}

Response

Response Code           

TypeDescription
200Success

Response Header           

Response Header NameType
content-typeapplication/json

Sample Response JSON    

{
  "content": [
    {
      "id": 20,
      "publisherId": 301,
      "creative": {
        "id": 29,
        "externalId": "Advert_101",
        "name": "string",
        "advertiser": "Advert_Company",
        "width": 0,
        "height": 0,
        "tag": "string",
        "url": "string",
        "ownerId": 301,
        "ownerTypeId": 1
      },
      "creativeStatus": "APPROVED"
    },

  ],
  "last": false,
  "totalPages": 11,
  "totalElements": 11
  "sort": [
    {
      "direction": "DESC",
      "property": "id",
      "ignoreCase": false,
      "nullHandling": "NATIVE",
      "ascending": false
    }
  ],
  "numberOfElements": 1,
  "first": true,
  "size": 1,
  "number": 0
}

Response Messages                       

StatusReasonDescription
401UnauthorizedAuthentication or Authorization failure. Check the response body for specific details.
403ForbiddenThe request was a valid request, but the server is refusing to respond to it. 403 error semantically means "unauthorized", i.e. the user does not have the necessary permissions for the resource.
404Not FoundThe requested resource could not be found.

Get AG Creative

Overview

This API allows you to get an AG Creative to be pushed to the ad server with the order and line item. (Regardless of a new order or existing order.)

Request           

URIHTTP Method

$URI_PREFIX/creatives/status/{id}

GET

Request Headers                               

Header NameTypeValueRequiredDescription
pubTokenString 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

resourceId

Integer 

Yes

Resource ID (Owner ID)

resourceTypeId 

Integer 

Yes

Type of Resource (e.g., Publisher=1)

Request Path Parameter                 

Path ParameterTypeValueRequiredDescription
idLong YesGenerated ID of the Creative

Sample Request UR    

GET $URI_PREFIX/creatives/{id}

Response

Sample Response JSON

{
  "id": 34,
  "externalId": "NT creative 123",
  "name": "NT creative 123",
  "advertiser": "Advertiser_Co",
  "width": 728,
  "height": 90,
  "tag": "tag",
  "url": "http://www.ourdomain.com",
  "ownerId": 737,
  "ownerTypeId": 5
}

Response Parameters                                                               

Body Parameter

Type

Description

idIntegerCreative ID
externalIdStringID used by the external service
nameStringName of the creative

advertiser

String

Name of the advertiser

widthIntegerWidth of Creative

height

Integer

Height of Creative

tagStringTag of Creative
urlStringURL of Creative

ownerId

Integer

Resource ID of the creator of the creative

ownerTypeId

String

Resource type ID of the creator of this creative

tag

String

Tag of creative

Response Code

TypeDescription
200Successful

Response Header           

Response Header NameType
content-typeapplication/json

 

Response Messages                       

StatusReasonDescription
401UnauthorizedAuthentication or Authorization failure. Check the response body for specific details.
403ForbiddenThe request was a valid request, but the server is refusing to respond to it. 403 error semantically means "unauthorized", i.e. the user does not have the necessary permissions for the resource.
404Not FoundThe requested resource could not be found

Attachments

    Outcomes