Product APIs (For Publishers & Demand Partners)

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

A product defines a publisher's ad inventory. It is a combination of one or more ad tags or sites that you can monetize as an inventory package. A product can also be defined as mappings to entities in the publisher's ad server. 

 

The Product APIs are part of Inventory APIs. To learn more about Inventory APIs, refer to Inventory Overview 

 

Products, which are created by publishers, can be used to create PMP/PMP Preferred/PMP-G Offers and Deals and can be the basis from which an AG Order is eventually created. 

Methods

                                   

 

Retrieving a List of Products (for Demand Partners)

Method Path
HTTP Method Type
Description
Link to Definition
/products
POST
Create a new product in the PubMatic systemCreating a Product
/products/{id}GETRetrieve the details of a specific productRetrieving Details of a Product
/productsGETRetrieve the list of products

Retrieving a List of Products (for Publishers)

 

Retrieving a List of Products (for Demand Partners)

/products/{id}PUTUpdate the details of a specific productUpdating a Product
/products/{id}DELETEDelete a ProductDeleting a Product

Creating a Product

Overview

This API allows you to create a product in the PubMatic system.

Request

         

URI

$URI_PREFIX/products

For sandbox testing, $URI_PREFIX should be replaced with "http://api-sandbox.pubmatic.com/v1/inventory". 

For production, $URI_PREFIX should be replaced with "http://api.pubmatic.com/v1/inventory/".

                                        
HTTP MethodPOST

Request Headers

               

Header Name
Type
Value
Required
Description
Authorization
String
Bearer ${access_token}
Yes
The access token generated for authentication should be sent in 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
name
String
Yes
  • Maximum length is 250 characters
  • Name should be unique for your account
  • Unsupported characters are |!{}[]^"~*?:;+\
Name of the product
description
String
No
  • Maximum length is 512 characters
  • Unsupported characters are |!{}[]^"~*?:;+\
Description of the product
productCategory
(For non IAB users)
JSON array of integer
Yes

Value should already exist in the system

Verticals to be associated with the product.
 
 
OR
 
IAB categories. Example: Automotive

productIABCategory

(For IAB users)

JSON array of stringYesValue should already exist in the system
IAB categories. Example: Automotive
adSizes
JSON array of integer
No
Value should already exist in the system
Ad sizes to be associated with the product.
adFoldPlacements
JSON array of integer
No
Value should already exist in the system
Ad fold placements to be associated with the product.
Example:
Above the Fold, Partially Above the Fold.
adCodeTypes
JSON array of integer
No
Value should already exist in the system
Types of ad tags to be associated with the product.
Example:
Video, IFrame, JS, Mobile Ad Tag.
siteGroups
JSON array of integers
No
Value should already exist in the system
Site groups to be included in the product (siteGroups.includes) and/or excluded from the product (siteGroups.excludes).
publishers
JSON array of integer
 
Value should already exist in the system
Publisher associated with the product
sites
JSON array of integer
At least 1 site or ad tag should be specified
Value should already exist in the system
Sites to be associated with the product
adTags
JSON array of integer
At least 1 site or ad tag should be specified
Value should already exist in the system
Ad tags to be associated with the product
sections
JSON array of integer
No
Value should already exist in the system
Sections to be associated with the product
siteName
String
No
  • Comma-separated list of strings
  • Maximum length is 255 characters
 
 
tags
String
No
  • Comma-separated list of strings
  • Maximum length is 255 characters
  • Characters allowed are alphabets, digits, space
Keywords/tags used to search the product.
platforms
JSON array of integer
No
Value should already exist in the system
Platforms to be associated with the product.
Example:
Web, Mobile Web.
companionAds
boolean
No
Value should be either true or false
Indicates whether support for companion ads is required.
This field is a filter parameter for video ad tags.
vastVersions
JSON array of integer
No
Value should already exist in the system
VAST version associated with product. Possible options are:
  • 2 - VAST 2.0
  • 3 - VAST 3.0
This field is a filter parameter for video ad tags.
minAdDuration
Integer
No
  • Value should be >=0
  • Maximum ad duration should be greater than or equal to the minimum ad duration, if both values are provided
Minimum duration required for video ad.
This field is a filter parameter for video ad tags.
maxAdDuration
Integer
No
  • Value should be >=0
  • Maximum ad duration should be greater than or equal to the minimum ad duration, if both values are provided
Maximum duration required for video ad.
This field is a filter parameter for video ad tags.
vpaidComplianceVersions
JSON array of integer
No
Value should already exist in the system
VPAID compliance version to be associated with the product. Possible options are:
  • 0 - NO_VPAID
  • 1 - VPAID 1.0
  • 2 - VPAID 2.0
This field is a filter parameter for video ad tags.
adServerInventoryUnitsJSON Array of IntegerNoMust be a valid adServerInventory ad unitAdUnit or Placement for a given Publisher AdServer. This parameter is supported only for AG-enabled publisher.
ownerTypeIdIntegerYes

Possible Values are:

Type of AccountValue
Publisher1
Demand Partner5
ATD/Buyer7
Indicates the type of account of the user invoking this API.
ownerIdLongYesShould be a valid Publisher ID, DSP ID, or Buyer ID.Indicates account ID

Sample Request for IAB-enabled User

Sample URL

POST $URI_PREFIX/products

 

Sample Request JSON

 

