Private Marketplace (PMP) Deal APIs for Demand Partners

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

Introduction

The Private Marketplace (PMP) API specification provides information on how to use these APIs to retrieve details about the various private marketplace settings available in the PubMatic system.

Important:

Note the following points before you start using the API:

  • Data beyond 90 days is not available; so please provide date range only for within the last 90 days.
  • All the data is currently available only in US dollars ($).

PMP API for Demand Partners

The Private Market Place (PMP) API streamlines the process of obtaining PubMatic premium publisher inventory and displaying it in your own system alongside other partners. Follow the API instructions to obtain new and existing deals and update deals with PubMatic publishers.

The API contains the following components:

  1. Retrieving a List of all Offers: This (GET) API retrieves a list of all offers
  2. Creating a Deal: This (POST) API gets a list of newly created deals.
  3. Updating a Deal: This (PUT) API enables you to update the details of a specific deal. Once your update is successful, you'll receive a response with the newly-updated detail.
  4. Retrieving a List of all Deals: This (GET) API retrieves the list of deals based on the filter criteria you include.
  5. Retrieving Details of a Deal: This (GET) API enables you to obtain the details of available deals from the PubMatic publisher inventory.

A deal can be created between a Publisher and a DSP or Buyer. This API allows a user to create and manage deals in the PubMatic system.

PMP API for Publishers documentation can be found here: Private Marketplace (PMP) Deal APIs for Publishers 

  

Methods

Method Path
HTTP Method Type
Description
Link to Definition
/deals
POST
Create a new deal in the PubMatic system
Creating a Deal (for Demand Partners)
/deals/{id}
GET
Retrieve the details of a specific deal
Retrieving Details of a Deal (for Demand Partners)
/deals/
GET
Retrieve the list of deals
Retrieving List of Deal (for Demand Partners)
/deals/{id}
PUT
Update the details of a specific deal
Updating a Deal (for Demand Partners)

Retrieving a List of Offers

Overview

This API allows you to retrieve a list of offers from the PubMatic system depending on the specified filter criteria.

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 MethodGET

Request Headers

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

Parameter NameTypeRequiredValidationsDescription
pageSizeIntegerNo 
Maximum number of rows to be included in the response.
Default value: 100
pageNumberIntegerNo 
Page number to be fetched in case of multiple pages.
Default value: 1
filtersStringNoValues 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.
sortStringNoValues 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.

 

Searchable Fields      

Name

Data Type

Summary

Sample Filter Data

Sample Sort Data

id

Long

Searching and Sorting is supported

?filters=id gtEq 298&filters=id lt 301

For ascending order, use ?sort=id

For descending order, use ?sort=-id

name

String

Searching and Sorting is supported

?filters=name like test

For ascending order, use ?sort=name

For descending order, use ?sort=-name

description

String

Searching and Sorting is supported

?filters=description like test

For ascending order, use ?sort=description

For descending order, use ?sort=-description

tags

String

Searching and Sorting is supported

?filters=tags like test

For ascending order, use ?sort=tags

For descending order,

use ?sort=-tags

publisherIds

Long

For fetching offers belonging to the given  publishers.

(Note : This filter will be available for demand partners only.)

?publisherIds=1234

NA

impressions

Long

Searching and Sorting is supported

?filters=impressions gt 4000

For ascending order,

use ?sort=impressions

For descending order, use ?sort=-impressions

cpm

Double

Searching and Sorting is supported

?filters=cpm lt 4

For ascending order, use ?sort=cpm

For descending order, use ?sort=-cpm

featured

Boolean

Searching and Sorting is supported

For fetching featured offers ,

?filters=featured eq 1

For fetching non featured offers ,

?filters=featured eq 0

For featured offers first, ?sort=-featured

For non-featured offers first,

use ?sort=featured

modificationTime

Timestamp

Sorting is supported

     
 

NA

Most recently modified offers ?sort=-modificationTime

Least recently modified offers :?sort=modificationTime

loggedInOwnerTypeId

Integer

Indicates type of account.
Publisher – 1
Demand partner – 5
Buyer/ATD - 7

&filters=loggedInOwnerId eq 12345

 

loggedInOwnerIdLongAccount ID&filters=loggedInOwnerTypeId eq 1

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.

        

Sample Request

GET $URI_PREFIX/offers/?filters=name like test*

Response

Response Headers                           

Response Header Name

Value

Description

Status Code

200

OK

Content-Type

application/json

Media type that is to be returned in search/sort operation

Date

Fri, 30 May 2014 06:45:05 GMT

 

Server

Apache-Coyote/1.1

 

Transfer-Encoding

chunked

 

Response Body  

Response Body Parameter

Type

Description

metadata

JSON Object 

Metadata about the response generated.

items

JSON Array of Offer object

Records generated as per your request.

Offer                             

Parameter

Type

Description

id

Number

Identifier of offer

name

String

Name of offer

description

String

Description of offer

notes

String

Additional notes regarding the offer

tags

List of String

Keywords / Hashtags associated with the offer

logoPath

String

URL/Path for offer's logo

deleted

Boolean

Indicated whether offer is deleted or not

publisherId

Number

Publisher Id of the offer's owner, if the owner is a publisher

product

Product Object

Product associated with the offer

targeting

Targeting Object

Targeting associated with the offer

timezone

Timezone Object

Timezone which is used to define startDate and endDate of the offer

offerStartDate

ISO Date

Date from which this offer is discoverable.

offerEndDate

ISO Date

Date up to which this offer is discoverable.

transactionStartDate

ISO Date

Date from which this offer can be bought or transacted upon

transactionEndDate

ISO Date

Date up to which this offer can be bought or transacted upon

impressions

Number

Impressions available in this offer

percentageAvails

Number

Percentage of the avails defined by the publisher that will be used in this offer.

cpm

Number

eCPM at which this offer is available

spend

Number

 

minSpend

Number

Minimum spend expected for this offer

currency

Currency Object

Currency used to define the spend.

oneClickBuy

Boolean

Flag to indicate whether this offer is available for one click buy

featured

Boolean

Flag to indicate whether this offer is featured.

channels

List of Channel Objects

Channels for which the offer is created for.

advertisers

List of Advertiser objects

Advertisers to whom this offer is available / discoverable

creationTime

ISO Date

Time at which offer was created.

modificationTime

ISODate

Time at which offer was last modified.

ATD / Buyer

Body Parameters

Type

Description

id

Number

Id of the ATD/Buyer

name

String

Name of the ATD

uri

String

URI to get details of the ATD.


DemandPartner / DSP

Body Parameters

Type

Description

id

Number

Id of the Demand Partner / DSP

name

String

Name of the Demand Partner / DSP

uri

String

URI to get details of the Demand Partner / DSP.

Advertiser 

Body Parameters

Type

Description

id

Number

Id of the Advertiser

name

String

Name of the Advertiser

uri

String

