Offers API

Document created by pubmatic-archivist on Mar 27, 2017Last modified by david.simerly on Apr 10, 2018
Version 8Show Document
  • View in full screen mode

Before using PubMatic APIs, first generate the API Token. For more information, refer to Getting Started with PubMatic APIs

Description

An offer is a combination of a product and a targeting unit which you can then sell to specific buyers for a proposed amount. These APIs allows a user to create and manage offers in the PubMatic system.

 

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

Methods

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

Creating an Offer

/offers/{id}GETRetrieve the details of a specific offer

Retrieving Details of an Offer (for Publishers)


Retrieving Details of an Offer (for Demand Partners)

/offersGETRetrieve the list of offers
/offers/{id}PUTUpdate the details of a specific offerUpdating an Offer
/offers/{id}DELETEDelete an OfferDeleting an Offer

 

 

Creating an Offer

 

Overview

This API allows you to create an offer in the PubMatic system.

Request

         
URI

$URI_PREFIX/offers


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 MethodPOST

Request Headers

                 

Header Name
Type
Value
Required
Description
Authorization
String
Bearer ${access_token}
Yes
Need to send the access token generating for authentication at the place of ${access_token}.
For more information about access tokens, refer to Getting Started with PubMatic APIs

Request Body

                                                                                                                                                                                                

Body Parameter
Type
Required
Validations
Description
name
String
Yes
  • Maximum length is 255 characters
  • Name should be unique for your account
  • Characters check should be done
Name of the offer.
description
 String
No
  • Maximum length is 512 characters
  • Characters check should be done
Description about the offer.
notes
String
No
  • Maximum length is 512 characters
  • Characters check should be done
Note about the offer.
logoPath
String
No
  • Valid URL check should be done
  • Maximum length is 256 characters
  • Characters check should be done
Path of the logo for the offer.
tags
String
No
  • Values should be comma-separated strings
  • Characters allowed are alphabets, digits, space
  • Maximum length is 255 characters
Hashtags/Keywords which will be used to search the offer.
product
Integer
Yes
  • Value should already exist in the system
  • User should have access to the specified product
ID of the product to be associated with the offer.
targeting
Integer
No
  • Value should already exist in the system
  • User should have access to the specified targeting
ID of the targeting to be associated with the offer.
timezone
Integer
No (Default is PST)
Value should already exist in the system. For a list of available time zones, refer the Reference data section.
ID of the timezone which is used to define startDate and endDate of the offer
offerStartDate
ISO Date
Yes
  • Offer Start date is Mandatory.
  • Offer should not be available beyond the specified date range.
  • Offer Start date cannot be earlier than today.
  • Offer Start date should be sent in GMT.
Date from which the offer will be visible for discovery.
offerEndDate
ISO Date
Yes
  • Offer End date is Mandatory.
  • Offer should not be available beyond the specified date range.
  • Offer End date can be equal to or greater than offer start date.
  • Offer End date should be sent in GMT.
Date till which the offer will be visible for discovery.
transactionStartDate
ISO Date
Yes
  • Transaction Start date is Mandatory.
  • Transaction Start date should be sent in GMT.
  • Transaction start date cannot be earlier than offer start date.
Date from which offer can be bought or transacted
transactionEndDate
ISO Date
Yes
  • Transaction End date is Mandatory.
  • Transaction End date can be equal or greater than transaction start date.
  • Offer End date should be sent in GMT.
Date till which offer can be bought or transacted
impressions
Long
No
Valid numeric value with a minimum value of 0
Number of impressions available in the offer.
percentageAvails
Integer
No
Valid numeric value with a minimum value of 0 and a maximum value of 100
Percentage of the avails defined by the publisher that will be used in this offer.
cpm
Decimal
Yes
Valid decimal value with a minimum value of 0.00 and a maximum value of 999.99
eCPM at which the offer will be available.
spend
Decimal
No
 
Spend expected for the offer.
minSpend
Decimal
No
Valid decimal value with a minimum value of 0
Minimum spend expected for the offer.
currency
Integer
No (Default is USD)
Value should already exist in the system. For a list of available currencies, refer the Reference data section.
Currency used to define the spend for the offer.
oneClickBuy
Boolean
No (Default is false)
Valid Boolean value
Indicates whether the offer is available for one-click buy or not.
featured
Boolean
No (Default is false)
Valid Boolean value
Indicates whether the offer should be marked as featured or not.
customizableEntities
JSON array of Integers
No
Value should already exist in the system.
Identifiers of entities that can be customized or edited in the offer.
channels
JSON array of Integers
Yes
  • Value should already exist in the system.
  • For a list of channels, refer the Reference data section.
  • A single valid value will be accepted for channel except "All".