{
"name" : "test name 24thmay - 1",
"description" : "test description 26thmay - 1",
"productIABCategory": ["IAB1","IAB2"],
"adSizes" : [7,9,10],
"adFoldPlacements" : [1,2,3,4],
"adCodeTypes" : [1,2,3,4],
"sites" : [1],
"adTags" :[2,3,4],
"sections" : [1,2],
"siteGroups":
  {
      "includes": [ 1, 2, 3 ],
      "excludes": [ 4, 5, 6 ]
   },
  "siteName" : "abc,xyz",
  "tags" : "sports,education",
  "companionAds" : true,

"minAdDuration" : 30,
"maxAdDuration" : 40,
"platforms" : [1,2],
"vastVersions" : [1,2],
"vpaidComplianceVersions" : [1,2],
"adServerInventoryUnits":[400]
}

 

Sample URL

POST $URI_PREFIX/products

 

Sample Request for IAB-disabled User

{
  "name": "test name 24thmay - 1",
  "description": "test description 26thmay - 1",
  "productCategory": [
    1
  ],
  "adSizes": [
    7,
    9,
    10
  ],
  "adFoldPlacements": [
    1
  ],
  "adCodeTypes": [
    1,
    2
  ],
  "sites": [
    1
  ],
  "adTags": [
    2,
    3,
    4
  ],
  "sections": [
    1,
    2
  ],
  "siteName": "www.test.com",
  "tags": "sports,education",
  "companionAds": true,
  "minAdDuration": 30,
  "maxAdDuration": 40,
  "platforms": [
    1,
    2
  ],
  "vastVersions": [
    1,
    2
  ],
  "vpaidComplianceVersions": [
    1,
    2
  ],
  "adServerInventoryUnits": [
    400
  ],
  "ownerType": 1,
  "ownerId": 12345
}

 

Response

Response Body

           

Type
Description
product object
JSON response of the successfully created product.

 

Sample Response for an IAB-enabled User

 

{
  "name": "test name 24thmay - 1",
  "description": "test description 26thmay - 1",
  "productIABCategory": [
    "IAB1",
    "IAB2"
  ],
  "adSizes": [
    7,
    9,
    10
  ],
  "adFoldPlacements": [
    1
  ],
  "adCodeTypes": [
    1,
    2
  ],
  "sites": [
    1
  ],
  "adTags": [
    2,
    3,
    4
  ],
  "sections": [
    1,
    2
  ],
  "siteName": "www.test.com",
  "tags": "sports,education",
  "companionAds": true,
  "minAdDuration": 30,
  "maxAdDuration": 40,
  "platforms": [
    1,
    2
  ],
  "vastVersions": [
    1,
    2
  ],
  "vpaidComplianceVersions": [
    1,
    2
  ],
  "adServerInventoryUnits": [
    400
  ],
  "ownerType": 1,
  "ownerId": 12345
}

 

 

Sample Response for a Non-IAB User

{
"id": 38879,
"creationTime": "2014-06-13T19:16:58Z",
"modificationTime": "2014-06-13T19:16:58Z",
"name": "Product 1",
"description": " sample description",
"tags": "abc,xyz",
"siteName": "abc,xyz",
"deleted": false,
"publisherId": 123,
"adSizes": [
{
"id": 7,
"name": "Leaderboard",
"uri": "$URI_PREFIX/common/adsize/7"
},
{
"id": 9,
"name": "Sidekick",
"uri": "$URI_PREFIX/common/adsize/9"
},
{
"id": 10,
"name": "Wide Skyscraper",
"uri": "$URI_PREFIX/common/adsize/10"
}
],
"productCategory": [
{
"id": 1,
"name": "education",
"uri": "$URI_PREFIX/common/vertical/1"
}
],
"adFoldPlacements": [
{
"id": 1,
"name": "Above the Fold"
},
{
"id": 2,
"name": "Below the Fold"
}
],
"adCodeTypes": [
{
"id": 0,
"name": "Iframe"
},
{
"id": 1,
"name": "JavaScript"
},
{
"id": 2,
"name": "Mobile AdTag"
},
{
"id": 3,
"name": "Video AdTag"
}
],
"sites": [
{
"id": 31446,
"name": "test site",
"uri": "$URI_PREFIX/inventory/publisherSites/31446"
},
{
"id": 31447,
"name": "test site 2",
"uri": "$URI_PREFIX/inventory/publisherSites/31447"
}
],
"adTags": [
{
"id": 30979,
"name": "test ad tag 1",
"uri": "$URI_PREFIX/inventory/publisherAdTag/30979"
},
{
"id": 30980,
"name": "test video ad tag 1",
"uri": "$URI_PREFIX/inventory/publisherAdTag/30980"
}
],
"sections": [
{
"id": 4,
"name": "Parenting",
"uri": "$URI_PREFIX/inventory/section/908"
}
],
"siteGroups": {
"includes": [
{
"id": 1,
"name": "TestSiteGroup1",
"uri": "$URI_PREFIX/inventory/siteGroup/1"
}
],
"excludes": [
{
"id": 2,
"name": "TestSiteGroup2",
"uri": "$URI_PREFIX/inventory/siteGroup/2"
}
]
},
"companionAds": true,
"minAdDuration": 30,
"maxAdDuration": 40,
"platforms": [
{
"id": 1,
"name": "Web"
},
{
"id": 2,
"name": "Mobile Web"
}
],
"vastVersions": [
{
"id": 2,
"name": "VAST 2.0"
},
{
"id": 3,
"name": "VAST 3.0"
}
],
"vpaidComplianceVersions": [
{
"id": 0,
"name": "No VPAID support"
},
{
"id": 1,
"name": "VPAID 1.0"
},
{
"id": 2,
"name": "VPAID 2.0"
}
],
"inventoryAdSize": [
{
"name": "Sidekick",
"width": 300,
"height": 250,
"categoryId": 0,
"id": 9,
"platformIds": [
1,
2,
4,
5
]
},
{
"name": "Leaderboard",
"width": 728,
"height": 90,
"categoryId": 0,
"id": 7,
"platformIds": [
1,
2,
4,
5
]
}
],
"inventoryAdFormat": [
{
"id": 1,
"name": "JAVASCRIPT"
}
],
"inventoryFoldPlacement": [
{
"id": 1,
"name": "ABOVE_THE_FOLD"
}
],
"inventoryPlatform": [
{
"id": 1,
"name": "WEB"
}
],
"inventoryVastVersions": [
{
"id": 2,
"name": "VAST 2.0"
}
],
"inventoryvpaidComplianceVersions": [
{
"id": 0,
"name": "No VPAID support"
}
],
"inventorySites": [
{
"id": 31446,
"name": "http://www.test_site.com"
}
],
"adServerInventoryUnits": [
{
"id": 400,
"name": "AMG-735-Adunit-Dinesh1"
}
],
"iabEnabled": false
}

 

