Automated Guaranteed (AG) Offers API

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

Description

An AG offer describes the terms under which a particular product is sold, including pricing, targeting, and the demand partner platform. These APIs allows a user to create and manage AG offers in the PubMatic system.

 

An offer is built off of a product of inventory defined by the publisher and add targeting and deal specific terms. The offer takes the sites, ad units, and ad unit groups from the product and defines the details of what is available to turn the offer into a line item. This two-step process of products and offers allows publishers to easily reuse the same defined sites, ad units, and ad unit groups over and over but to create many different offers with differing prices, targeting, and quantity. This reduces the need to constantly redefine the sites, ad units, and ad units groups on the publisher's sites. 

 

An offer is always linked to a product. Offers are the end unit that is discoverable by buyers since it is what includes the proposed pricing and targeting. The sites and ad units of the product that the offer is built off of are also visible from the end offer. The offer is the ultimate end unit that will be turned into line items when offers are added to an order.  

Methods

                                       
Method Path
HTTP Method Type
Description
Link to Definition
/agoffers
POST
Create a new AG offer in the PubMatic system

Creating an AG Offer

/agoffersGETRetrieve the list of AG offersRetrieving List of AG Offers
/alloffersGETRetrieve the list of all AG and PMP offersRetrieving List of All Offers
/agoffers/{id}GETRetrieve the details of a specific AG offerRetrieving Details of an AG Offer
/agoffers/{id}PUTUpdate the details of a specific AG offerUpdating an AG Offer

 

 

Creating an AG Offer

Overview

This API allows you to create an AG Offer.

Request

         

URI
$URI_PREFIX/agoffers
HTTP Method
POST

Request Headers

                               