IDs of the channels (such as PMP, RTB, Spot buys, etc.) using which the offer can be used.
dsps
JSON array of Integers
No
  • Value should already exist in the system
  • Offer will be visible to a DSP only when
    • The offer is made discoverable to the DSP and
    • During the specified date range of the offer
IDs of DSPs to whom the offer will be available / discoverable.
buyers
JSON array of Integers
No
  • Value should already exist in the system
  • Offer will be visible to a buyer/ATD only when
    • The offer is made discoverable to the buyer/ATD and
    • During the specified date range of the offer.
IDs of ATDs/buyers to whom the offer will be available / discoverable.
advertisers
JSON array of Integers
No
  • Value should already exist in the system
  • Offer will be visible to the advertiser only when
    • The offer is made discoverable to the advertiser and
    • During the specified date range of the offer.
IDs of Advertisers to whom this offer is available / discoverable.
publishers
JSON array of Integers
No
  • Value should already exist in the system
  • Offer will be visible to a publisher only when
    • The offer is made discoverable to the publisher and
    • During the specified date range of the offer.
Identifiers of publishers to whom this offer is available / discoverable.

Sample Request


POST $URI_PREFIX/offers

{

    "name": "test offer 123",

    "description": "test description 1234",

    "tags": "test hashtag, hastag123",

    "notes": "test notes",

    "logoPath": "test logo path",

    "product": 3,

    "targeting": 1,

    "timezone": 1,

    "offerStartDate": "2014-11-17T00:00:00Z",

    "offerEndDate": "2014-11-25T10:00:00Z",

    "transactionStartDate": "2014-11-17T00:00:00Z",

    "transactionEndDate": "2014-11-25T10:00:00Z",

    "impressions": 1500000,

    "percentageAvails": 30,

    "cpm": 4.5,

    "spend": 75000,

    "minSpend": 50000,

    "oneClickBuy": true,

    "featured": true,

    "currency": 1,

    "channels": [

        1

    ],

    "dsps": [

        1,

        2

    ],

    "buyers": [

        1,

        2,

        3,

        4

    ],

    "advertisers": [

        1,

        2

    ]

}


Response

Response Body

           
Type
Description
Offer objectJSON response of successfully-created offer

Sample Response for an IAB-enabled User

{
    "id": 123,
    "name": "test offer 123",
    "description": "test description",
    "notes": "test notes",
    "tags": "test hashtag, hastag123",
    "logoPath": "test logo path",
    "publisherId": 1234,
    "deleted": false,
    "creationTime": "2014-08-30T19:16:58Z",
    "modificationTime": "2014-08-30T19:16:58Z",
    "product": {
        "id": 3,
        "name": "test inventory unit 3",
        "uri": "$URI_PREFIX/products/3",
        "productCategory": [
            {
                "id": 52,
                "name": "Automotive",
                "iabCategoryId": "IAB1"
            },
            {
                "id": 76,
                "name": "Business",
                "iabCategoryId": "IAB2"

             }
        ],
        "platforms": [
            {
                "id": 1,
                "name": "Web"
            },
            {
                "id": 2,
                "name": "Mobile Web"
            },
            {
                "id": 4,
                "name": "Mobile App IOS"
            }
        ],
        "iabEnabled": true
    },
    "targeting": {
        "id": 1,
        "name": "test targeting unit 1",
        "uri": "$URI_PREFIX/targeting/1"
    },
    "timezone": {
        "id": 1,
        "name": "PST"
    },
    "offerStartDate": "2014-08-30T12:00:00Z",
    "offerEndDate": "2014-12-31T12:00:00Z",
    "transactionStartDate": "2014-11-01T00:00:00Z",
    "transactionEndDate": "2014-11-30T10:00:00Z",
    "impressions": 1500000,
    "percentageAvails": 30,
    "cpm": 4.5,
    "spend": 75000,
    "minSpend": 50000,
    "currency": {
        "id": 1,
        "name": "USD"
    },
    "oneClickBuy": true,
    "featured": true,
    "channels": [
        {
            "id": 1,
            "name": "PMP"
        }
    ],
    "dsps": [
        {
            "id": 1,
            "name": "DSP 1",
            "uri": "$URI_PREFIX/advertisingEntity/1"
        },
        {
            "id": 2,
            "name": "DSP 2",
            "uri": "$URI_PREFIX/advertisingEntity/2"
        }
    ],
    "buyers": [
        {
            "id": 1,
            "name": "Buyer 1",
            "uri": "$URI_PREFIX/buyer/1"
        },
        {
            "id": 2,
            "name": "Buyer 2",
            "uri": "$URI_PREFIX/buyer/2"
        },
        {
            "id": 3,
            "name": "Buyer 3",
            "uri": "$URI_PREFIX/buyer/3"
        },
        {
            "id": 4,
            "name": "Buyer 4",
            "uri": "$URI_PREFIX/buyer/4"
        }
    ],
    "advertisers": [
        {
            "id": 1,
            "name": "Advertiser 1",
            "uri": "$URI_PREFIX/advertiser/1"
        },
        {
            "id": 2,
            "name": "Advertiser 2",
            "uri": "$URI_PREFIX/advertiser/2"
        }
    ]
}

 