Special Handling for "ALL" Use Case

For the sites and adTags fields, the following handling is done:

Request

sites: [ 0 ] will be considered as ALL sites for the publisher
adTags: [ 0 ] will be considered as ALL adTags for the publisher

 

Response

The sites/adTags fields in Response in ALL sites or adTags will be shown as:

sites: null

adTags: null

 

HTTP Response Status Codes

For the list of HTTP status codes, see "HTTP Status Codes".

 

Error Codes

Error CodeDescription
CC03_0008Multiple resource access users need to provide account details. Pass the ownerId and ownerType in request body.
CC02_0006User is not allowed to access this resource.
IU_001_0001Invalid product ID.
IU_001_0002Invalid user ID.
IU_001_0003Invalid name.
IU_001_0004Invalid owner ID.
IU_001_0005Invalid product type specified.
IU_001_0006Error in deleting product entities.
IU_001_0008Invalid description.
IU_001_0017Invalid or null value for owner type field.
IU_001_0018Product name cannot be null or empty.
IU_001_0019Product name cannot exceed 250 characters.
IU_001_0023Internal error in validating selected ad tags.
IU_001_0024Selected ad tags are invalid.
IU_001_0026Selected sites are invalid.
IU_001_0030Failed to locate a dozer file.
IU_001_0031Error in fetching publisher site details.
IU_001_0033Invalid product entity IDs.
IU_001_0037Invalid product category IDs passed.
IU_001_0038Invalid ad size IDs passed.
IU_001_0039Invalid fold placement IDs passed.
IU_001_0051Invalid publisher section IDs passed.
IU_001_0052Unable to retrieve details for ad tag.   
IU_001_0053Unable to filter ad tags.
IU_001_0054No ad tags found for the matching filters.
IU_001_0055Internal error in validating Ad tags.
IU_001_0056Invalid resource type found for logged in user.
IU_001_0061Error in fetching product details.
IU_001_0062No product found for given product ID.
IU_001_0063User does not have access to update product.
IU_001_0066No sites are associated for given user.
IU_001_0070Product name already exists. Please use another name.
IU_001_0071Invalid Ad Code Type IDs passed.
IU_001_0072At least one site or ad tag should be selected
IU_001_0073Invalid product name. The following characters are not allowed : |!{}[]^"~*?:;+\\
IU_001_0074Invalid product description. The following characters are not allowed : |!{}[]^"~*?:;+\\
IU_001_0075Product creation failed.
IU_001_0076Product description cannot exceed 512 characters.
IU_001_0077Invalid site group inclusion IDs passed.
IU_001_0078Invalid site group exclusion IDs passed.
IU_001_0079Product update failed.
IU_001_0080Product cannot be updated as it is being used in a transaction entity.
IU_001_0081Transaction count cannot be decremented as it is already zero.
IU_001_0082Used count cannot be decremented as it is already zero.
IU_001_0083Both sites and ad tags cannot be specified.
IU_001_0084Error in fetching ad tags for sites.
IU_001_0085No ad tag found for the given filters.
IU_001_0087ID cannot be given in the input while creating/updating a product.
IU_001_0088Invalid site names.
IU_001_0089Site names cannot exceed 255 characters.
IU_001_0090Invalid site names specified. Only alpha-numeric characters are allowed. Multiple site names should be comma separated.
IU_001_0091Invalid Tags.
IU_001_0092Tags cannot exceed 255 characters.
IU_001_0093Invalid tags specified. Only alpha-numeric characters are allowed. Multiple tags should be comma separated.
IU_001_0095Error in validating platforms.
IU_001_0096Invalid platforms passed.
IU_001_0097Invalid VAST versions passed.
IU_001_0098Invalid Minimum ad duration passed.
IU_001_0099Invalid Maximum ad duration passed.
IU_001_0100Maximum ad duration cannot be less than Minimum ad duration.
IU_001_0101Invalid VPAID compliance versions passed.
IU_001_0102Publisher ID filter is not applicable for this user.
IU_001_0103Incorrect loggedInOwnerTypeId provided in search operation for admin.
IU_001_0104SiteName cannot be null or empty.
IU_001_0105Product category cannot be null or empty.
IU_001_0106Video filters AdDuration, companionAds, VAST versions or VPAID Compliance versions cannot be selected if Video adCodeType is not selected.
IU_001_0107Each site should contain at least one active ad tag.
IU_001_0109Platform filter cannot be applied if ALL sites are selected.
IU_001_0110Ad tag filters cannot be applied if ALL ad tags are selected.

 