Header Name
Type
Value
Required
Description
pubToken
String
${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

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

Request Body Parameters

                                                                                                                                                               

Body Parameter

Type

Required

Description

idIntegerNoOffer ID
optlockIntegerNo

Used in update operation. Number represents version and prevents overriding other edits during update.

Upon creation, optlock value should be null, whereas upon update, the optlock value should be preserved.

name

String

Yes

Name of the offer.
Length check (min limit is 1 character)

description

String

No

Description of the offer

ownerId

Long

Yes

Owner ID

ownerTypeId

Long

Yes

Type of owner

currency

String

Yes

Currency

priceAmount

BigDecimal

Yes

Offer Price

minSpendAmount

BigDecimal

Yes

Minimum spend amount

publicRateCardAmount

BigDecimal

YesPublish Rate Card amount

costType

String

No

Cost type 
Example, "CPD","CPC","CPM"

status

String

No

Indicates status of offer.
Example, "ACTIVE","INACTIVE"

deleted

Boolean

No

Flag to indicate offer is deleted or not

productId

Long

Yes

Product ID

maxDailyImpressions

Long

No

Maximum daily impressions

userGeneratedContent

Boolean

No

Indicates whether page allows user generated content

creativeTypes

JSON array of creative types.

No

Creative types

notes

String

No

Notes

offerVisibilityMapping

JSON Object Array

Yes

Contains Mapping of Demand Partner and Buyer to which Newly Created offer will be visible.Special Case id:"0" means "ALL"

viewStartDate

String

No

This offer to visible from particular Start Date (must be greater than today)

viewEndDate

String

No

This offer to visible till particular End Date (must be greater than today and viewStartDate)

runStartDate

String

No

Offer can be translated to Line Item within same range (must be greater than today and viewStartDate)

runEndDate

String

No

Offer can be translated to Line Item within same range (must be greater than today and runStartDate)

tags

String

No

Searchable Tags for Offer

logoPath

String

No

URL of Logo associated with Offer

Sample Request URL

GET $URI_PREFIX/agoffers/

Sample Request JSON

    

{
      "associateId": null,
      "associateTypeId": null,
      "costType": "CPM",
      "creativeTypes": [
        "JPG",
        "GIF",
        "SWF"
      ],
      "currency": "USD",
      "description": "Offer.",
      "logoPath": "http://apps.pubmatic.com/AdGainMgmt/publisher/images/323455.png",
      "maxDailyImpressions": 1000,
      "minSpendAmount": 5,
       "name": "Mothers Day Offer",
      "notes": null,
      "offerVisibilityMapping": [
        {
          "demandPartner": {
            "id": 737,
            "name": "AdvertName",
            "uri": "http://localhost:7070/common/advertisingEntity/737"
          },
          "buyers": [
            {
              "id": 0,
              "name": null,
              "uri": null,
              "dspBuyerId": null
            }
          ]
        }
      ],
      "ownerId": 31445,
      "ownerTypeId": 1,
      "priceAmount": 5,    
      "productId": 15430,
      "publicRateCardAmount": 5,
      "publisherEmail": "",
      "runEndDate": "2016-06-28",
      "runStartDate": "2016-06-25",
      "status": "ACTIVE",
      "tags": "",
      "targeting": "",
      "url": "ourdomain.com",
      "userGeneratedContent": false,
      "viewEndDate": "2016-06-29",
      "viewStartDate": "2016-06-24"
    }

Response

         

Type
Description
AG Offer Object.
JSON response of newly created offer.

AG Offer 

                                                                                                                                    

Body Parameters
Type
Description
id
Integer
Offer ID
optlock
Integer
Used in update operation. Number represents version and prevents overriding other edits during update. 
Optlock value should be null upon creation (upon update, the optlock value should be preserved.)
name
String
Offer name
description
String
Offer description
ownerId
Integer
Owner ID
ownerTypeId
Integer
Owner type ID
associateId
Integer
Future Use
associateTypeId
Integer
Future Use
costType
String
Example, CPD,CPC,CPM
status
String
Example, ACTIVE, INACTIVE
productId
Integer
Product ID
maxDailyImpressions
Integer
Maximum daily impressions
url
String
URL of page related to the offer.
userGeneratedContent
Boolean
Indicates whether page allows user generated content
creativeTypes
Set of CreativeTypes
Creative types
(e.g., GIF, SWF, JPG)
creationTime
String
Offer creation time
modificationTime
String
Offer modification time
notes
String
Notes
offerVisibilityMapping
JSON Object Array
Contains Mapping of Demand Partner and Buyer to which Newly Created offer will be visible. Special Case id:"0" means "ALL"
viewStartDate
String
This offer to visible from particular Start Date
viewEndDate
String
This offer to visible till particular End Date
runStartDate
String
Offer can be translated to Line Item within same range
runEndDate
String
Offer can be translated to Line Item within same range
tags
String
Searchable Tags for Offer
logoPath
String
URL to mention Logo associated with Offer

 

Offer Visibility Mapping

                

Body Parameters
Type
Description
demandPartner
Object
Details about Demand Partner
buyers
Array of Objects
Buyer Objects Associated with given Demand Partner.

 

Product   

                             

Body Parameters
Type
Description
id
Integer
Product ID
name
String
Product Name
description
String
Product description
deleted
Boolean
Flag to indicate whether Product is deleted or not.
adSizes
JSON array of AdSize objects
Ad Sizes associated with product
adServerInventoryUnits
JSON array of AdServerInventoryUnit objects
Ad Server Inventory Units associated with Product.

 

AdServerInventoryUnit

                                    

Body Parameters
Type
Description
id
Integer
Ad Server Inventory Unit ID
name
String
Ad Server Inventory Unit name
uri
String
URL to get more details of specific Ad Server Inventory Unit.
adserverConfId
Integer
Ad Server Configuration ID
iuType
Integer
Inventory Unit type
externalId
String
ID to refer this Ad Server Inventory Unit at particular Ad Server

 

Ad Size

                               

Body Parameters

Type

Description

id

Integer

AdSize ID

name

String

AdSize name

width

Integer

AdSize width

height

Integer

AdSize height

uri

String

URL to get more details of AdSize.

 

Sample Response JSON

    


{
  "associateId": null,
  "associateTypeId": null,
  "costType": "CPM",
  "creationTime": "2016-06-21T17:37:18.976Z",
  "creativeTypes": [
    "JPG",
    "GIF",
    "SWF"
  ],
  "currency": "USD",
  "description": "Offer.",
  "id": 43,
  "logoPath": "http://apps.pubmatic.com/AdGainMgmt/publisher/images/31445.png?cachebuster=0.9516202261023887",
  "maxDailyImpressions": 1000,
  "minSpendAmount": 5,
  "modificationTime": "2016-06-21T17:37:18.976Z",
  "name": "Mothers Day Offer",
  "notes": null,
  "offerVisibilityMapping": [
    {
      "demandPartner": {
        "id": 737,
        "name": "AdCompany",
        "uri": "http://localhost:1234/common/advertisingEntity/737"
      },
      "buyers": [
        {
          "id": 0,
          "name": null,
          "uri": null,
          "dspBuyerId": null
        }
      ]
    }
  ],
  "optlock": 0,
  "ownerId": 31445,
  "ownerTypeId": 1,
  "priceAmount": 5,
  "product": {
    "id": 15430,
    "name": "RichMedia",
    "description": "RichMedia Product.",
    "deleted": false,
    "adSizes": [
      {
        "id": 65,
        "name": "Leaderboard",
        "width": 990,
        "height": 100,
        "uri": "http://localhost:7070/common/adSize/65"
      },
      {
        "id": 7,
        "name": "Leaderboard-728X90",
        "width": 728,
        "height": 90,
        "uri": "http://localhost:7070/common/adSize/7"
      },
      {
        "id": 66,
        "name": "Double Leaderboard",
        "width": 990,
        "height": 210,
        "uri": "http://localhost:7070/common/adSize/66"
      },
      {
        "id": 111,
        "name": "Super Leaderboard",
        "width": 980,
        "height": 150,
        "uri": "http://localhost:7070/common/adSize/111"
      }
    ],
    "adServerInventoryUnits": [
      {
        "id": 2813,
        "name": "test_",
        "uri": "http://localhost:7070/inventory/adserverinventory/2813",
        "adserverConfId": 1,
        "iuType": 1,
        "externalId": "123848325"
      }
    ]
  },
  "productId": 15430,
  "publicRateCardAmount": 5,
  "publisherEmail": "",
  "runEndDate": "2016-06-28",
  "runStartDate": "2016-06-25",
  "status": "ACTIVE",
  "tags": "",
  "targeting": "",
  "url": "ourdomain.com",
  "userGeneratedContent": false,
  "viewEndDate": "2016-06-29",
  "viewStartDate": "2016-06-24"
}

Response Headers

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

400

Bad Request

There is some validation failure; check the response body for error details.

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.

 

 

Retrieving List of AG Offers

Overview

This API enables you to retrieve a list of AG Offers from PubMatic.

Request

         
URI$URI_PREFIX/agoffers
HTTP MethodGET

Request Headers

                                   
Header Name
Type
Value
Required
Validations
Description
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

resourcedIdLong Yes Resource ID (Owner ID)
resourceTypeIdLong Yes Type of Resource (e.g., Publisher = 1)

Request Query Parameters

                                             
Parameter Name
Type
Required
Validations
Description
ownerIdIntegerYes Owner Id to whom offers belongs.
ownerTypeIdIntegerYes 

Type of owner.

E.g., For Publisher Owner,  ownerTypeId=1

pageSizeIntegerNo Maximum number of records to be included in the response. Default value = 100.
pageNumberIntegerNo The page number the response should begin (in the case of multiple pages). Default value is 1.
filtersArray of stringNo Filters list, filter syntax:[field operation value], valid operations: eq noteq like notlike. See Filter Parameter Details for more information.

Sample Request URL:

GET $URI_PREFIX/agoffers/?ownerId=12345&ownerTypeId=1&pageNumber=1&pageSize=100&filters=-modificationTime*

Response

Response Body

                  
Body Parameter
Type
Description
metaDataJSON Object This contains the meta data about the response generated.
itemsJSON Array of Offer objectThis gives the records formed as per your request.

AG Offer

                                                                                                                                          
Body Parameters
Type
Description
idIntegerOffer id
optlockInteger

Used in update operation. Number represents version and prevents overriding other edits during update.

Upon creation, optlock value should be null, whereas upon update, the optlock value should be preserved.

nameStringOffer name
descriptionStringOffer description
ownerIdIntegerResource ID
ownerTypeIdInteger

Resource Type ID

associateIdIntegerFuture Use
associateTypeIdIntegerFuture Use
tagsStringSearchable tags for the Offer
costTypeStringe.g : CPD, CPC, CPM, CPA
statusStringe.g : ACTIVE, INACTIVE
productIdIntegerProduct Id
productProduct ObjectProduct details
maxDailyImpressionsIntegerMaximum daily impressions
urlStringURL of web page included in the Offer
logoPathStringURL to of logo associated with the Offer
userGeneratedContentBooleanIndicates whether the site page potentially contains user generated content (e.g., comments, ratings, etc.)
creativeTypesSet of Creative TypesType of Creative(s) associated with the Offer (through Product association)
creationTimeStringOffer creation time
modificationTimeStringOffer modification time
notesStringPublisher Notes
viewStartDateStringThis offer to visible from particular Start Date
viewEndDateStringThis offer to visible till particular End Date
runStartDateStringOffer can be translated to Line Item within same range
runEndDateStringOffer can be translated to Line Item within same range
offerVisibilityMappingJSON Object ArrayContains Mapping of Demand Partner and Buyer to which Newly Created offer will be visible. Special Case id:"0" means "ALL"

Product

                                      
Body Parameters
Type
Description
idIntegerProduct Id
nameStringProduct Name
descriptionStringProduct description
deletedBooleanFlag to indicate whether Product is deleted or not.
adSizesJSON array of AdSize objectsAd Sizes associated with product
adServerInventoryUnitsJSON array of AdServerInventoryUnit objectsAd Server Inventory Units associated with Product.

Offer Visibility Mapping

                  
Body Parameters
Type
Description
demandPartnerObjectDetails about Demand Partner
buyersArray of ObjectsBuyer Objects Associated with given Demand Partner.

Demand Partner

                       
Body Parameters
Type
Description
idIntegerDemand Partner ID
nameStringName of Demand Partner
uriStringURL to get more information about the Demand Partner

Buyer

                            
Body Parameters
Type
Description
idIntegerBuyer ID
nameStringName of Buyer
uriStringURL to get more information about the Buyer
dspBuyerIdIntegerDemand Partner ID 

Ad Server Inventory Unit

                                      
Body Parameters
Type
Description
idIntegerAd Server Inventory Unit Id
nameStringAd Server Inventory Unit name
uriStringURL to get more details of specific AdServerInventory Unit.
adserverConfIdInteger 
iuTypeIntegerInventoryUnit type
externalIdStringID to refer this Ad Server Inventory Unit at particular Ad Server

Ad Size

                                 
Body Parameters
Type
Description
idIntegerAdSize Id
nameStringAdSize name
widthIntegerAdSize width
heightIntegerAdSize height
uriStringURL to get more details of AdSize.

 

Sample Response JSON:

    
{
    "items": [
        {
            "associateId": null,
            "associateTypeId": null,
            "costType": "CPM",
            "creationTime": "2015-08-23T11:00:05.550Z",
            "creativeTypes": [
                "GIF",
                "JPG",
                "SWF"
            ],
            "currency": "USD",
            "description": "Sample12121",
            "geos": [
                {
                    "id": 107
                }
            ],
            "id": 220,
            "logoPath": null,
            "maxDailyImpressions": 1111111,
            "minSpendAmount": 11.11,
            "modificationTime": "2015-08-23T11:00:05.755Z",
            "name": "Sample12126",
            "notes": null,
            "offerVisibilityMapping": [
                {
                    "buyers": [
                        {
                            "dspBuyerId": null,
                            "id": 0,
                            "name": null,
                            "uri": null
                        }
                    ],
                    "demandPartner": {
                        "id": 648,
                        "name": "Kantar",
                        "uri": "http://54.164.157.178:7070/common/advertisingEntity/648"
                    }
                }
            ],
            "optlock": 1,
            "ownerId": 31445,
            "ownerTypeId": 1,
            "priceAmount": 11.11,
            "product": {
                "adServerInventoryUnits": [
                    {
                        "adserverConfId": 1,
                        "externalId": "90067245",
                        "id": 400,
                        "iuType": 1,
                        "name": "AMG-735-Adunit-Dinesh1",
                        "uri": "http://54.164.157.178:7070/inventory/adserverinventory/400"
                    }
                ],
                "adSizes": [
                    {
                        "height": 600,
                        "id": 10,
                        "name": "Wide Skyscraper",
                        "uri": "http://54.164.157.178:7070/common/adSize/10",
                        "width": 160
                    }
                ],
                "deleted": false,
                "description": "Sample12121",
                "id": 1411,
                "name": "Sample12121"
            },
            "productId": 1411,
            "publicRateCardAmount": 1.11,
            "runEndDate": "2015-11-15",
            "runStartDate": "2015-11-10",
            "status": "ACTIVE",
            "tags": "test1",
            "url": "www.pubmatic.com",
            "userGeneratedContent": false,
            "viewEndDate": "2015-10-15",
            "viewStartDate": "2015-10-10"
        }
    ],
    "metaData": {
        "endIndex": 1,
        "startIndex": 1,
        "totalRecords": 44
    }
}

Response Headers

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

400

Bad Request

There is some validation failure; check the response body for error details.

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.

Retrieving List of All Offers

Overview

This API allows you to retrieve a list of all AG and PMP offers from PubMatic.

Request

         

URI
$URI_PREFIX/alloffers
HTTP Method
GET

 

Request Headers

                               

Header Name
Type
Value
Required
Description
pubToken
String
${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

resourceIDLong YesResource ID (Owner ID)
resourseTypeIDLong YesType of Resource (e.g., Publisher = 1)

Request Query Parameters

                                       

Parameter Name
Type
Required
Description
ownerId
Integer
Yes
Owner ID to whom offers belongs.
ownerTypeId
Integer
Yes
Type of owner.
E.g., Publisher Type Owner. ownerTypeId=1
pageSize
Integer
No
Maximum number of records to be included in the response. Default value = 100.
pageNumber
Integer
No
The page number the response should begin (in the case of multiple pages). Default value is 1.
filters
Array of string
No
Filters list, filter syntax:[field operation value], valid operations: eq noteq like notlike. See Filter Parameter Details for more information.

Sample Request URL

GET $URI_PREFIX/alloffers/?ownerId=12345&ownerTypeId=1&pageNumber=1&pageSize=100&filters=-modificationTime*

Response

Response Headers

                  

Response Header Name
Type
Description
Status Code
200
OK
Content-Type
application/json
Mediatype that is to be returned in search/sort operation

Response Body

                  

Response Body Parameter
Type
Description
metaData
JSON Object 
This contains the meta data about the response generated.
items
JSON Array of OfferSummary object
This gives the records formed as per your request.

Offer

                                                                         

Body Parameters
Type
Description
id
Integer
Offer ID
name
String
Offer Name
productName
String
Product Name
description
String
Description of offer
price
Number
Offer price
currencyNumberCurrency Type (e.g., USD, GBP, EUR)
startDate
String
Offer start date
endDate
String
Offer end date
type
String
Offer Type
(PMP or AG)
creationTime
String
Creation time of offer
modificationTime
String
Modification time of offer
tagsStringSearch tags
logoPathURLURL of logo associated with this offer

 

Sample Response JSON


{
    "items": [
        {
      "id": 37,
      "name": "Father's Day-Male 25-49-ROS",
      "productName": "RichMediaProduct",
      "description": "Fathers Day package",
      "price": 4.5,
      "currency": "USD",
      "startDate": "2016-06-09",
      "endDate": "2016-06-29",
      "type": "AG",
      "creationTime": "2016-06-09T14:54:33Z",
      "modificationTime": "2016-06-09T19:03:11Z",
      "tags": "",
      "logoPath": "http://apps.pubmatic.com/AdGainMgmt/publisher/images/31445.png?cachebuster=0.4105078715426831"
    }
    ],
    "metaData": {
        "endIndex": 10,
        "startIndex": 1,
        "totalRecords": 1908
    }
}

Response Headers

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

400

Bad Request

There is some validation failure; check the response body for error details.

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.
 

 

 

Retrieving Details of an AG Offer

Overview

This API allows you to retrieve the details of specific AG Offer from PubMatic.

Request

         

URI

$URI_PREFIX/agoffers/{id}

HTTP Method

GET

Request Headers

                               

Header Name

Type

Value

Required

Description

pubToken

String

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

resourceIdLong YesResource ID (Owner ID)
resourceTypeIdLong YesType of Resource (e.g., Publisher = 1)

Path Parameters

                 

Parameter Name

Type

Required

Description

Sample Data

 id

Long 

Yes 

AG Offer ID for which details need to be extracted 

123 

Sample Request URL

GET $URI_PREFIX/agoffers/123?ownerId=12345&ownerTypeId=1

Response

Response Body

         

Type

Description

AG Offer Object

Details of AG Offer Object in JSON format.

AG Offer

                                                                                                                                                  

Body Parameters
Type
Description
idIntegerOffer id
optlockInteger

Used in update operation. Number represents version and prevents overriding other edits during update. 

Upon creation, optlock value should be null, whereas upon update, the optlock value should be preserved.

nameStringOffer name
descriptionStringOffer description
ownerIdIntegerOwner Id
ownerTypeIdInteger

Owner type id

associateIdIntegerFuture Use
associateTypeIdIntegerFuture Use
tagsStringSearchable tags for the Offer
costTypeStringe.g : CPD,CPC,CPM
statusStringe.g : ACTIVE, INACTIVE
productIdIntegerProduct Id
productProduct ObjectProduct details
maxDailyImpressionsIntegerMaximum daily impressions
urlStringURL of web page included in the Offer
logoPathStringURL to of logo associated with the Offer
userGeneratedContentBooleanIndicates whether the site page potentially contains user generated content (e.g., comments, ratings, etc.)
creativeTypesSet of Creative TypesType of Creative(s) associated with the Offer (through Product association)
creationTimeStringOffer creation time
modificationTimeStringOffer modification time
viewStartDateStringThis offer to visible from particular Start Date
viewEndDateStringThis offer to visible till particular End Date
runStartDateStringOffer can be translated to Line Item within same range
runEndDateStringOffer can be translated to Line Item within same range
notesStringNotes
targetingStringSpecific targeting associated with this Offer
pulbisherEmailStringEmail of publisher 
offerVisibilityMappingJSON Object ArrayContains Mapping of Demand Partner and Buyer to which Newly Created offer will be visible.

Product

                                    

Body Parameters
Type
Description
idIntegerProduct Id
nameStringProduct Name
descriptionStringProduct description
deletedBooleanFlag to indicate whether Product is deleted or not.
adSizesJSON array of Ad Size objectsAd Sizes associated with product
adServerInventoryUnitsJSON array of Ad Server Inventory Unit objectsAd Server Inventory Units associated with Product.

Offer Visibility Mapping

                

Body Parameters
Type
Description
demandPartnerObjectDetails about Demand Partner
buyersArray of ObjectsBuyer Objects Associated with given Demand Partner.

AdSize

                               

Body Parameters
Type
Description
idIntegerAdSize Id
nameStringAdSize name
widthIntegerAdSize width
heightIntegerAdSize height
uriStringURL to get more details of AdSize.

Ad Server Inventory Unit

                                    

Body Parameters
Type
Description
idIntegerAd Server Inventory Unit Id
nameStringAd Server Inventory Unit name
uriStringURL to get more details of specific Ad Server Inventory Unit
adserverConfIdIntegerAd Server Configuration ID
iuTypeIntegerInventory Unit type
externalIdStringId to refer this Ad Server Inventory Unit at particular Ad Server

 

Sample Response JSON:

    

{
  "associateId": null,
  "associateTypeId": null,
  "costType": "CPM",
  "creationTime": "2016-06-09T14:54:33Z",
  "creativeTypes": [
    "JPG",
    "GIF",
    "SWF"
  ],
  "currency": "USD",
  "description": "Sample Inventory package",
  "id": 37,
  "logoPath": "http://apps.domain.con/publisher/images/31445.png?cachebuster=0.4105078715426831",
  "maxDailyImpressions": null,
  "minSpendAmount": 4500,
  "modificationTime": "2016-06-09T19:03:11Z",
  "name": "Father's Day - Sample -ROS",
  "notes": null,
  "offerVisibilityMapping": [
    {
      "demandPartner": {
        "id": 753,
        "name": "Sample Name",
        "uri": "http://localhost:1234/common/sampledsp/753"
      },
      "buyers": [
        {
          "id": 6587,
          "name": "Sample_Buyer1",
          "uri": "http://localhost:1234/common/samplebuyer/6587",
          "dspBuyerId": 20
        },
        {
          "id": 6520,
          "name": "Sample_Buyer3",
          "uri": "http://localhost:1234/common/samplebuyer/6587",
          "dspBuyerId": 19
        }
      ]
    }
  ],
  "optlock": 3,
  "ownerId": 12345,
  "ownerTypeId": 1,
  "priceAmount": 4.5,
  "product": {
    "id": 15648,
    "name": "RichMediaProduct",
    "description": "",
    "deleted": false,
    "adSizes": [
      {
        "id": 65,
        "name": "Leaderboard",
        "width": 990,
        "height": 100,
        "uri": "http://localhost:1234/common/adSize/65"
      },
      {
        "id": 17,
        "name": "Leaderboard-728X90",
        "width": 728,
        "height": 90,
        "uri": "http://localhost:1234/common/adSize/7"
      },
      {
        "id": 11,
        "name": "Super Leaderboard",
        "width": 980,
        "height": 150,
        "uri": "http://localhost:1234/common/adSize/111"
      }
    ],
    "adServerInventoryUnits": [
      {
        "id": 99,
        "name": "RichMediaAdunit",
        "uri": "http://localhost:1234/inventory/adserverinventory/99",
        "adserverConfId": 1,
        "iuType": 1,
        "externalId": "9305930"
      }
    ]
  },
  "productId": 150072,
  "publicRateCardAmount": 6,
  "publisherEmail": "",
  "runEndDate": "2016-06-29",
  "runStartDate": "2016-06-09",
  "status": "ACTIVE",
  "tags": "",
  "targeting": "(country = (2840)) & (browser = (500011)) & (bandwidth = (9))",
  "url": "www.sampledomain.com",
  "userGeneratedContent": false,
  "viewEndDate": "2016-06-09",
  "viewStartDate": "2016-06-09"
}

Response Headers

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

400

Bad Request

There is some validation failure; check the response body for error details.

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.
 

 

 

Updating an AG Offer

Overview

This API allows you to update an existing AG Offer in PubMatic.

Request

         
URI$URI_PREFIX/agoffers/{id}
HTTP MethodPUT

Sample Request URL

GET $URI_PREFIX/agoffers/{id}

 

Request Headers

                                   
Header Name
Type
 
Required
Validations
Description
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

resourceIdInteger Yes Resource ID (Owner ID)
resourceTypeIdInteger Yes Resource Type ID (e.g., Publisher = 1)

Path Parameters

                 
Parameter Name
Type
Required
Description
Sample Data
idLongYesOffer Id that need to be updated98

Request Body Parameters

                                                                                                                                                               

Body Parameter

Type

Required

Description

idIntegerNoOffer ID
optlockIntegerNo

Used in update operation. Number represents version and prevents overriding other edits during update. 

Upon creation, optlock value should be null, whereas upon update, the optlock value should be preserved.

name

String

Yes

Name of the offer.
Length check (min limit is 1 character)

description

String

No

Description of the offer

ownerId

Long

Yes

Owner ID

ownerTypeId

Long

Yes

Type of owner

currency

String

Yes

Currency

priceAmount

BigDecimal

Yes

Offer Price

minSpendAmount

BigDecimal

Yes

Minimum spend amount

publicRateCardAmount

BigDecimal

YesPublish Rate Card amount

costType

String

No

Cost type 
Example, "CPD","CPC","CPM"

status

String

No

Indicates status of offer.
Example, "ACTIVE","INACTIVE"

deleted

Boolean

No

Flag to indicate offer is deleted or not

productId

Long

Yes

Product ID

maxDailyImpressions

Long

No

Maximum daily impressions

userGeneratedContent

Boolean

No

Indicates whether page allows user generated content

creativeTypes

JSON array of creative types.

No

Creative types

notes

String

No

Notes

offerVisibilityMapping

JSON Object Array

Yes

Contains Mapping of Demand Partner and Buyer to which Newly Created offer will be visible

viewStartDate

String

No

This offer to visible from particular Start Date (must be greater than today)

viewEndDate

String

No

This offer to visible till particular End Date (must be greater than today and viewStartDate)

runStartDate

String

No

Offer can be translated to LineItem within same range (must be greater than today and viewStartDate)

runEndDate

String

No

Offer can be translated to LineItem within same range (must be greater than today and runStartDate)

tags

String

No

Searchable Tags for Offer

logoPath

String

No

URL of Logo associated with Offer

Sample Request URL

GET $URI_PREFIX/agoffers/{id}/

Sample Request JSON

   
{
      "associateId": null,
      "associateTypeId": null,
      "costType": "CPM",
      "creativeTypes": [
        "JPG",
        "GIF",
        "SWF"
      ],
      "currency": "USD",
      "description": "Offer.",
      "logoPath": "http://apps.pubmatic.com/AdGainMgmt/publisher/images/323455.png",
      "maxDailyImpressions": 1000,
      "minSpendAmount": 5,
       "name": "Mothers Day Offer",
      "notes": null,
      "offerVisibilityMapping": [
        {
          "demandPartner": {
            "id": 737,
            "name": "AdvertName",
            "uri": "http://localhost:7070/common/advertisingEntity/737"
          },
          "buyers": [
            {
              "id": 0,
              "name": null,
              "uri": null,
              "dspBuyerId": null
            }
          ]
        }
      ],
      "ownerId": 31445,
      "ownerTypeId": 1,
      "priceAmount": 5,    
      "productId": 15430,
      "publicRateCardAmount": 5,
      "publisherEmail": "",
      "runEndDate": "2016-06-28",
      "runStartDate": "2016-06-25",
      "status": "ACTIVE",
      "tags": "",
      "targeting": "",
      "url": "ourdomain.com",
      "userGeneratedContent": false,
      "viewEndDate": "2016-06-29",
      "viewStartDate": "2016-06-24"
    }

Response

         

TypeDescription
AG Offer Object.JSON response of updated offer.

AG Offer

                                                                                                                                     

Body ParametersTypeDescription
idIntegerOffer ID
optlockIntegerUsed in update operation. Number represents version and prevents overriding other edits during update.
nameStringOffer name
descriptionStringOffer description
ownerIdIntegerOwner ID
ownerTypeIdIntegerOwner type ID
associateIdIntegerFuture Use
associateTypeIdIntegerFuture Use
costTypeStringExample, CPD,CPC,CPM
statusStringExample, ACTIVE, INACTIVE
productIdIntegerProduct ID
maxDailyImpressionsIntegerMaximum daily impressions
urlStringURL of page related to the offer.
userGeneratedContentBooleanIndicates whether page allows user generated content
creativeTypesSet of CreativeTypeCreative types
(e.g., GIF, SWF, JPG)
creationTimeStringOffer creation time
modificationTimeStringOffer modification time
notesStringNotes
offerVisibilityMappingJSON Object ArrayContains Mapping of Demand Partner and Buyer to which Newly Created offer will be visible. Special Case id:"0" means "ALL"
viewStartDateStringThis offer to visible from particular Start Date
viewEndDateStringThis offer to visible till particular End Date
runStartDateStringOffer can be translated to Line Item within same range
runEndDateStringOffer can be translated to Line Item within same range
tagsStringSearchable Tags for Offer
logoPathStringURL to mention Logo associated with Offer

Offer Visibility Mapping

                

Body ParametersTypeDescription
demandPartnerObjectDetails about Demand Partner
buyersArray of ObjectsBuyer Objects Associated with given Demand Partner.

Product

                                    

Body ParametersTypeDescription
idIntegerProduct ID
nameStringProduct Name
descriptionStringProduct description
deletedBooleanFlag to indicate whether Product is deleted or not.
adSizesJSON array of Ad Size objectsAd Sizes associated with product
adServerInventoryUnitsJSON array of Ad Server Inventory Unit objectsAd Server Inventory Units associated with Product.

Ad Server Inventory Unit

                                    

Body ParametersTypeDescription
idIntegerAd Server Inventory Unit ID
nameStringAd Server Inventory Unit name
uriStringURL to get more details of specific Ad Server Inventory Unit.
adserverConfIdIntegerAd Server Configuration ID
iuTypeIntegerInventory Unit type
externalIdStringID to refer this Ad Server Inventory Unit at particular Ad Server

Ad Size

                               

Body Parameters

Type

Description

id

Integer

Ad Size ID

name

String

Ad Size name

width

Integer

Ad Size width

height

Integer

Ad Size height

uri

String

URL to get more details of Ad Size

 

Sample Response JSON    


{
  "associateId": null,
  "associateTypeId": null,
  "costType": "CPM",
  "creationTime": "2016-06-21T17:37:18.976Z",
  "creativeTypes": [
    "JPG",
    "GIF",
    "SWF"
  ],
  "currency": "USD",
  "description": "Offer.",
  "id": 43,
  "logoPath": "http://apps.pubmatic.com/AdGainMgmt/publisher/images/31445.png?cachebuster=0.9516202261023887",
  "maxDailyImpressions": 1000,
  "minSpendAmount": 5,
  "modificationTime": "2016-06-21T17:37:18.976Z",
  "name": "Mothers Day Offer",
  "notes": null,
  "offerVisibilityMapping": [
    {
      "demandPartner": {
        "id": 737,
        "name": "AdCompany",
        "uri": "http://localhost:1234/common/advertisingEntity/737"
      },
      "buyers": [
        {
          "id": 0,
          "name": null,
          "uri": null,
          "dspBuyerId": null
        }
      ]
    }
  ],
  "optlock": 0,
  "ownerId": 31445,
  "ownerTypeId": 1,
  "priceAmount": 5,
  "product": {
    "id": 15430,
    "name": "RichMedia",
    "description": "RichMedia Product.",
    "deleted": false,
    "adSizes": [
      {
        "id": 65,
        "name": "Leaderboard",
        "width": 990,
        "height": 100,
        "uri": "http://localhost:7070/common/adSize/65"
      },
      {
        "id": 7,
        "name": "Leaderboard-728X90",
        "width": 728,
        "height": 90,
        "uri": "http://localhost:7070/common/adSize/7"
      },
      {
        "id": 66,
        "name": "Double Leaderboard",
        "width": 990,
        "height": 210,
        "uri": "http://localhost:7070/common/adSize/66"
      },
      {
        "id": 111,
        "name": "Super Leaderboard",
        "width": 980,
        "height": 150,
        "uri": "http://localhost:7070/common/adSize/111"
      }
    ],
    "adServerInventoryUnits": [
      {
        "id": 2813,
        "name": "test_",
        "uri": "http://localhost:7070/inventory/adserverinventory/2813",
        "adserverConfId": 1,
        "iuType": 1,
        "externalId": "123848325"
      }
    ]
  },
  "productId": 15430,
  "publicRateCardAmount": 5,
  "publisherEmail": "",
  "runEndDate": "2016-06-28",
  "runStartDate": "2016-06-25",
  "status": "ACTIVE",
  "tags": "",
  "targeting": "",
  "url": "ourdomain.com",
  "userGeneratedContent": false,
  "viewEndDate": "2016-06-29",
  "viewStartDate": "2016-06-24"
}

Response Headers

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

400

Bad Request

There is some validation failure; check the response body for error details.

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.

Attachments

    Outcomes