URI to get details of the Advertiser


Channel Type 

Body Parameters

Type

Description

id

Number

Pubmatic id of the channel selected

name

String

The name assigned to the Channel

 

Timezone

Body Parameters

Type

Description

id

Number

Pubmatic id of the timezone selected

name

String

The name of the timezone

 

Product

Body Parameters

Type

Description

id

Number

Pubmatic id of the product listed

name

String

The name assigned to the product

uri

String

URI to fetch any further details required for the product

Targeting                   

Body Parameters

Type

Description

id

Number

Pubmatic id of the targeting listed

name

String

The name assigned to the targeting

uri

String

URI to fetch any further details required for the targeting


Category

Body Parameters

Type

                        Description

id

Number

Pubmatic id of the category / vertical

name

String

The name assigned to the category / vertical

uri

String

URI to fetch any further details required for the category / vertical

 

Sample Response JSON:

{
    "metaData": {
        "startIndex": 1,
        "request": {
            "pageSize": 15,
            "pageNumber": 1,
            "metrics": null,
            "dimensions": null,
            "sort": null,
            "filters": [
                "name like test*"
            ],
            "fromDate": null,
            "toDate": null,
            "useAllDimensions": true
        },
        "totalRecords": 2,
        "endIndex": 2
    },
    "items": [
        {
            "name": "test offer 123",
            "description": "test description",
            "notes": "test notes",
            "tags": "test hashtag, hastag123",
            "id": 100,
            "logoPath": "test logo path",
            "publisherId": 1234,
            "deleted": false,
            "creationTime": "2014-08-30T19:16:58Z",
            "modificationTime": "2014-08-30T19:16:58Z",
    "product": {
    "id": 10,
    "name": "test inventory unit 1",
    "uri": "$URI_PREFIX/products/10",
    "productCategory": [
      {
        "id": 52,
        "name": "Automotive",
        "iabCategoryId": "IAB2"
      },
      {
        "id": 76,
        "name": "Business",
        "iabCategoryId": "IAB3"
      }
    ],
    "platforms": [
      {
        "id": 1,
        "name": "Web"
      },
      {
        "id": 2,
        "name": "Mobile Web"
      },
      {
        "id": 4,
        "name": "Mobile App IOS"
      }
    ],
    "iabEnabled": true
  },
"targeting": {
                "id": 14,
                "name": "test targeting unit 1",
                "uri": "$URI_PREFIX/targeting/14"
            },
            "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"
                },
                {
                    "id": 3,
                    "name": "DSP 3",
                    "uri": "$URI_PREFIX/advertisingEntity/3"
                }
            ],
            "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"
                }
            ]
        },
        {
            "name": "test offer 456",
            "description": "test description",
            "notes": "test notes",
            "tags": "test hashtag, hastag123",
            "id": 200,
            "logoPath": "test logo path for offer 456",
            "publisherId": 1234,
            "deleted": false,
            "creationTime": "2014-08-30T19:16:58Z",
            "modificationTime": "2014-08-30T19:16:58Z",
         

"product": {
    "id": 10,
    "name": "test inventory unit 1",
    "uri": "$URI_PREFIX/products/10",
    "productCategory": [
      {
        "id": 52,
        "name": "Automotive",
        "iabCategoryId": "IAB2"
      },
      {
        "id": 76,
        "name": "Business",
        "iabCategoryId": "IAB3"
      }
    ],
    "platforms": [
      {
        "id": 1,
        "name": "Web"
      },
      {
        "id": 2,
        "name": "Mobile Web"
      },
      {
        "id": 4,
        "name": "Mobile App IOS"
      }
    ],
    "iabEnabled": true
  },


            "targeting": {
                "id": 14,
                "name": "test targeting unit 1",
                "uri": "$URI_PREFIX/targeting/14"
            },
            "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"
                },
                {
                    "id": 3,
                    "name": "DSP 3",
                    "uri": "$URI_PREFIX/advertisingEntity/3"
                }
            ],
            "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, 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 for "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"
} ]

HTTP Response Status Codes

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

 

Error Codes

Error Code

Error Description

PKG_002_0094

Publisher Id filter is not available for this user.

CC03_0007

Multiple associated resources found during search operation. Pass loggedInOwnerId and loggedInOwnerTypeId in query parameters.

Creating a Deal

 

Overview

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

Detailed Description

A deal can be created between a Publisher and a DSP or Buyer. To create a deal, you need to send a HTTP POST call to the URL mentioned below. You need to pass the arguments in the request's body. This topic also lists the parameters which are required and those which are optional. If the deal creation is successful, it will return the newly created deal. Please refer to the error codes section to understand the error messages which are displayed in case of an error.

Request

         
URL
$URI_PREFIX/deals

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

 

For production,$URI_PREFIX should be replaced with "http://api.pubmatic.com/v3/pmp/".
HTTP Method
POST

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

Supported

Validations

Description

dealId

String

No