Sample Error Response 

[
{
"errorCode": "IU_001_0070",
"errorMessage": "Product name already exists. Please use another name."
}
]

 

 

Retrieving Details of a Product

 

Overview

This API allows you to retrieve the details of a specific product using the "id" parameter.

Request

         
URI

$URI_PREFIX/products/{id}


Note: For sandbox testing, $URI_PREFIX should be replaced with "http://api-sandbox.pubmatic.com/v1/inventory".

 

                                                     For production, $URI_PREFIX should be replaced with "http://api.pubmatic.com/v1/inventory/".
HTTP MethodGET

Request Headers

               

Header Name
Type
Value
Required
Description
Authorization
String
Bearer ${access_token}
Yes
The access token generated for authentication should be sent in place of ${access_token}.
For more information about access tokens, refer to Getting Started with PubMatic APIs

 

Path Parameters:

               
Parameter Name
Type
Required
Description
id
Long
Yes
ID of the product whose details need to be retrieved.
For example, 123

Sample Request URL

GET $URI_PREFIX/products/123

Response

Response Body

             
Response Body Parameter
Type
Description
ProductJSON for record objectDetails of the requested product

Product

                                                                                                                                                                             

Parameter
Type
Description
id
Integer
ID of the product
name
String
Name of the product
description
String
Description of the product
creationTime
ISO Date
Time (in GMT) at which the product was created
modificationTime
ISO Date
Time (in GMT) at which the product was last modified
productCategory
List of productCategory objects
For non-IAB users: Verticals associated with the product. Example:Automotive, Education
For IAB-enabled users: IAB Categories for the product. Example: Automotive, Education
iabEnabledBooleanIndicates whether productCategory response contains PubMatic or IAB categories
adSizes
List of adSizes objects
Ad sizes associated with the product
adFoldPlacements
List of adFoldPlacements objects
Ad fold placements associated with the product
adCodeTypes
List of adCodeTypes objects
Types of ad tags associated with the product
siteGroups
List of siteGroups objects
Site groups included in the product (siteGroups.includes) and/or excluded from the product (siteGroups.excludes)
sites
List of sites objects
Sites associated with the product
adTags
List of adTags objects
Ad tags associated with the product
sections
List of sections objects
Sections associated with the product
siteName
String
Actual page URL of the publisher where the creative will be served
tags
String
Keywords/tags used to search the product
deleted
Boolean
Indicates whether the product is deleted. Possible options are:
  • true - deleted,
  • false - not deleted
publisherId
Integer
Publisher who owns this product
platforms
JSON Array of Integer
Platforms for the product, for example, Web, Mobile Web.
companionAds
Boolean
Indicates whether the companion ads support is required.
vastVersions
Boolean
Filtering parameter for video ad tag.
minAdDuration
Integer
Minimum duration required for video ad.
maxAdDuration
Integer
Maximum duration required for video ad.
vpaidComplianceVersions
JSON Array of Integer
Filtering parameter for ad tags.
inventoryAdSizeJSON Array of AdSizes

Indicates the ad sizes available in selected inventory (Site / AdTag)

inventoryAdFormatJSON Array of AdFormat

Indicates the ad formats available in selected inventory (Site / AdTag)

inventoryFoldPlacementJSON Array of FoldPlacement

Indicates the fold placements available in selected inventory (Site/AdTag)

inventoryPlatformJSON Array of Platform

Indicates the platforms available in selected inventory (Site/AdTag)

inventoryVastVersionsJSON Array of VastVersion

Video ad format (VAST version) supported as per the IAB standards in response for the selected inventory (Site/AdTag)

inventoryvpaidComplianceVersionsJSON Array of VPaidComplianceVersion

Video ad API (VPAID) compliance versions supported as per IAB response for the selected inventory (Site/AdTag)

inventorySitesJSON Array of SitesSites derived from the selected inventory
iabEnabledBoolean flagIndicates if the user is IAB enabled or not
adServerInventoryUnitsJSON Array of IntegerAdUnit or Placement for a given Publisher AdServer

 

Note : Fields which are named as "inventoryXXX" in the response JSON, represent the actual inventory of the Product. For example, "adSizes", "platforms", "foldPlacements" fields in the response denote the filters selected while creating the product. Whereas, "inventoryAdSize", "inventoryPlatform", "inventoryFoldPlacement" are the actual as sizes, platforms and fold placements of the Product. These are the valid inventory parameters derived by applying the filters in the Product. External partners should use "inventoryXXX" fields.

                                                          

 

Sample Response for an IAB-enabled User