Sample Response for a Non-IAB User


{
    "id": 123,
    "name": "test offer 123",
    "description": "test description",
    "notes": "test notes",
    "tags": "test hashtag, hastag123",
    "logoPath": "test logo path",
    "publisherId": 1234,
    "deleted": false,
    "creationTime": "2014-08-30T19:16:58Z",
    "modificationTime": "2014-08-30T19:16:58Z",
  "product": {
    "id": 3,
    "name": "test inventory unit 3",
    "uri": "$URI_PREFIX/products/3",
    "productCategory": [
      {
        "id": 2,
        "name": "Automotive",
        "iabCategoryId": null
      },
      {
        "id": 3,
        "name": "Business and Finance",
        "iabCategoryId": null
      }
    ],
    "platforms": [
      {
        "id": 1,
        "name": "Web"
      },
      {
        "id": 2,
        "name": "Mobile Web"
      },
      {
        "id": 4,
        "name": "Mobile App IOS"
      }
    ],
    "iabEnabled": false
  }
    "targeting": {
        "id": 1,
        "name": "test targeting unit 1",
        "uri": "$URI_PREFIX/targeting/1"
    },
    "timezone": {
        "id": 1,
        "name": "PST"
    },
    "offerStartDate": "2014-08-30T12:00:00Z",
    "offerEndDate": "2014-12-31T12:00:00Z",
    "transactionStartDate": "2014-11-01T00:00:00Z",
    "transactionEndDate": "2014-11-30T10:00:00Z",
    "impressions": 1500000,
    "percentageAvails": 30,
    "cpm": 4.5,
    "spend": 75000,
    "minSpend": 50000,
    "currency": {
        "id": 1,
        "name": "USD"
    },
    "oneClickBuy": true,
    "featured": true,
    "channels": [
        {
            "id": 1,
            "name": "PMP"
        }
    ],
    "dsps": [
        {
            "id": 1,
            "name": "DSP 1",
            "uri": "$URI_PREFIX/advertisingEntity/1"
        },
        {
            "id": 2,
            "name": "DSP 2",
            "uri": "$URI_PREFIX/advertisingEntity/2"
        }
    ],
    "buyers": [
        {
            "id": 1,
            "name": "Buyer 1",
            "uri": "$URI_PREFIX/buyer/1"
        },
        {
            "id": 2,
            "name": "Buyer 2",
            "uri": "$URI_PREFIX/buyer/2"
        },
        {
            "id": 3,
            "name": "Buyer 3",
            "uri": "$URI_PREFIX/buyer/3"
        },
        {
            "id": 4,
            "name": "Buyer 4",
            "uri": "$URI_PREFIX/buyer/4"
        }
    ],
    "advertisers": [
        {
            "id": 1,
            "name": "Advertiser 1",
            "uri": "$URI_PREFIX/advertiser/1"
        },
        {
            "id": 2,
            "name": "Advertiser 2",
            "uri": "$URI_PREFIX/advertiser/2"
        }
    ]
}

Special Handling for 'ALL' Use Case

For the dsps,buyers and advertisers fields the following handling is done:

 

Request

dsps : [ 0 ] will be considered as ALL dsps
buyers : [ 0 ]  will be considered as ALL buyers
advertisers : [ 0 ] will be considered as ALL advertisers 

 

Response

The dsps/buyers/advertisers field in Response in ALL use case will be shown as:


"dsps": [

{
"id": 0,
"name": null,
"uri": "$URI_PREFIX/advertisingEntity/0"
} ]

"buyers": [
{
"id": 0,
"name": null,
"uri": "$URI_PREFIX/buyer/0"
} ]

"advertisers": [
{
"id": 0,
"name": null,
"uri": "$URI_PREFIX/advertiser/0"
} ]

"advertisers": [

   {

      "id": 0,

      "name": null,

      "uri": "$URI_PREFIX/advertiser/0"

} ]
 

HTTP Response Status Codes

For the list of HTTP status codes, refer to the HTTP Status Codes section.

Error Codes

                                                                                                                                                                                                                                  &