Yes
  • Characters not allowed are [+|!(){}[]<>#%^\"~*?:;@$]
  • Maximum length is 64 characters
  • In case the dealId is not specified, an autogenerated dealId is used while activating the Deal.
  • Once a deal is in Active / Scheduled state, deal ID cannot be changed.
  • Deal ID must be passed while making any edit on a deal.

name

String

Yes

Yes
  • Maximum length is 256 characters.
  • Name should be unique for a combination of ownerType and ownerId.
  • Characters not allowed are [+|!(){}[]<>#%^\"~*?:;@$]

Name of the deal

additionalInfo

String

No

Yes 

Any additional information to be linked with the deal. All the message-based interactions will be recorded here.

status

Integer

Yes

Yes

Demand Partner can create a deal directly in Active state if offer is a one-click buy.

Publisher can create a deal directly in Active state. InReview state deal creation is not applicable for a Publisher.

Status of the deal. Possible options are:

1 = ACTIVE

2 = INACTIVE

4 = SCHEDULED

5 = COMPLETED

6 = INREVIEWDRAFT

7 = INREVIEWACTIVE

8 = INREVIEWREJECTED

auctionType

Integer

Yes

Yes

Value must be between 1 to 3.

Possible Values:

1 = First Price

2 = Second Price

3 = Fixed Price

Auction type (First Price, Second Price, or Fixed Price) associated with the deal. 

Note: This field is negotiable in case of In-review deals.

channelTypeIntegerYesYes

Possible Values:

PMP = 1

Preferred = 5

PMP-G = 6

Value specifying the channel type of the deal.

offer

Integer

No

Yes
  • Value must be greater than 0.
  • Value must be a valid offer ID.
  • Either 'offer' or 'product' must be provided.

ID of the offer associated with the deal.

Please refer to Offer API details for more information.

startDate

ISO Date in GMT

No

Yes

Value must not be earlier than the current date.

Start date of the deal. This field is optional, in case the start date from the selected offer need not be changed.

endDate

ISO Date in GMT

No

Yes

Value must not be earlier than the start date.

End date of the deal. This field is optional, in case the end date from the selected offer need not be changed.

timeZone

Integer

No

Yes

Value must be between the allowed time zone IDs.

Timezone for start date and end date specified in the deal. Possible options are:

1 = PST

2 = JST

3 = AET

4 = GMT

5 = ACST

6 = AWST

flooreCPM

Float

Yes

Yes

Value must be between 0.01 to 999.99

Minimum eCPM expected for the deal.

minSpendFloatNoYes

Mandatory channelType = PMP-G

Minimum spend for this deal.
impressionAvailsLongNoYesMandatory for channelType = PMP-GAvailable impressions for this deal.

advertiserWhiteListing

Boolean

No

Yes

Default Value = False

Indicates whether advertiser whitelisting is enabled for the deal or not.

advertisers

Array of Integers

No

Yes

Value must be valid advertiser IDs and should be mapped to selected advertiser categories id selected.

List of advertisers for which the deal should be whitelisted.

advertiserCategories

Array of Integers

No

Yes

Value must be valid advertiser category IDs (PubMatic or IAB)

List of advertiser categories for which the deal should be whitelisted.

advertiserIABCategories

Array of strings

No

Yes

Value must be valid IAB advertiser category IDs

List of IAB advertiser categories for which the deal should be whitelisted.

advertiserDomains

Array of Integers

No

Yes

Value must be valid advertiser domains and should mapped to the selected advertiser categories and advertisers if selected.

List of advertiser domains for which the deal should be whitelisted.

dealDspBuyerMappingsArray of JSON objectsYesYes

Must be valid DSP and Buyer Ids.

Publishers and DSPs can send these mappings.

List of DSP-Buyer map for this deal.

This is a mandatory field.

buyers

Array of Integers

No

Yes

Value must be valid buyer IDs.

Publishers and DSPs can send these.

List of ATDs associated with the deal.

This field is mandatory when the deal is created in the Active/Scheduled state.

buyerEmails

Array of Buyer Emails with mapped owner ID

No

Yes

Publishers and DSPs can send these.

List of buyer email addresses that should be notified  while  creating deal / deal In-review/ accepting deal In-review

dsps

Array of Integers

No

Yes

Value must be valid DSP IDs.

List of DSPs associated with the deal. This field is mandatory when the deal is created in the Active/Scheduled state.

dspEmails

Array of DSP Emails with mapped owner ID

No

Yes

Publishers and ATDs can send these.

List of DSP email addresses that should be notified while creating deal / deal In-review / Accepting deal In-review

pubEmailsArray of Publisher Emails with mapped owner IDNoYesOnly DSP/Buyer can send theseList of publisher emails that should be notified while creating deal/deal in review/accepting deal in review.

additionalEmails

List of Strings

No

Yes

 

Any additional emails that should be notified  while creating deal / deal In-review / accepting deal In-review

decisionManagerEnabledBooleanNoYes

Default Value = False

Value can be set only if appropriate property is set for publisher.

Field to indicate if Unified Optimization is enabled.
publisherCategoryIdIntegerNoYes Used for PMRG consortium

revShare
DoubleNoYes Used for PMRG consortium
loggedInOwnerIdLongYesYesShould be a valid Publisher ID, DSP ID, or Buyer IDIndicates account ID
loggedInOwnerTypeIdLongNoYes

Possible values are:

 

Type of AccountValue
Publisher1
Demand Partner5
ATD/Buyer7
Indicates the type of account of the user invoking this API.

Important Notes for Creating a Deal

  • Please refer to Deal Status Explanation and Restrictions/Workflow to learn more about various states that a deal may enter
  • If a buyer is creating a deal 'In-Review', he need not mention the DSP. But when the deal 'In Reivew' is accepted, then it is a mandatory field.
  • Currently the system sends e-mails only for following two events:
    • When a deal is created
    • When an "In-Review" deal is accepted
  • We now have support for IAB advertiser categories. Following are some important points around the same: 
    • Publisher can be enabled or disabled for the IAB setting. If a publisher is IAB enabled, then the advertiser category ids sent in the request JSON should be IAB category ids only (See "advertiserCategories" in sample request json below). If publisher is NOT IAB enabled, then the advertiser category ids sent in the request JSON should be PubMatic advertiser categories only.

      In the API response as well. advertiser categories shown will be either IAB or PubMatic categories depending on publisher setting.
    • The PubMatic Media Console is moving entirely to IAB, therefore, advertiser categories in all deal API requests and responses should be IAB category Ids only.
    • Differences between IAB and PubMatic category response: 
      - When IAB categories are shown, "uri" value is : "http://$ {URI_PREFIX}/common/iabCategories/${IAB_category_id}".
      - When PubMatic categories are shown, "uri" value is : "http://${URI_PREFIX}/common/advertiserCategory/${PubMatic_category_id}"
      - When PubMatic categories are shown, "iabDetails" object will always be null

Sample Request JSON for Demand Partners

 

{
  "dealId": "ABCD1234",
  "name": "SampleRequestDeal",
  "additionalInfo": "I would like to buy this deal for $0.3",
  "status": 1,
  "auctionType": 1,
  "impressionAvails": 10000,
  "minSpend": 500,
  "offer": 122323,
  "startDate": "2017-07-31T18:06:36Z",
  "endDate": "2017-08-02T06:59:59.000Z",
  "timeZone": 1,
  "flooreCPM": 2.23,
  "advertisers": [
    1,
    2,
    3
  ],
  "advertiserIABCategories": [
    "IAB1"
  ],
  "advertiserDomains": [
    1,
    2,
    3
  ],
  "pubEmails": [
    {
      "ownerId": "1",
      "userEmails": [
        "test_abc@pqr.com",
        "test_xyz@pqr.com"
      ]
    }
  ],
  "additionalEmails": [
    "test1@pubmatic.com"
  ],
  "channelType": 1,
  "advertiserWhiteListing": true,
  "dealDspBuyerMappings": [
    {
      "dspId": null,
      "buyerId": 1,
      "seatId": null
    },
    {
      "dspId": null,
      "buyerId": 2,
      "seatId": null
    }
  ],
  "loggedInOwnerId": 12345,
  "loggedInOwnerTypeId": 5
}

 

Response

 

Response Body 

{
  "items": [
    {
      "id": 123456,
      "dealId": "ABCD1234",
      "name": "SampleRequestDeal",
      "uri": "$URI_PREFIX/deals/123456",
      "additionalInfo": "I would like to buy this deal for $0.3",
      "status": {
        "id": 2,
        "name": "In Review"
      },
      "auctionType": {
        "id": 1,
        "name": "FIRST PRICE"
      },
     "channelType": {

        "id": 1,
        "name": "PMP"
     },
      "minSpend": 500,
      "impressionAvails": 10000,
      "offer": {
        "id": 122323,
        "name": "Test Package 1",
        "uri": "${URL_PREFIX}/offer/122323"
      },
      "product": {
        "id": 123,
        "name": "Test product 1",
        "uri": "${URL_PREFIX}/products/123"
      },
      "targeting": {
        "id": 123,
        "name": "Test targeting 1",
        "uri": "${URL_PREFIX}/targeting/123"
      },
      "startDate": "2014-09-03T12: 12: 12.000",
      "endDate": "2013-09-08T12: 12: 12.000",
      "timeZone": 1,
      "flooreCPM": 2.23,
      "advertisers": [
        {
          "id": 1,
          "name": "Advertiser 1",
          "uri": "${URI_PREFIX}/advertiser/1"
        }
      ],
      "advertiserCategories": [
        {
          "id": 44,
          "name": "Arts & Entertainment",
          "uri": "http://${URI_PREFIX}/common/iabCategories/IAB1",
          "iabDetails": {
            "iabName": "Arts & Entertainment",
            "iabId": "IAB1",
            "id": 44,
            "parentCategory": null,
            "parentIabCatId": null,
            "subCategoryList": [
              {
                "iabName": "Books & Literature",
                "iabId": "IAB1-1",
                "id": 45,
                "parentCategory": null,
                "parentIabCatId": "IAB1",
                "subCategoryList": null,
                "pubmaticAdvertiserCategoryId": 8,
                "name": "Books & Literature"
              }
            ],
            "pubmaticAdvertiserCategoryId": 8,
            "name": "Arts & Entertainment"
          }
        },
        {
          "id": 279,
          "name": "Sports",
          "uri": "http://${URI_PREFIX}/common/iabCategories/IAB17",
          "iabDetails": {
            "iabName": "Sports",
            "iabId": "IAB17",
            "id": 279,
            "parentCategory": null,
            "parentIabCatId": null,
            "subCategoryList": null,
            "pubmaticAdvertiserCategoryId": 19,
            "name": "Sports"
          }
        }
      ],
      "advertiserDomains": [
        {
          "id": 1,
          "name": "test.domain",
          "uri": "http://${URI_PREFIX}/common/advertiserDomain/1"
        }
      ],
      "buyers": [
        {
          "id": 1,
          "name": "Buyer 1",
          "uri": "$URI_PREFIX/buyer/1"
        }
      ],
      "buyerEmails": [
        "test@buyer.com"
      ],
      "dsps": [
        {
          "id": 1,
          "name": "DSP 1",
          "uri": "$URI_PREFIX/advertisingEntity/1"
        },
        {
          "id": 2,
          "name": "DSP 2",
          "uri": "$URI_PREFIX/advertisingEntity/2"
        }
      ],
      "dspEmails": [
        "test@dsp.com"
      ],
      "publisher": [
        {
          "id": 1,
          "name": "Publisher 1",
          "uri": "$URI_PREFIX/publisher/1"
        }
      ],
      "pubEmails": [
        "test@publisher.com"
      ],
      "additionalEmails": [
        "test1@pubmatic.com"
      ],
      "advertiserWhiteListing": true
    }
  ]
}

Sample Response JSON for Demand Partners


Error Codes

Sample error response


[
    {
        "errorCode": "DEAL_001_0010",
        "errorMessage": "Invalid value for field XYZ"
    },
    {
        "errorCode": "DEAL_001_0012",
        "errorMessage": "Invalid value for field ABC"
    }
]

 

Updating a Deal (for Demand Partners)

Overview

This API allows you to update the details of a specific deal.

Detailed Description

A deal can be created between a Publisher and a DSP or Buyer. To edit a deal, you need to send a HTTP PUT call to the URL mentioned below. You need to pass a definitive set of arguments in the request's body. This topic also lists the parameters which are required and those which are optional. If the deal update is successful, it will return the newly-updated deal. Please refer to the error codes section to understand the error messages which are displayed in case of an error.

Request Type

         
URL
$URI_PREFIX/deals


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

For production,$URI_PREFIX should be replaced with "http://api.pubmatic.com/v3/pmp/".
HTTP Method
PUT

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.

Path Parameters         

Parameter NameTypeRequiredDescription
idIntegerYesID of the deal to be edited

Request Body

Body ParameterTypeRequiredSupportedValidationsDescription
dealIdStringNoYes
  • Characters not allowed are [+|!(){}[]<>#%^\"~*?:;@$]
  • Maximum length is 64 characters
  • ID of the deal to be created. In case, the deal ID is not specified, an auto-generated deal ID is used while activating a deal.
  • Once a deal is in Active / Scheduled state, deal ID cannot be changed.
  • Deal ID should be passed while editing a deal.
nameStringYesYes
  • Maximum length is 256 characters.
  • Name should be unique for a combination of ownerType and ownerId.
  • Characters not allowed are [+|!(){}[]<>#%^\"~*?:;@$]
Name of the deal
additionalInfoStringNoYes Any additional information to be linked with the deal. All the message-based interactions will be recorded here.
statusIntegerYesYes
  • Demand Parter can edit a deal only for INREVIEW status.
Status of the deal. Possible options are:
1 = ACTIVE
2 = INACTIVE
4 = SCHEDULED
5 = COMPLETED
6 = INREVIEWDRAFT
7 = INREVIEWACTIVE
8 = INREVIEWREJECTED
priorityIntegerNoYes
  • Value must be in the following interval: 0<= priority <= 100.
  • Displays for Publishers only.
Priority of the deal. The lower the number, the higher the priority.
This field is visible only to publishers.
auctionTypeIntegerYesYes
  • Value must be between 1 to 3
Auction type associated with the deal. Possible options are:
1 = First Price
2 = Second Price
3 = Fixed Price
offerIntegerNoYes
  • Offer must be passed as selected at the time of deal creation.
  • Value must be greater than 0.
  • Value must be a valid offer ID.
ID of the offer associated with the deal. Refer to Offer API for more information.
productIntegerYesYes
  • Value must be greater than 0.
  • Value must be a valid product ID.
Changed productId. Refer to Product API for more information.

targeting
IntegerNoYes
  • Value must be greater than 0.
  • Value must be a valid targeting ID.
Changed targeting Id. Refer to Targeting API for more information.
startDateISO Date in GMTYesYes
  • Once a deal has started, startDate cannot be modified.
Changed start date of the deal. 
endDateISO Date in GMTNoYes
  • Value must not be earlier than the start date.
Changed end date of the deal. This date can be extended even if the deal is completed.
timezoneIntegerYesYes
  • Value must be between the allowed time zone IDs.
Time zone for start date and end date specified in the deal. Possible options are:
1 = PST
2 = JST
3 = AET
4 = GMT
5 = ACST
6 = AWST
flooreCPMFloatYesYes
  • Value must be between 0.01 to 999.99
Minimum eCPM expected for the deal.
minSpendFloatNoYes
  • Mandatory for channelType = PMP-G
Minimum spend for this deal.
impressionAvailsLongNoYes
  • Mandatory for channelType = PMP-G
Available impressions for this deal.
advertiserWhiteListingBooleanNoYes 
Indicates whether advertiser whitelisting is enabled for the deal or not.
Default value: False
advertisersArray of IntegersNoYes
  • Value must be valid advertiser ID and should be mapped to selected advertiser categories.
List of advertisers for which the deal should be whitelisted.
advertiserCategoriesArray of IntegersNoYes
  • Value must be valid advertiser category ID
List of advertiser categories for which the deal should be whitelisted.
advertiserIABCategoriesArray of StringsNoYes
  • Value must be valid IAB advertiser category ID
List of advertiser IAB categories for which the deal should be whitelisted.
advertiserDomainsArray of IntegersNoYes
  • Value must be valid advertiser domains and should mapped to the selected advertiser categories and advertisers.
List of advertiser domains for which the deal should be whitelisted.
dealDspBuyerMappingsArray of JSON objectsYesYes
  • Must be valid DSP and Buyer IDs
  • Both Publishers and DSPs can send these
List of DSP-Buyer Mappings for this deal.
buyersArray of IntegersNoYes
  • Value must be valid buyer IDs
  • Cannot be modified once the deal starts.
List of ATDs associated with the deal, which is only viewable to Publishers.
This cannot be modified once the deal has started.
buyerEmailsArray of Buyer Emails with mapped owner IDNoYes List of buyer email addresses that should be notified while creating an INREVIEW or ACTIVE deal and accepting the INREVIEW deal.
dspsArray of IntegersNoYes
  • Value must be valid DSP IDs.
List of DSPs associated with the deal, which is viewable for Publishers and ATDs only.
dspEmailsArray of DSP Emails with mapped owner IDNoYes List of DSP email addresses that should be notified while creating an INREVIEW or ACTIVE deal and accepting the INREVIEW deal.
pubEmailsArray of Publisher Emails with mapped with owner IDNoYes List of publisher emails that should be notified while creating an INREVIEW or ACTIVE deal and accepting the INREVIEW deal.
additionalEmailsList of StringsNoYes Any additional emails that should be notified while creating an INREVIEW or ACTIVE deal and accepting the INREVIEW deal.

publisherCategoryId
IntegerNoYes Used for PMRG consortium
revShareDoubleNoYes Used for PMRG consortium
loggedInOwnerIdLongYesYes

Should be a valid Publisher ID, DSP ID or Buyer ID

Indicates account ID
loggedInOwnerTypeIdIntegerYesYes

Possible values are:

Type of accountValue
Publisher1
Demand Partner5
ATD/Buyer7
Indicates the type of account of the user invoking this API.

Important Notes for Editing a Deal

  • Please refer to Deal Status Explanation and Restrictions/Workflow to learn more about various states that a deal may enter
  • If a buyer is creating a deal 'In-Review', he need not mention the DSP. But when the deal 'In Reivew' is accepted, then it is a mandatory field.
  • Currently the system sends e-mails only for following two events:
    • When a deal is created
    • When an "In-Review" deal is accepted
  • We now have support for IAB advertiser categories. Following are some important points around the same: 
    • Publisher can be enabled or disabled for the IAB setting. If a publisher is IAB enabled, then the advertiser category ids sent in the request JSON should be IAB category ids only (See "advertiserCategories" in sample request json below). If publisher is NOT IAB enabled, then the advertiser category ids sent in the request JSON should be PubMatic advertiser categories only.

      In the API response as well. advertiser categories shown will be either IAB or PubMatic categories depending on publisher setting.
    • The PubMatic Media Console is moving entirely to IAB, therefore, advertiser categories in all deal API requests and responses should be IAB category Ids only.
    • Differences between IAB and PubMatic category response: 
      - When IAB categories are shown, "uri" value is : "http://$ {URI_PREFIX}/common/iabCategories/${IAB_category_id}".
      - When PubMatic categories are shown, "uri" value is : "http://${URI_PREFIX}/common/advertiserCategory/${PubMatic_category_id}"
      - When PubMatic categories are shown, "iabDetails" object will always be null

Sample Request JSON for Demand Partners

 

{
  "dealId": "ABCD1234",
  "name": "SampleRequestDeal",
  "additionalInfo": "I would like to buy this deal for $0.3",   "status": 7,   "auctionType": 1,   "channelType": 6,   "impressionAvails": 10000,   "minSpend": 500,   "offer": 122323,   "startDate": "2017-08-02T07:00:00.000Z",
  "endDate": "2033-01-01T07:59:59.000Z",
  "timeZone": 1,
  "flooreCPM": 2.23,
  "advertisers": [
    1,
    2,
    3
  ],
  "advertiserIABCategories": [
    "IAB1",
    "IAB2"
  ],
  "advertiserDomains": [
    1,
    2,
    3
  ],
  "pubEmails": [
    {
      "ownerId": "1",
      "userEmails": [
        "test_abc@pqr.com",
        "test_xyz@pqr.com"
      ]
    }
  ],
  "additionalEmails": [
    "test1@pubmatic.com"
  ],
  "advertiserWhiteListing": true,
  "products": [3452],
  "targeting": 284,
  "dealDspBuyerMappings": [
    {
      "dspId": null,
      "buyerId": 1,
      "seatId": null
    },
    {
      "dspId": null,
      "buyerId": 2,
      "seatId": null
    }
  ],
  "loggedInOwnerId": 12345,
  "loggedInOwnerTypeId": 5
}

Response

Response Body

Sample Response JSON for Demand Partner

{
  "id": 123456,
  "dealId": "ABCD1234",
  "name": "SampleRequestDeal",
  "additionalInfo": "I would like to buy this deal for $0.3",
  "status": {
    "id": 2,
    "name": "In Review"
  },
  "auctionType": {
    "id": 1,
    "name": "FIRST PRICE"
  },

"minSpend": 500,
"impressionAvails": 10000,
"channelType": {
"id": 1,
"name": "PMP"
},

  "offer": {
    "id": 122323,
    "name": "Test Package 1",
    "url": "${URL_PREFIX}/offer/122323"
  },
  "product": {
    "id": 123,
    "name": "Test product 1",
    "uri": "${URL_PREFIX}/products/123"
  },
  "targeting": {
    "id": 123,
    "name": "Test targeting 1",
    "uri": "${URL_PREFIX}/targeting/123"
  },
  "startDate": "2014-09-03T12: 12: 12.000",
  "endDate": "2013-09-08T12: 12: 12.000",
  "timeZone": 1,
  "flooreCPM": 2.23,
  "advertisers": [
    {
      "id": 1,
      "name": "Advertiser 1",
      "uri": "${URI_PREFIX}/advertiser/1"
    }
  ],
  "advertiserCategories": [
    {
      "id": 44,
      "name": "Arts & Entertainment",
      "uri": "http://${URI_PREFIX}/common/iabCategories/IAB1",
      "iabDetails": {
        "iabName": "Arts & Entertainment",
        "iabId": "IAB1",
        "id": 44,
        "parentCategory": null,
        "parentIabCatId": null,
        "subCategoryList": [
          {
            "iabName": "Books & Literature",
            "iabId": "IAB1-1",
            "id": 45,
            "parentCategory": null,
            "parentIabCatId": "IAB1",
            "subCategoryList": null,
            "pubmaticAdvertiserCategoryId": 8,
            "name": "Books & Literature"
          }
        ],
        "pubmaticAdvertiserCategoryId": 8,
        "name": "Arts & Entertainment"
      }
    },
    {
      "id": 279,
      "name": "Sports",
      "uri": "http://${URI_PREFIX}/common/iabCategories/IAB17",
      "iabDetails": {
        "iabName": "Sports",
        "iabId": "IAB17",
        "id": 279,
        "parentCategory": null,
        "parentIabCatId": null,
        "subCategoryList": null,
        "pubmaticAdvertiserCategoryId": 19,
        "name": "Sports"
      }
    }
  ],
  "advertiserDomains": [
    {
      "id": 1,
      "name": "test.domain",
      "uri": "http://${URI_PREFIX}/common/advertiserDomain/1"
    }
  ],
  "buyers": [
    {
      "id": 1,
      "name": "Buyer 1",
      "uri": "$URI_PREFIX/buyer/1"
    }
  ],
  "buyerEmails": [
    "test@buyer.com"
  ],
  "publisher": [
    {
      "id": 1,
      "name": "Publisher 1",
      "uri": "$URI_PREFIX/publisher/1"
    }
  ],
  "pubEmails": [
    "test@publisher.com"
  ],
  "additionalEmails": [
    "test1@pubmatic.com"
  ],
  "advertiserWhiteListing": true
}

Error Codes

Sample error response

 

[
    {
        "errorCode": "DEAL_001_0010",
        "errorMessage": "Invalid value for field XYZ"
    },
    {
        "errorCode": "DEAL_001_0012",
        "errorMessage": "Invalid value for field ABC"
    }
]

 

Retrieving List of Deals (for Demand Partners)

Overview

This API allows you to retrieve the list of deals by specifying the various filter criteria.

Request

         
URI
${URI_PREFIX}/deals/


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

For production,$URI_PREFIX should be replaced with "http://api.pubmatic.com/v3/pmp/".
HTTP Method
GET

Request Headers                 

Header Name
Type
Value
Required
Description
Authorization
String
Bearer ${access_token}
Yes

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

 

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

Request Query Search-Specific Parameters                                             

Parameter Name

Type

Required

Validations

Description

fromDateDateNo This is used for a reporting call. If you need to search startDate/endDate, use the Filters parameter instead.

pageSize

Integer

No

 

Maximum number of rows to be included in the response.

Default value: 25

pageNumber

Integer

No

 

pateNumber to be fetched in case of multiple pages.

Default value: 1

filters

String

No

Values must be from those mentioned below in the Searchable Fields 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 list of supported dimensions.

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.

Searchable Fields                                                                                       

Name

Data Type

Summary

Sample Filter Data

Sample Sort Data

id

Long

SEARCH and SORT is supported.

Plain SEARCH is depreciated as we have a separate endpoint for it.

?filters=id gtEq 298&filters=id lt 301

For ascending order, use ?sort=id

For descending order, use ?
sort=--id

dealIdString To be supported at a future date. 

name

String

SEARCH and SORT is allowed in this field. 

?filters=name like test

For ascending order, use ?sort=name

For descending order, use ?sort=-name

additionalInfo

String

Search deal by its message component.

SORT is depreciated for this field.

?filters=additionalInfo like test

 

statusInteger To be supported at a future date. 

auctionType

Integer

SEARCH and SORT is allowed in this field. 

?filters=auctionType eq 1

For ascending order, use ?sort=auctionType

For descending order, use ?
sort=
-auctionType

startDate

Date

SEARCH and SORT supported. BETWEEN attribute is not currently supported. But you can use filters like

?filters=startDate gtEq 2014-06-12T17:00:00Z&filters=startDate lt 2014-06-16T17:00:00Z.

?filters=startDate gtEq 2014-06-12T17:00:00Z&filters=startDate lt 2014-06-16T17:00:00Z.

?sort=-startDate

endDate

Date

SEARCH and SORT supported.

?filters=endDate gtEq 2014-06-12T17:00:00Z&filters=endDate lt 2014-06-16T17:00:00Z.

 

buyersArray of LongDeals can be searched by involved DSPs. Format to specify AND or OR for the ids to be updated.
To be supported at a future date.
 
dspsArray of LongDeals can be searched by involved DSPs. Format to specify AND or OR for the ids to be updated.
To be supported at a future date.
 
publishersLongDeals can be searched by publisher. Only DSPs and buyers can search using publishers.To be supported at a future date. 

 

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

     

Important Notes for Modifying a Deal

  • Please refer to Deal Status Explanation and Restrictions/Workflow to learn more about various states that a deal may enter
  • If a buyer is creating a deal 'In-Review', he need not mention the DSP. But when the deal 'In Reivew' is accepted, then it is a mandatory field.
  • Currently the system sends e-mails only for following two events:
    • When a deal is created
    • When an "In-Review" deal is accepted
  • We now have support for IAB advertiser categories. Following are some important points around the same: 
    • Publisher can be enabled or disabled for the IAB setting. If a publisher is IAB enabled, then the advertiser category ids sent in the request JSON should be IAB category ids only (See "advertiserCategories" in sample request json below). If publisher is NOT IAB enabled, then the advertiser category ids sent in the request JSON should be PubMatic advertiser categories only.

      In the API response as well. advertiser categories shown will be either IAB or PubMatic categories depending on publisher setting.
    • The PubMatic Media Console is moving entirely to IAB, therefore, advertiser categories in all deal API requests and responses should be IAB category Ids only.
    • Differences between IAB and PubMatic category response: 
      - When IAB categories are shown, "uri" value is : "http://$ {URI_PREFIX}/common/iabCategories/${IAB_category_id}".
      - When PubMatic categories are shown, "uri" value is : "http://${URI_PREFIX}/common/advertiserCategory/${PubMatic_category_id}"
      - When PubMatic categories are shown, "iabDetails" object will always be null

Response

Response Body

                  
Response Body ParameterTypeDescription
metaDataJSON Object Meta data about the response generated.
itemsJSON Array of Deal objectsRecords generated as per your request.

Sample Search Request 

http://${URI_PREFIX}/deals/?filters=name like SampleRequestDeal*

 

http://${URI_PREFIX}/deals?&filters=loggedInOwnerTypeId eq 1&filters=loggedInOwnerId eq 12345&pageSize=10

Sample Response JSON

{
"startIndex": 1,
"metaData": {
"request": {
"pageSize": 15,
"pageNumber": 1,
"metrics": null,
"dimensions": null,
"sort": null,
"filters": [
"name like SampleRequestDeal"
],
"fromDate": null,
"toDate": null,
"useAllDimensions": true
},
"totalRecords": 1,
"endIndex": 1
},
"items": [
{
"id": 123456,
"dealId": "ABCD1234",
"name": "SampleRequestDeal",
"additionalInfo": "I would like to buy this deal for $0.3",
"status": {
"id": 2,
"name": "In Review"
},
"auctionType": {
"id": 1,
"name": "FIRST PRICE"
},
"minSpend": 500,
"impressionAvails": 10000,
"channelType": {
"id": 1,
"name": "PMP"
},
"offer": {
"id": 122323,
"name": "Test Package 1",
"url": "${URL_PREFIX}/offer/122323"
},
"product": {
"id": 123,
"name": "Test product 1",
"uri": "${URL_PREFIX}/products/123"
},
"targeting": {
"id": 123,
"name": "Test targeting 1",
"uri": "${URL_PREFIX}/targeting/123"
},
"startDate": "2014-09-03T12: 12: 12.000",
"endDate": "2013-09-08T12: 12: 12.000",
"timeZone": 1,
"flooreCPM": 2.23,
"advertisers": [
{
"id": 1,
"name": "Advertiser 1",
"uri": "${URI_PREFIX}/advertiser/1"
}
],
"advertiserCategories": [
{
"id": 44,
"name": "Arts & Entertainment",
"uri": "http://${URI_PREFIX}/common/iabCategories/IAB1",
"iabDetails": {
"iabName": "Arts & Entertainment",
"iabId": "IAB1",
"id": 44,
"parentCategory": null,
"parentIabCatId": null,
"subCategoryList": [
{
"iabName": "Books & Literature",
"iabId": "IAB1-1",
"id": 45,
"parentCategory": null,
"parentIabCatId": "IAB1",
"subCategoryList": null,
"pubmaticAdvertiserCategoryId": 8,
"name": "Books & Literature"
}
],
"pubmaticAdvertiserCategoryId": 8,
"name": "Arts & Entertainment"
}
},
{
"id": 279,
"name": "Sports",
"uri": "http://${URI_PREFIX}/common/iabCategories/IAB17",
"iabDetails": {
"iabName": "Sports",
"iabId": "IAB17",
"id": 279,
"parentCategory": null,
"parentIabCatId": null,
"subCategoryList": null,
"pubmaticAdvertiserCategoryId": 19,
"name": "Sports"
}
}
],
"advertiserDomains": [
{
"id": 1,
"name": "test.domain",
"uri": "http://${URI_PREFIX}/common/advertiserDomain/1"
}
],
"buyers": [
{
"id": 1,
"name": "Buyer 1",
"uri": "$URI_PREFIX/buyer/1"
}
],
"buyerEmails": [
{
"ownerId": 1,
"userEmails": [
"test_testatd@yahoo.in"
]
}
],
"dsps": [
{
"id": 1,
"name": "DSP 1",
"uri": "$URI_PREFIX/advertisingEntity/1"
},
{
"id": 2,
"name": "DSP 2",
"uri": "$URI_PREFIX/advertisingEntity/2"
}
],
"dspEmails": [
{
"ownerId": 1,
"userEmails": [
"test_testdemandpartner@gmail.com"
]
},
{
"ownerId": 2,
"userEmails": [
"test_testdemandpartner2@gmail.com"
]
}
],
"publisher": [
{
"id": 1,
"name": "Publisher 1",
"uri": "$URI_PREFIX/publisher/1"
}
],
"pubEmails": [
{
"ownerId": 1,
"userEmails": [
"test_testdemandpartner@gmail.com"
]
}
],
"additionalEmails": [
"test1@pubmatic.com"
],
"advertiserWhitelisting": true,
"messages": []
}
]
}

Error Codes

Sample error response

 

[
    {
        "errorCode": "DEAL_001_0010",
        "errorMessage": "Error fetching deal XYZ"
    }
]

 

Retrieving Details of a Deal (for Demand Partners)

 

Overview

This API allows you to retrieve the details of a specific deal.

Request

         
URI
$URI_PREFIX/deals/{id}

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

 

For production,$URI_PREFIX should be replaced with "http://api.pubmatic.com/v3/pmp/".
HTTP Method
GET

Request Headers

                 

Header Name
Type
Value
Required
Description
Authorization
String
Bearer ${access_token}
Yes

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

 

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

Path Parameters

               
Parameter Name
Type
Required
Description
id
Integer
Yes
ID of the deal to be fetched

Query Parameters

Parameter Name
Type
Required
Description
loggedInOwnerTypeId
Integer
Yes

Indicates the type of account of the user invoking this API. Possible values are:

 

Type of AccountValue
Publisher1
Demand Partner5
ATD/Buyer7
loggedInOwnerId
Long
Yes

Indicates account ID

 

Sample Request


http://${URI_PREFIX}/deals/123?&filters=loggedInOwnerTypeId eq 1&filters=loggedInOwnerId eq 12345

Response

Response Body

                                                                                                                                                                   

Response Body ParameterTypeDescription
idLongID of the deal.
dealIdStringPublisher-specific Deal.
nameStringName of the deal.
additionalInfoStringAll the message-based interactions recorded for the deal.
statusJSON Element
Status of the deal. This field is depicted in a key-value pair. Possible options are:

1 = ACTIVE

2 = INACTIVE

4 = SCHEDULED

5 = COMPLETED

6 = INREVIEWDRAFT

7 = INREVIEWACTIVE

8 = INREVIEWREJECTED

auctionTypeJSON Element
Auction type associated with the deal. This field is depicted in a key-value pair.
 
Possible options:

1 - First Price

2 - Second Price

3 - Fixed Price

 
channelTypeJSON Element

Value specifying the channel type of the deal.

PMP = 1

Preferred = 5

PMP-G = 6

offerJSON ElementID, Name and URL for the base offer associated with the deal. Refer to the Offer API for more information.
productJSON ElementID, Name and URL for the product associated with the deal. Refer to the Product API for more information.
targetingJSON ElementID, Name and URL for the targeting unit associated with the deal. Refer to the Targeting API for more information.
startDateISO Date in GMTStart date of the deal.
endDateISO Date in GMTEnd date of the deal.
timezoneJSON ElementTime zone associated with the start and end dates of the deal. This field is depicted in a key-value pair.
flooreCPMFloatMinimum eCPM expected for the deal.
minSpendFloatMinimum spend for this deal.
impressionAvailsLongAvailable impressions for this deal.
advertiserWhiteListingBooleanIndicates whether advertiser whitelisting is enabled for the deal.
advertisersList of AdvertisersList of advertisers for which the deal is whitelisted. 
advertiserCategoriesList of Advertiser CategoriesList of advertiser categories (Id, Name and URL) for which the deal is whitelisted.
advertiserIABCategoriesList of Advertiser IAB CategoriesList of Advertiser IAB categories (Id, Name, URL) for advertiser categories for which this deal should be whitelisted.
advertiserDomainsList of Advertiser DomainsList of advertiser domains for which the deal is whitelisted.
buyersList of BuyersList of ATDs associated with the deal. 
buyerEmailsList of Buyer EmailsList of ATD email addresses that should be notified on the deal's state changes. Publishers and DSPs can see these emails. 
dspsList of DSPsList of DSPs associated with the deal.
dspEmailsList of DSP EmailsList of DSP email addresses that should be notified on the deal's state changes.Publishers and ATDs can see these emails.
publisherPublisherPublisher for this deal.

pubEmails
List of Publisher EmailsEmail Ids of Publisher to notify on deal stat changes.
additionalEmailsList of EmailsAny additional email addresses to be notified on the deal state changes.
lastNegotiatedBy
 
Integer
Indicates the name of the entity by which the deal was last negotiated. Possible options are:

1 = Publisher

= DSP

= ATD

activityLogDetailsJson Element   Indicate the negotiation history of the deal.
modificationTimeISO Date in GMT    Indicate last modification time of the deal.

Important Notes:

  • Please refer to Deal Status Explanation and Restrictions/Workflow to learn more about various states that a deal may enter
  • If a buyer is creating a deal 'In-Review', he need not mention the DSP. But when the deal 'In Reivew' is accepted, then it is a mandatory field.
  • Currently the system sends e-mails only for following two events:
    • When a deal is created
    • When an "In-Review" deal is accepted
  • We now have support for IAB advertiser categories. Following are some important points around the same: 
    • Publisher can be enabled or disabled for the IAB setting. If a publisher is IAB enabled, then the advertiser category ids sent in the request JSON should be IAB category ids only (See "advertiserCategories" in sample request json below). If publisher is NOT IAB enabled, then the advertiser category ids sent in the request JSON should be PubMatic advertiser categories only.

      In the API response as well. advertiser categories shown will be either IAB or PubMatic categories depending on publisher setting.
    • The PubMatic Media Console is moving entirely to IAB, therefore, advertiser categories in all deal API requests and responses should be IAB category Ids only.
    • Differences between IAB and PubMatic category response: 
      - When IAB categories are shown, "uri" value is : "http://$ {URI_PREFIX}/common/iabCategories/${IAB_category_id}".
      - When PubMatic categories are shown, "uri" value is : "http://${URI_PREFIX}/common/advertiserCategory/${PubMatic_category_id}"
      - When PubMatic categories are shown, "iabDetails" object will always be null

Sample Response JSON

 

{
  "id": 123456,
  "dealId": "ABCD1234",
  "name": "SampleRequestDeal",
  "additionalInfo": "I would like to buy this deal for $0.3",
  "status": {
    "id": 2,
    "name": "In Review"
  },
  "auctionType": {
    "id": 1,
    "name": "FIRST PRICE"
  },
"minSpend": 500,
"impressionAvails": 10000,
  "offer": {
    "id": 122323,
    "name": "Test Package 1",
    "url": "${URL_PREFIX}/offer/122323"
  },
  "product": {
    "id": 123,
    "name": "Test product 1",
    "uri": "${URL_PREFIX}/products/123"
  },
  "targeting": {
    "id": 123,
    "name": "Test targeting 1",
    "uri": "${URL_PREFIX}/targeting/123"
  },
  "startDate": "2014-09-03T12: 12: 12.000",
  "endDate": "2013-09-08T12: 12: 12.000",
  "timeZone": 1,
  "flooreCPM": 2.23,
  "advertisers": [
    {
      "id": 1,
      "name": "Advertiser 1",
      "uri": "${URI_PREFIX}/advertiser/1"
    }
  ],
  "advertiserCategories": [
    {
      "id": 44,
      "name": "Arts & Entertainment",
      "uri": "http://${URI_PREFIX}/common/iabCategories/IAB1",
      "iabDetails": {
        "iabName": "Arts & Entertainment",
        "iabId": "IAB1",
        "id": 44,
        "parentCategory": null,
        "parentIabCatId": null,
        "subCategoryList": [
          {
            "iabName": "Books & Literature",
            "iabId": "IAB1-1",
            "id": 45,
            "parentCategory": null,
            "parentIabCatId": "IAB1",
            "subCategoryList": null,
            "pubmaticAdvertiserCategoryId": 8,
            "name": "Books & Literature"
          }
        ],
        "pubmaticAdvertiserCategoryId": 8,
        "name": "Arts & Entertainment"
      }
    },
    {
      "id": 279,
      "name": "Sports",
      "uri": "http://${URI_PREFIX}/common/iabCategories/IAB17",
      "iabDetails": {
        "iabName": "Sports",
        "iabId": "IAB17",
        "id": 279,
        "parentCategory": null,
        "parentIabCatId": null,
        "subCategoryList": null,
        "pubmaticAdvertiserCategoryId": 19,
        "name": "Sports"
      }
    }
  ],
  "advertiserDomains": [
    {
      "id": 1,
      "name": "test.domain",
      "uri": "http: //${URI_PREFIX}/common/advertisorDomain/1"
    }
  ],
  "buyers": [
    {
      "id": 1,
      "name": "Buyer 1",
      "uri": "$URI_PREFIX/buyer/1"
    }
  ],
  "buyerEmails": [
    "test@buyer.com"
  ],
  "dsps": [
    {
      "id": 1,
      "name": "DSP 1",
      "uri": "$URI_PREFIX/advertisingEntity/1"
    },
    {
      "id": 2,
      "name": "DSP 2",
      "uri": "$URI_PREFIX/advertisingEntity/2"
    }
  ],
  "dspEmails": [
    "test@dsp.com"
  ],
  "publisher": [
    {
      "id": 1,
      "name": "Publisher 1",
      "uri": "$URI_PREFIX/publisher/1"
    }
  ],
  "pubEmails": [
    "test@publisher.com"
  ],
  "additionalEmails": [
    "test1@pubmatic.com"
  ],
  "advertiserWhiteListing": true,
  "modificationTime": "2015-01-09T14:49:57Z",
  "lastNegotiatedBy": 1,
  "activityLogDetails": [
    {
      "userId": 13569,
      "userEmail": "test_shalmali@pubmatic.com",
      "patch": null,
      "creationTime": "2015-01-09T14:49:57Z",
      "mapChangedDetails": {
        "advertiserCategories": [
          "Updated: from (All) to (Auto )"
        ]
      }
    }
  ]
}

HTTP Response Status Codes

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

Sample error response

[
    {
        "errorCode": "DEAL_001_0010",
        "errorMessage": "Error fetching deal XYZ"
    }
]

Attachments

    Outcomes