{
    "id": 38879,
    "creationTime": "2014-06-13T19:16:58Z",
    "modificationTime": "2014-06-13T19:16:58Z",
    "name": "Product 1",
    "description": " sample description",
    "tags": "abc,xyz",
    "siteName": "abc,xyz",
    "deleted": false,
    "publisherId": 123,
    "adSizes": [
        {
            "id": 7,
            "name": "Leaderboard",
            "uri": "$URI_PREFIX/common/adsize/7"
        },
        {
            "id": 9,
            "name": "Sidekick",
            "uri": "$URI_PREFIX/common/adsize/9"
        },
        {
            "id": 10,
            "name": "Wide Skyscraper",
            "uri": "$URI_PREFIX/common/adsize/10"
        }
    ],
    "productCategory": [
        {
            "id": 52,
            "name": "education",
            "uri": "$URI_PREFIX/common/iabCategories/IAB2",
            "iabCategoryId": "IAB2"
        }
    ],
    "adFoldPlacements": [
        {
            "id": 1,
            "name": "Above the Fold"
        },
        {
            "id": 2,
            "name": "Below the Fold"
        }
    ],
    "adCodeTypes": [
        {
            "id": 0,
            "name": "Iframe"
        },
        {
            "id": 1,
            "name": "JavaScript"
        },
        {
            "id": 2,
            "name": "Mobile AdTag"
        },
        {
            "id": 3,
            "name": "Video AdTag"
        }
    ],
    "sites": [
        {
            "id": 31446,
            "name": "test site",
            "uri": "$URI_PREFIX/inventory/publisherSites/31446"
        },
        {
            "id": 31447,
            "name": "test site 2",
            "uri": "$URI_PREFIX/inventory/publisherSites/31447"
        }
    ],
    "adTags": [
        {
            "id": 30979,
            "name": "test ad tag 1",
            "uri": "$URI_PREFIX/inventory/publisherAdTag/30979"
        },
        {
            "id": 30980,
            "name": "test video ad tag 1",
            "uri": "$URI_PREFIX/inventory/publisherAdTag/30980"
        }
    ],
    "sections": [
        {
            "id": 4,
            "name": "Parenting",
            "uri": "$URI_PREFIX/inventory/section/908"
        }
    ],
    "siteGroups": {
        "includes": [
            {
                "id": 1,
                "name": "TestSiteGroup1",
                "uri": "$URI_PREFIX/inventory/siteGroup/1"
            }
        ],
        "excludes": [
            {
                "id": 2,
                "name": "TestSiteGroup2",
                "uri": "$URI_PREFIX/inventory/siteGroup/2"
            }
        ]
    },
    "companionAds": true,
    "minAdDuration": 30,
    "maxAdDuration": 40,
    "platforms": [
        {
            "id": 1,
            "name": "Web"
        },
        {
            "id": 2,
            "name": "Mobile Web"
        }
    ],
    "vastVersions": [
        {
            "id": 2,
            "name": "VAST 2.0"
        },
        {
            "id": 3,
            "name": "VAST 3.0"
        }
    ],
    "vpaidComplianceVersions": [
        {
            "id": 0,
            "name": "No VPAID support"
        },
        {
            "id": 1,
            "name": "VPAID 1.0"
        },
        {
            "id": 2,
            "name": "VPAID 2.0"
        }
    ],
    "inventoryAdSize": [
        {
            "name": "Sidekick",
            "width": 300,
            "height": 250,
            "categoryId": 0,
            "id": 9,
            "platformIds": [
                1,
                2,
                4,
                5
            ]
        },
        {
            "name": "Leaderboard",
            "width": 728,
            "height": 90,
            "categoryId": 0,
            "id": 7,
            "platformIds": [
                1,
                2,
                4,
                5
            ]
        }
    ],
    "inventoryAdFormat": [
        {
            "id": 1,
            "name": "JAVASCRIPT"
        }
    ],
    "inventoryFoldPlacement": [
        {
            "id": 1,
            "name": "ABOVE_THE_FOLD"
        }
    ],
    "inventoryPlatform": [
        {
            "id": 1,
            "name": "WEB"
        }
    ],
    "inventoryVastVersions": [
        {
            "id": 2,
            "name": "VAST 2.0"
        }
    ],
    "inventoryvpaidComplianceVersions": [
        {
            "id": 0,
            "name": "No VPAID support"
        }
    ],
    "inventorySites": [
        {
            "id": 31446,
            "name": "http://www.test_site.com"
        }
    ],
    "adServerInventoryUnits": [
        {
            "id": 400,
            "name": "AMG-735-Adunit-Dinesh1"
        }
    ],
    "iabEnabled": true
}

 

 

Sample Response for a Non-IAB User

 

{
"id": 38879,
"creationTime": "2014-06-13T19:16:58Z",
"modificationTime": "2014-06-13T19:16:58Z",
"name": "Product 1",
"description": " sample description",
"tags": "abc,xyz",
"siteName": "abc,xyz",
"deleted": false,
"publisherId": 123,
"adSizes": [
{
"id": 7,
"name": "Leaderboard",
"uri": "$URI_PREFIX/common/adsize/7"
},
{
"id": 9,
"name": "Sidekick",
"uri": "$URI_PREFIX/common/adsize/9"
},
{
"id": 10,
"name": "Wide Skyscraper",
"uri": "$URI_PREFIX/common/adsize/10"
}
],
"productCategory": [
{
"id": 1,
"name": "education",
"uri": "$URI_PREFIX/common/vertical/1"
}
],
"adFoldPlacements": [
{
"id": 1,
"name": "Above the Fold"
},
{
"id": 2,
"name": "Below the Fold"
}
],
"adCodeTypes": [
{
"id": 0,
"name": "Iframe"
},
{
"id": 1,
"name": "JavaScript"
},
{
"id": 2,
"name": "Mobile AdTag"
},
{
"id": 3,
"name": "Video AdTag"
}
],
"sites": [
{
"id": 31446,
"name": "test site",
"uri": "$URI_PREFIX/inventory/publisherSites/31446"
},
{
"id": 31447,
"name": "test site 2",
"uri": "$URI_PREFIX/inventory/publisherSites/31447"
}
],
"adTags": [
{
"id": 30979,
"name": "test ad tag 1",
"uri": "$URI_PREFIX/inventory/publisherAdTag/30979"
},
{
"id": 30980,
"name": "test video ad tag 1",
"uri": "$URI_PREFIX/inventory/publisherAdTag/30980"
}
],
"sections": [
{
"id": 4,
"name": "Parenting",
"uri": "$URI_PREFIX/inventory/section/908"
}
],
"siteGroups": {
"includes": [
{
"id": 1,
"name": "TestSiteGroup1",
"uri": "$URI_PREFIX/inventory/siteGroup/1"
}
],
"excludes": [
{
"id": 2,
"name": "TestSiteGroup2",
"uri": "$URI_PREFIX/inventory/siteGroup/2"
}
]
},
"companionAds": true,
"minAdDuration": 30,
"maxAdDuration": 40,
"platforms": [
{
"id": 1,
"name": "Web"
},
{
"id": 2,
"name": "Mobile Web"
}
],
"vastVersions": [
{
"id": 2,
"name": "VAST 2.0"
},
{
"id": 3,
"name": "VAST 3.0"
}
],
"vpaidComplianceVersions": [
{
"id": 0,
"name": "No VPAID support"
},
{
"id": 1,
"name": "VPAID 1.0"
},
{
"id": 2,
"name": "VPAID 2.0"
}
],
"inventoryAdSize": [
{
"name": "Sidekick",
"width": 300,
"height": 250,
"categoryId": 0,
"id": 9,
"platformIds": [
1,
2,
4,
5
]
},
{
"name": "Leaderboard",
"width": 728,
"height": 90,
"categoryId": 0,
"id": 7,
"platformIds": [
1,
2,
4,
5
]
}
],
"inventoryAdFormat": [
{
"id": 1,
"name": "JAVASCRIPT"
}
],
"inventoryFoldPlacement": [
{
"id": 1,
"name": "ABOVE_THE_FOLD"
}
],
"inventoryPlatform": [
{
"id": 1,
"name": "WEB"
}
],
"inventoryVastVersions": [
{
"id": 2,
"name": "VAST 2.0"
}
],
"inventoryvpaidComplianceVersions": [
{
"id": 0,
"name": "No VPAID support"
}
],
"inventorySites": [
{
"id": 31446,
"name": "http://www.test_site.com"
}
],
"adServerInventoryUnits": [
{
"id": 400,
"name": "AMG-735-Adunit-Dinesh1"
}
],
"iabEnabled": false
}

Special Handling for "ALL" Use Case

For the sites and adTags fields, the following handling is done:

Request

sites: [ 0 ] will be considered as ALL sites for the publisher
adTags: [ 0 ] will be considered as ALL adTags for the publisher

 

Response

The sites/adTags fields in Response in ALL sites or adTags will be shown as:

sites: null

adTags: null

 

HTTP Response Status Codes

For the list of HTTP status codes, see "HTTP Status Codes".

 

Error Codes

Error CodeDescription
IU_001_0062No product found for given product ID.
IU_001_0061Error in fetching product details.
CC02_0006User is not allowed to access this resource

 

Sample Error Response 

[
{
"errorCode": "IU_001_0062",
"errorMessage": "No product found for given product Id."
}
]

 

Retrieving List of Products (for Publishers)

 

Overview

This API allows you to retrieve the list of products matching the supplied filter parameters. Various filter parameters can be applied to narrow down the search results.

 

Request

URI

$URI_PREFIX/products

Note: For sandbox testing, $URI_PREFIX should be replaced with "http://api-sandbox.pubmatic.com/v1/inventory".

For production, $URI_PREFIX should be replaced with "http://api.pubmatic.com/v1/inventory/".
           

                                 
HTTP MethodGET

Request Headers

               

Header Name
Type
Value
Required
Description
Authorization
String
Bearer ${access_token}
Yes
The access token generated for authentication should be sent in 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
pageSize
Integer
No
 
Maximum number of rows to be included in the response.
Default value: 100
pageNumber
Integer
No
 
Page number to be fetched in case of multiple pages.
Default value: 1
filters
String
No
Values must be from those mentioned below in the supported Dimensions section.
Filters that restrict the data returned for your request.
For more details, refer the Reporting and Listing API Request Details section.
sort
String
No
Values must be from those mentioned below in the supported Dimensions section.
A list of comma-separated dimensions indicating the sorting order and sorting direction for the returned data.
For more details, refer the Reporting and Listing API Request Details section.

Note: For more details on the filter and sort parameters, refer the Reporting and Listing API Request Details section. notLike filter operator is not supported.

Dimension

                               
Name
Data Type
Summary
Sample filter data
Sample sort data
idIntegerID of the productid gt 10

For ascending, use ?sort=id

For descending, use ?sort=-id

nameStringName of the productname like test

For ascending, use ?sort=name

For descending, use ?sort=-name

descriptionStringDescription of the productdescription like test 
loggedInOwnerTypeIdInteger

Indicates type of account. Possible values are:

 

Type of AccountValue
Publisher1
Demand Partner5
ATD/Buyer7
&filters=loggedInOwnerTypeId eq 1
loggedInOwnerIdLong

Account ID

&filters=loggedInOwnerId eq 12345

Sample Request

GET $URI_PREFIX/products?filters=loggedInOwnerTypeId eq 1&filters=loggedInOwnerId eq 12345&pageSize=25&pageNumber=1&filters=name like test

Response

Response Body

                  
Response Body Parameter
Type
Description
itemsJSON Array of record objectFetches the records formed as per your request.
metaDataJSON Object Metadata about the generated response.

Sample Response for an IAB-enabled Users

 

{
"metaData": {
"startIndex": 1,
"request": {
"pageSize": 2,
"pageNumber": 1,
"metrics": null,
"dimensions": null,
"sort": "-id",
"filters": null,
"fromDate": "2010-01-02",
"toDate": "2099-01-01",
"tz": null,
"originalQuery": "pageSize=2&pageNumber=0&fromDate=2010-01-02&toDate=2010-01-02"
},
"totalRecords": 123,
"endIndex": 2
},
"items": [
{
"id": 1,
"creationTime": "2014-06-13T19:16:58Z",
"modificationTime": "2014-06-13T19:16:58Z",
"name": "Product 1",
"description": " sample description",
"tags": "abc,xyz",
"siteName": "abc,xyz",
"deleted": false,
"publisherId": 123,
"adSizes": [
{
"id": 7,
"name": "Leaderboard",
"uri": "$URI_PREFIX/common/adsize/7"
},
{
"id": 9,
"name": "Sidekick",
"uri": "$URI_PREFIX/common/adsize/9"
},
{
"id": 10,
"name": "Wide Skyscraper",
"uri": "$URI_PREFIX/common/adsize/10"
}
],
"productCategory": [
{
"id": 52,
"name": "education",
"uri": "$URI_PREFIX/common/iabCategories/IAB2",
"iabCategoryId": "IAB2"
}
],
"adFoldPlacements": [
{
"id": 1,
"name": "Above the Fold"
},
{
"id": 2,
"name": "Below the Fold"
}
],
"adCodeTypes": [
{
"id": 0,
"name": "Iframe"
},
{
"id": 1,
"name": "JavaScript"
},
{
"id": 2,
"name": "Mobile AdTag"
},
{
"id": 3,
"name": "Video AdTag"
}
],
"sites": [
{
"id": 31446,
"name": "test site",
"uri": "$URI_PREFIX/inventory/publisherSites/31446"
},
{
"id": 31447,
"name": "test site 2",
"uri": "$URI_PREFIX/inventory/publisherSites/31447"
}
],
"adTags": [
{
"id": 30979,
"name": "test ad tag 1",
"uri": "$URI_PREFIX/inventory/publisherAdTag/30979"
},
{
"id": 30980,
"name": "test video ad tag 1",
"uri": "$URI_PREFIX/inventory/publisherAdTag/30980"
}
],
"sections": [
{
"id": 4,
"name": "Parenting",
"uri": "$URI_PREFIX/inventory/section/908"
}
],
"siteGroups": {
"includes": [
{
"id": 1,
"name": "TestSiteGroup1",
"uri": "$URI_PREFIX/inventory/siteGroup/1"
}
],
"excludes": [
{
"id": 2,
"name": "TestSiteGroup2",
"uri": "$URI_PREFIX/inventory/siteGroup/2"
}
]
},
"companionAds": true,
"minAdDuration": 30,
"maxAdDuration": 40,
"platforms": [
{
"id": 1,
"name": "Web"
},
{
"id": 2,
"name": "Mobile Web"
}
],
"vastVersions": [
{
"id": 2,
"name": "VAST 2.0"
},
{
"id": 3,
"name": "VAST 3.0"
}
],
"vpaidComplianceVersions": [
{
"id": 0,
"name": "No VPAID support"
},
{
"id": 1,
"name": "VPAID 1.0"
},
{
"id": 2,
"name": "VPAID 2.0"
}
],
"inventoryAdSize": null,
"inventoryAdFormat": null,
"inventoryFoldPlacement": null,
"inventoryPlatform": null,
"inventoryVastVersions": null,
"inventoryvpaidComplianceVersions": null,
"inventorySites": null,
"adServerInventoryUnits": [
{
"id": 400,
"name": "AMG-735-Adunit-Dinesh1"
}
],
"iabEnabled": true
},
{
"id": 2,
"creationTime": "2014-06-13T19:16:58Z",
"modificationTime": "2014-06-13T19:16:58Z",
"name": "Product 2",
"description": " sample description",
"tags": "abc,xyz",
"siteName": "abc,xyz",
"deleted": false,
"publisherId": 123,
"adSizes": [
{
"id": 7,
"name": "Leaderboard",
"uri": "$URI_PREFIX/common/adsize/7"
},
{
"id": 9,
"name": "Sidekick",
"uri": "$URI_PREFIX/common/adsize/9"
},
{
"id": 10,
"name": "Wide Skyscraper",
"uri": "$URI_PREFIX/common/adsize/10"
}
],
"productCategory": [
{
"id": 52,
"name": "education",
"uri": "$URI_PREFIX/common/iabCategories/IAB2",
"iabCategoryId": "IAB2"
}
],
"adFoldPlacements": [
{
"id": 1,
"name": "Above the Fold"
},
{
"id": 2,
"name": "Below the Fold"
}
],
"adCodeTypes": [
{
"id": 0,
"name": "Iframe"
},
{
"id": 1,
"name": "JavaScript"
},
{
"id": 2,
"name": "Mobile AdTag"
},
{
"id": 3,
"name": "Video AdTag"
}
],
"sites": [
{
"id": 31446,
"name": "test site",
"uri": "$URI_PREFIX/inventory/publisherSites/31446"
},
{
"id": 31447,
"name": "test site 2",
"uri": "$URI_PREFIX/inventory/publisherSites/31447"
}
],
"adTags": [
{
"id": 30979,
"name": "test ad tag 1",
"uri": "$URI_PREFIX/inventory/publisherAdTag/30979"
},
{
"id": 30980,
"name": "test video ad tag 1",
"uri": "$URI_PREFIX/inventory/publisherAdTag/30980"
}
],
"sections": [
{
"id": 4,
"name": "Parenting",
"uri": "$URI_PREFIX/inventory/section/908"
}
],
"siteGroups": {
"includes": [
{
"id": 1,
"name": "TestSiteGroup1",
"uri": "$URI_PREFIX/inventory/siteGroup/1"
}
],
"excludes": [
{
"id": 2,
"name": "TestSiteGroup2",
"uri": "$URI_PREFIX/inventory/siteGroup/2"
}
]
},
"companionAds": true,
"minAdDuration": 30,
"maxAdDuration": 40,
"platforms": [
{
"id": 1,
"name": "Web"
},
{
"id": 2,
"name": "Mobile Web"
}
],
"vastVersions": [
{
"id": 2,
"name": "VAST 2.0"
},
{
"id": 3,
"name": "VAST 3.0"
}
],
"vpaidComplianceVersions": [
{
"id": 0,
"name": "No VPAID support"
},
{
"id": 1,
"name": "VPAID 1.0"
},
{
"id": 2,
"name": "VPAID 2.0"
}
],
"inventoryAdSize": null,
"inventoryAdFormat": null,
"inventoryFoldPlacement": null,
"inventoryPlatform": null,
"inventoryVastVersions": null,
"inventoryvpaidComplianceVersions": null,
"inventorySites": null,
"adServerInventoryUnits": [
{
"id": 400,
"name": "AMG-735-Adunit-Dinesh1"
}
],
"iabEnabled": true
}
]
}
Sample Response for a Non-IAB User
{
"metaData": {
"startIndex": 1,
"request": {
"pageSize": 2,
"pageNumber": 1,
"metrics": null,
"dimensions": null,
"sort": "-id",
"filters": null,
"fromDate": "2010-01-02",
"toDate": "2099-01-01",
"tz": null,
"originalQuery": "pageSize=2&pageNumber=0&fromDate=2010-01-02&toDate=2010-01-02"
},
"totalRecords": 123,
"endIndex": 2
},
"items": [
{
"id": 1,
"creationTime": "2014-06-13T19:16:58Z",
"modificationTime": "2014-06-13T19:16:58Z",
"name": "Product 1",
"description": " sample description",
"tags": "abc,xyz",
"siteName": "abc,xyz",
"deleted": false,
"publisherId": 123,
"adSizes": [
{
"id": 7,
"name": "Leaderboard",
"uri": "$URI_PREFIX/common/adsize/7"
},
{
"id": 9,
"name": "Sidekick",
"uri": "$URI_PREFIX/common/adsize/9"
},
{
"id": 10,
"name": "Wide Skyscraper",
"uri": "$URI_PREFIX/common/adsize/10"
}
],
"productCategory": [
{
"id": 1,
"name": "education",
"uri": "$URI_PREFIX/common/vertical/1"
}
],
"adFoldPlacements": [
{
"id": 1,
"name": "Above the Fold"
},
{
"id": 2,
"name": "Below the Fold"
}
],
"adCodeTypes": [
{
"id": 0,
"name": "Iframe"
},
{
"id": 1,
"name": "JavaScript"
},
{
"id": 2,
"name": "Mobile AdTag"
},
{
"id": 3,
"name": "Video AdTag"
}
],
"sites": [
{
"id": 31446,
"name": "test site",
"uri": "$URI_PREFIX/inventory/publisherSites/31446"
},
{
"id": 31447,
"name": "test site 2",
"uri": "$URI_PREFIX/inventory/publisherSites/31447"
}
],
"adTags": [
{
"id": 30979,
"name": "test ad tag 1",
"uri": "$URI_PREFIX/inventory/publisherAdTag/30979"
},
{
"id": 30980,
"name": "test video ad tag 1",
"uri": "$URI_PREFIX/inventory/publisherAdTag/30980"
}
],
"sections": [
{
"id": 4,
"name": "Parenting",
"uri": "$URI_PREFIX/inventory/section/908"
}
],
"siteGroups": {
"includes": [
{
"id": 1,
"name": "TestSiteGroup1",
"uri": "$URI_PREFIX/inventory/siteGroup/1"
}
],
"excludes": [
{
"id": 2,
"name": "TestSiteGroup2",
"uri": "$URI_PREFIX/inventory/siteGroup/2"
}
]
},
"companionAds": true,
"minAdDuration": 30,
"maxAdDuration": 40,
"platforms": [
{
"id": 1,
"name": "Web"
},
{
"id": 2,
"name": "Mobile Web"
}
],
"vastVersions": [
{
"id": 2,
"name":