Private Marketplace (PMP) Deal APIs for Publishers

Document created by pubmatic-archivist on Mar 27, 2017Last modified by david.simerly on Sep 18, 2017
Version 28Show Document
  • View in full screen mode

The Private Market Place (PMP) API streamlines the process between publishers and demand partners/buyers to maximize revenue for premium inventory. The PMP APIs facilitate deal negotiations and closures by enabling demand partners/buyers to obtain premium PubMatic publisher inventory to display in their own systems and create deals. Follow the API instructions to manage this process with demand partners.

 

The API contains the following components:

  1. Creating a Deal: This (POST) API enables you to publish deals in PubMatic.
  2. Retrieving a List of Deals: This (GET) API retrieves the list of deals based on the filter criteria you include.
  3. Retrieving Details of a Deal: This (GET) API enables you to obtain the details of a specific deal.
  4. Updating a Deal: This (PUT) API enables you to update the details of a specific deal. Once your update is successful, a response will be sent to the DSP/Buyer with the newly-updated detail.

 

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 Demand Partners documentation can be found here: Private Marketplace (PMP) Deal APIs for Demand Partners 

                                       

 

Methods                   

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

 

Creating a Deal

Overview

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

 

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. 

 

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.

To create a deal for all Buyers associated with a DSP, see Creating a Deal for Buyers associated with a DSP below.

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 auto-generated 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.

dealIdInRequestEnabled

Boolean

No

Yes

Default value = False

Set this flag to True to indicate that the Publisher will include the Deal ID in the OpenRTB Ad Request to PubMatic.

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

priority

Integer

No

Yes

Value must be in the following interval: 0<= priority <= 100.

Displayable to publishers only.

Priority of the deal.

The lower the number, the higher the priority.

This field is visible only to Publishers.

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.

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

ID of the product  from which this deal is originated.

Please refer to Product API details for more information.

targetingIntegerNoYes
  • Value must be greater than 0.
  • Value must be a valid targeting ID.
  • Can only be passed when 'product' must be provided.

ID of the targeting from which this deal is originated.

Please refer to the Targeting 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.

salesperson

String

No

Yes
  • Value must be a valid user e-mail ID.
  • Only publisher Admin can set this field
  • If user is logged in publisher user, user will be saved as sales person of the deal.

Sales representative associated with the deal.

It is a publisher-specific deal, therefore only a publisher can send this parameter.

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

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.

lastLookUpEnabled

Boolean

No

Yes

Default Value = False

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

Indicates whether last look up has been enabled for the deal or not.

publisherCategoryIdIntegerNoYes Used for PMRG consortium

revShare
DoubleNoYes Used for PMRG consortium
loggedInOwnerIdLongYesYesShould be a valid Publisher ID, DSP ID or Buyer IDIndicates 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 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

 

Request

Sample Request JSON for Creating a Deal from a Product

{
  "dealId": "PM-12344512",
  "name": "test deal",
  "channelType": "1",
  "auctionType": "2",
  "additionalEmails": [],
  "startDate": "2017-01-12T06:03:58Z",
  "endDate": "2033-01-01T07:59:59.000Z",
  "flooreCPM": 0.03,
  "minSpend": null,
  "impressionAvails": null,
  "additionalInfo": "",
  "advertiserCategories": [],
  "advertisers": [],
  "advertiserDomains": [],
  "products": [
    27474
  ],
  "offer": null,
  "targeting": 47391,
  "advertiserWhiteListing": "false",
  "dspEmails": [
    {
      "ownerId": "1",
      "userEmails": []
    }
  ],
  "pubEmails": [],
  "buyerEmails": [
    {
      "ownerId": "2",
      "userEmails": []
    }
  ],
  "salesPerson": null,
  "decisionManagerEnabled": null,
  "lastLookUpEnabled": "false",
  "priority": 100,
  "timeZone": 1,
  "revShare": "",
  "publisherCategoryId": "",
  "dealDspBuyerMappings": [
    {
      "dspId": 1,
      "buyerId": 2,
      "seatId": 123
    }
  ],
  "dealIdInRequestEnabled": true,
  "loggedInOwnerId": 12345,
  "loggedInOwnerTypeId": 1
}

 

Sample Request JSON for IAB-Enabled Publishers

{
  "dealId": "ABCD1234",
  "name": "SampleRequestDeal",
  "additionalInfo": "I would like to sell this deal for $0.3",
  "status": 1,
  "priority": 3,
  "auctionType": 1,
  "channelType": 1,
  "impressionAvails": 10000,
  "minSpend": 500,
  "offer": 122323,
  "startDate": "2017-01-12T06:03:58Z",
  "endDate": "2033-01-01T07:59:59.000Z",
  "timeZone": 1,
  "flooreCPM": 2.23,
  "salesPerson": "test1@pubmatic.com",
  "advertisers": [
    1,
    2,
    3
  ],
  "advertiserIABCategories": [
    "IAB1"
  ],
  "advertiserDomains": [
    1,
    2,
    3
  ],
  "buyerEmails": [
    {
      "ownerId": "1",
      "userEmails": [
        "test_abc@pqr.com",
        "test_xyz@pqr.com"
      ]
    }
  ],
  "dspEmails": [
    {
      "ownerId": "1",
      "userEmails": [
        "test_abc@pqr.com",
        "test_xyz@pqr.com"
      ]
    }
  ],
  "additionalEmails": [
    "test1@pubmatic.com"
  ],
  "advertiserWhiteListing": true,
  "decisionManagerEnabled": false,
  "lastLookUpEnabled": true,
  "publisherCategoryId": "",
  "revShare": "",
  "dealDspBuyerMappings": [
    {
      "dspId": 1,
      "buyerId": 1,
      "seatId": null
    },
    {
      "dspId": 2,
      "buyerId": 1,
      "seatId": null
    }
  ],
  "dealIdInRequestEnabled": true,
  "loggedInOwnerId": 12345,
  "loggedInOwnerTypeId": 1
}

 

Sample Request JSON for Non-IAB Enabled Publishers

{
  "dealId": "ABCD1234",
  "name": "SampleRequestDeal",
  "additionalInfo": "I would like to sell this deal for $0.3",
  "status": 1,
  "priority": 3,
  "auctionType": 1,
  "channelType": 1,
  "impressionAvails": 10000,
  "minSpend": 500,
  "offer": 122323,
  "startDate": "2017-01-12T06:03:58Z",
  "endDate": "2033-01-01T07:59:59.000Z",
  "timeZone": 1,
  "flooreCPM": 2.23,
  "salesPerson": "test1@pubmatic.com",
  "advertisers": [
    1,
    2,
    3
  ],
  "advertiserCategories": [
    6,
    12
  ],
  "advertiserDomains": [
    1,
    2,
    3
  ],
  "buyerEmails": [
    {
      "ownerId": "1",
      "userEmails": [
        "test_abc@pqr.com",
        "test_xyz@pqr.com"
      ]
    }
  ],
  "dspEmails": [
    {
      "ownerId": "1",
      "userEmails": [
        "test_abc@pqr.com",
        "test_xyz@pqr.com"
      ]
    }
  ],
  "additionalEmails": [
    "test1@pubmatic.com"
  ],
  "advertiserWhiteListing": true,
  "decisionManagerEnabled": false,
  "lastLookUpEnabled": true,
  "publisherCategoryId": "",
  "revShare": "",
  "dealIdInRequestEnabled":true,
  "dealDspBuyerMappings": [
    {
      "dspId": 1,
      "buyerId": 1,
      "seatId": null
    },
    {
      "dspId": 2,
      "buyerId": 1,
      "seatId": null
    }
  ],
  "dealIdInRequestEnabled":true,
  "loggedInOwnerId": 12345,
  "loggedInOwnerTypeId": 1
}

 

Response

Response Body

Response Body ParameterTypeDescription
itemsList of DealsList of newly created deals

 

Sample Response JSON for IAB-enabled Publishers

{
  "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"
      },
      "priority": 3,
      "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,
      "salesPerson": "test1@pubmatic.com",
      "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"
      ],
      "additionalEmails": [
        "test1@pubmatic.com"
      ],
      "advertiserWhiteListing": true,
      "decisionManagerEnabled": false,
      "lastLookUpEnabled": true,
      "dealIdInRequestEnabled":true,
      "dealDspBuyerMappings": [
         { "id": 33102,
           "dealMetaId": 123456,
           "dspId": 1,
           "buyerId": 1,
          "seatId": 10422
         },
         { "id": 33102,

           "dealMetaId": 123456,
           "dspId": 1,
           "buyerId": 1,
          "seatId": 10422
         }
       ]
    }
  ]
}

 

Sample Response JSON for a Non-IAB Publisher

{
  "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"
      },
      "priority": 3,
      "auctionType": {
        "id": 1,
        "name": "FIRST PRICE"
      },
     "channelType": {
        "id": 1,
        "name": "PMP"
     },
    "minSpend": 500,
    "impressionAvails": 1000,
    "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,
      "salesPerson": "test1@pubmatic.com",
      "advertisers": [
        {
          "id": 1,
          "name": "Advertiser 1",
          "uri": "${URI_PREFIX}/advertiser/1"
        }
      ],
      "advertiserCategories": [
        {
          "id": 6,
          "name": "Drugs & Supplements",
          "uri": "http://${URI_PREFIX}/common/advertiserCategory/6",
          "iabDetails": null
        },
        {
          "id": 12,
          "name": "News",
          "uri": "http://${URI_PREFIX}/common/advertiserCategory/12",
          "iabDetails": null
        }
      ],
      "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"
      ],
      "additionalEmails": [
        "test1@pubmatic.com"
      ],
      "advertiserWhiteListing": true,
      "decisionManagerEnabled": false,
      "lastLookUpEnabled": true,
      "dealIdInRequestEnabled": true,
      "dealDspBuyerMappings": [
         { "id": 33102,
           "dealMetaId": 123456,
           "dspId": 1,
           "buyerId": 1,
          "seatId": 10422
         },
         { "id": 33102,
           "dealMetaId": 123456,
           "dspId": 1,
           "buyerId": 1,
          "seatId": 10422
         }
       ]
    }
  ]
}

 

Creating a Deal for Buyers Associated with a DSP

There are two ways of creating a deal for all buyers associated with a DSP:

  1. There are three DSPs Turn, DBM and Centro DSP with special mapping of “Any Buyer” (ID : -1) . So buyer-id == -1 means all buyers for any of these DSPs. If you want another DSP to have such a mapping, please let your account manger know. Before mapping, we will need to confirm with the DSP first that if they can process –1 for any buyer.
  2. To fetch all Buyers mapped to a given DSP, one will need to call our Buyers API. Here is a sample request and response for the same.

 

Request

GET http://{domainName}/common/advertisingEntity/getDSPBuyerMap?dspId=123&pageNumber=2&pageSize=2&sort=name

 

Response

{
"metaData": {
"startIndex": "1",
"totalRecords": "100",
"endIndex": "2"
},
"items": [
{
"demandPartner": {
"id": 123,
"name": "Test Demand Partner",
"uri": "http://beta-api.pubmatic.com/v1/common/advertisingEntity/123"
},
"buyers": [
{
"id": 45,
"name": "Buyer 1",
"uri": "http://beta-api.pubmatic.com/v1/common/buyer/45",
"dspBuyerId": 1458
},
{
"id": 27,
"name": "Buyer 2",
"uri": "http://beta-api.pubmatic.com/v1/common/buyer/2",
"dspBuyerId": 91
}
]
}
]
}

 

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 a List of Deals

 

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. 
loggedInOwnerTypeIdIntegerIndicates type of account.
Publisher – 1
Demand partner – 5
Buyer/ATD - 7
&filters=loggedInOwnerTypeId eq 1
loggedInOwnerIdLongAccount ID&filters=loggedInOwnerId eq 12345

 

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 Parameter
Type
Description
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 for an IAB-enabled User

{
"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"
},
"priority": 3,
"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,
"salesPerson": "test1@pubmatic.com",
"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": [
{
"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"
]
}
],
"additionalEmails": [
"test1@pubmatic.com"
],
"advertiserWhitelisting": true,
"decisionManagerEnabled": false,
"lastLookUpEnabled": true,
"dealIdInRequestEnabled": true,
"revShare": null,
"publisherCategoryId": null,
"dealDspBuyerMappings": [
         { "id": 33102,
           "dealMetaId": 123456,
           "dspId": 1,
           "buyerId": 1,
          "seatId": 10422
         },
         { "id": 33102,
           "dealMetaId": 123456,
           "dspId": 1,
           "buyerId": 1,
          "seatId": 10422
         }
       ],
"messages": []
}
]
}

 

Sample Response JSON for a Non-IAB User

{
"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"
},
"priority": 3,
"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,
"salesPerson": "test1@pubmatic.com",
"advertisers": [
{
"id": 1,
"name": "Advertiser 1",
"uri": "${URI_PREFIX}/advertiser/1"
}
],
"advertiserCategories": [
{
"id": 6,
"name": "Drugs & Supplements",
"uri": "http://${URI_PREFIX}/common/advertiserCategory/6",
"iabDetails": null
},
{
"id": 12,
"name": "News",
"uri": "http://${URI_PREFIX}/common/advertiserCategory/12",
"iabDetails": null
}
],
"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": [
{
"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"
]
}
],
"additionalEmails": [
"test1@pubmatic.com"
],
"advertiserWhitelisting": true,
"decisionManagerEnabled": false,
"lastLookUpEnabled": true,
"dealIdInRequestEnabled": true,
"revShare": null,
"publisherCategoryId": null,
"dealDspBuyerMappings": [
         { "id": 33102,

           "dealMetaId": 123456,
           "dspId": 1,
           "buyerId": 1,
          "seatId": 10422
         },
         { "id": 33102,

           "dealMetaId": 123456,
           "dspId": 1,
           "buyerId": 1,
          "seatId": 10422
         }

       ],
"messages": []
}
]
}

 

Error Codes

Sample error response

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

 

Retrieving Details of a Deal

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.
dealIdInRequestEnabledBooleanSet this flag to True to indicate that the Publisher will include the Deal ID in the OpenRTB Ad Request to PubMatic.
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

priorityIntegerPriority of the deal. The lower the number, the higher the priority.
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.
salesPersonStringEmail of the sales representative associated with the 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.
additionalEmailsList of EmailsAny additional email addresses to be notified on the deal state changes.
decisionManagerEnabledBooleanIndicates whether Decision Manager has been enabled for the deal or not.
lastLookUpEnabledBooleanIndicates whether last look up has been enabled for the deal or not.
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.
dealDspBuyerMappingsJSON ElementIndicates the Deal DSP/Buyer Mappings
publisherCategoryIdIntegerIndicates the Publisher Category ID
revShareDoublIndicates the Revenue Share

 

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 for an IAB-enabled Publisher

{
  "id": 123456,
  "dealId": "ABCD1234",
  "name": "SampleRequestDeal",
  "additionalInfo": "I would like to buy this deal for $0.3",
  "status": {
    "id": 2,
    "name": "In Review"
  },
  "priority": 3,
  "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,
  "salesPerson": "test1@pubamtic.com",
"channelType": {
"id": 1,
"name": "PMP"
},
  "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"
  ],
  "additionalEmails": [
    "test1@pubmatic.com"
  ],
  "advertiserWhiteListing": true,
  "decisionManagerEnabled": false,
  "lastLookUpEnabled": true,
  "dealIdInRequestEnabled": true,
  "modificationTime": "2015-01-09T14:49:57Z",
  "lastNegotiatedBy": 1,
  "revShare": null,
  "publisherCategoryId": null,
  "dealDspBuyerMappings": [
         { "id": 33102,
           "dealMetaId": 123456,
           "dspId": 1,
           "buyerId": 1,
          "seatId": 10422
         },
         { "id": 33102,
           "dealMetaId": 123456,
           "dspId": 1,
           "buyerId": 1,
          "seatId": 10422
         }
       ],
  "activityLogDetails": [
    {
      "userId": 13569,
      "userEmail": "test_shalmali@pubmatic.com",
      "patch": null,
      "creationTime": "2015-01-09T14:49:57Z",
      "mapChangedDetails": {
        "advertiserCategories": [
          "Updated: from (All) to (Auto )"
        ]
      }
    }
  ]
}

 

Sample Response JSON for a Non-IAB  User

{
  "id": 123456,
  "dealId": "ABCD1234",
  "name": "SampleRequestDeal",
  "additionalInfo": "I would like to buy this deal for $0.3",
  "status": {
    "id": 2,
    "name": "In Review"
  },
  "priority": 3,
  "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,
  "salesPerson": "test1@pubamtic.com",
  "advertisers": [
    {
      "id": 1,
      "name": "Advertiser 1",
      "uri": "${URI_PREFIX}/advertiser/1"
    }
  ],
  "advertiserCategories": [
    {
      "id": 6,
      "name": "Drugs & Supplements",
      "uri": "http://${URI_PREFIX}/common/advertiserCategory/6",
      "iabDetails": null
    },
    {
      "id": 12,
      "name": "News",
      "uri": "http://${URI_PREFIX}/common/advertiserCategory/12",
      "iabDetails": null
    }
  ],
  "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"
  ],
  "additionalEmails": [
    "test1@pubmatic.com"
  ],
  "advertiserWhiteListing": true,
  "decisionManagerEnabled": false,
  "lastLookUpEnabled": true,
  "dealIdInRequestEnabled": true,
  "modificationTime": "2015-01-09T14:49:57Z",
  "lastNegotiatedBy": 1,
  "revShare": null,
  "publisherCategoryId": null,
  "dealDspBuyerMappings": [
         { "id": 33102,

           "dealMetaId": 123456,
           "dspId": 1,
           "buyerId": 1,
          "seatId": 10422
         },
         { "id": 33102,

           "dealMetaId": 123456,
           "dspId": 1,
           "buyerId": 1,
          "seatId": 10422
         }

       ],
  "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"
    }
]

 

Updating a Deal

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 ATD. 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 Parameter
Type
Required
Supported
Validations
Description
dealId
String
No
Yes
  • 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.
dealIdInRequestEnabled
Boolean
No
Yes
Default value = False

Set this flag to True to indicate that the Publisher will include the Deal ID in the OpenRTB Ad Request to PubMatic.

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 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
auctionType
Integer
Yes
Yes
  • 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
offer
Integer
NoYes
  • 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.
product
Integer
Yes
Yes
  • 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.
startDate
ISO Date in GMT
YesYes
  • Once a deal has started, startDate cannot be modified.
Changed start date of the deal. 
endDate
ISO Date in GMT
No
Yes
  • 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.
timezone
Integer
YesYes
  • 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
flooreCPM
Float
Yes
Yes
  • 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.
salesperson
String
No
Yes
  • Value must be a valid user e-mail ID.
  • Only publisher Admin can set this field
  • If user is logged in publisher user, user will be save as sales person of the deal.
Sales representative associated with the deal. It is a publisher specific deal so only publisher can send this parameter.
advertiserWhiteListing
Boolean
No
Yes
 
Indicates whether advertiser whitelisting is enabled for the deal or not.
Default value: False
advertisers
Array of Integers
No
Yes
  • Value must be valid advertiser ID and should be mapped to selected advertiser categories.
List of advertisers for which the deal should be whitelisted.
advertiserCategories
Array of Integers
No
Yes
  • Value must be valid advertiser category ID
List of advertiser categories for which the deal should be whitelisted.
advertiserIABCategories
Array of Strings
No
Yes
  • Value must be valid IAB advertiser category ID
List of advertiser IAB 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.
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.
buyers
Array of Integers
No
Yes
  • 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.
buyerEmails
Array of Buyer Emails with mapped owner ID
No
Yes
 
List of buyer email addresses that should be notified while creating an INREVIEW or ACTIVE deal and accepting the INREVIEW deal.
dsps
Array of Integers
No
Yes
  • Value must be valid DSP IDs.
List of DSPs associated with the deal, which is viewable for Publishers and ATDs only.
dspEmails
Array of DSP Emails with mapped owner ID
No
Yes
 
List of DSP email addresses that should be notified while creating an INREVIEW or ACTIVE deal and accepting the INREVIEW deal.
additionalEmails
List of Strings
No
Yes
 
Any additional emails that should be notified while creating an INREVIEW or ACTIVE deal and accepting the INREVIEW deal.
decisionManagerEnabled
Boolean
No
Yes
  • Default value: False
Indicates whether Unified Optimization is enabled for the deal.
 
lastLookUpEnabled
 
 
 
Boolean
No
 
  • Value can be set only if last look up has been enabled for the publisher.
Indicates whether last look up has been enabled for the deal or not.
Default value: False

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

Should be a valid Publisher, 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 IAB-enabled Publishers

{
  "id": 123456,
  "dealId": "ABCD1234",
  "name": "SampleRequestDeal",
  "additionalInfo": "I would like to buy this deal for $0.3",
  "status": {
    "id": 2,
    "name": "In Review"
  },
  "priority": 3,
  "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,
  "salesPerson": "test1@pubmatic.com",
  "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"
  ],
  "additionalEmails": [
    "test1@pubmatic.com"
  ],
  "advertiserWhiteListing": true,
  "decisionManagerEnabled": false,
  "lastLookUpEnabled": true,
  "dealIdInRequestEnabled": true
}

 

Sample Request JSON for non-IAB Publishers

{
  "dealId": "ABCD1234",
  "name": "SampleRequestDeal",
  "additionalInfo": "I would like to sell this deal for $0.3",
  "status": 1,
  "priority": 3,
  "auctionType": 1,
  "channelType": 6,
  "impressionAvails": 10000,
  "minSpend": 500,
  "offer": null, "startDate": "2017-07-31T18:06:36Z",
  "endDate": "2017-08-02T06:59:59.000Z",
  "timeZone": 1,
  "flooreCPM": 2.23,
  "salesPerson": "test1@pubmatic.com",
  "advertisers": [
    1,
    2,
    3
  ],
  "advertiserCategories": [
    6,
    12
  ],
  "advertiserDomains": [
    1,
    2,
    3
  ],
  "buyerEmails": [
    {
      "ownerId": "1",
      "userEmails": [
        "test_abc@pqr.com",
        "test_xyz@pqr.com"
      ]
    }
  ],
  "dspEmails": [
    {
      "ownerId": "1",
      "userEmails": [
        "test_abc@pqr.com",
        "test_xyz@pqr.com"
      ]
    }
  ],
  "additionalEmails": [
    "test1@pubmatic.com"
  ],
  "advertiserWhiteListing": true,
  "decisionManagerEnabled": false,
  "lastLookUpEnabled": true,
  "dealIdInRequestEnabled": true,
  "products": [3452],
  "targeting": 284,
  "publisherCategoryId": "",
  "revShare": "",
  "dealDspBuyerMappings": [
    {
      "dspId": 1,
      "buyerId": 1,
      "seatId": null
    },
    {
      "dspId": 2,
      "buyerId": 1,
      "seatId": null
    }
  ],
  "loggedInOwnerId": 12345,
  "loggedInOwnerTypeId": 1
}

 

Response

Response Body

Sample Response JSON for an IAB-enabled User

{
  "id": 123456,
  "dealId": "ABCD1234",
  "name": "SampleRequestDeal",
  "additionalInfo": "I would like to buy this deal for $0.3",
  "status": {
    "id": 2,
    "name": "In Review"
  },
  "priority": 3,
  "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,
  "salesPerson": "test1@pubmatic.com",
  "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"
  ],
  "additionalEmails": [
    "test1@pubmatic.com"
  ],
  "advertiserWhiteListing": true,
  "decisionManagerEnabled": false,
  "lastLookUpEnabled": true,
  "dealIdInRequestEnabled": true
}

 

Sample Response JSON for a Non-IAB User

{
  "id": 123456,
  "dealId": "ABCD1234",
  "name": "SampleRequestDeal",
  "additionalInfo": "I would like to buy this deal for $0.3",
  "status": {
    "id": 2,
    "name": "In Review"
  },
  "priority": 3,
  "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,
  "salesPerson": "test1@pubmatic.com",
  "advertisers": [
    {
      "id": 1,
      "name": "Advertiser 1",
      "uri": "${URI_PREFIX}/advertiser/1"
    }
  ],
  "advertiserCategories": [
    {
      "id": 6,
      "name": "Drugs & Supplements",
      "uri": "http://${URI_PREFIX}/common/advertiserCategory/6",
      "iabDetails": null
    },
    {
      "id": 12,
      "name": "News",
      "uri": "http://${URI_PREFIX}/common/advertiserCategory/12",
      "iabDetails": null
    }
  ],
  "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"
  ],
  "additionalEmails": [
    "test1@pubmatic.com"
  ],
  "advertiserWhiteListing": true,
  "decisionManagerEnabled": false,
  "lastLookUpEnabled": true,
  "dealIdInRequestEnabled": true,
  "dealDspBuyerMappings": [
         { "id": 33102,
           "dealMetaId": 123456,
           "dspId": 1,
           "buyerId": 1,
          "seatId": 10422
         },
         { "id": 33102,
           "dealMetaId": 123456,
           "dspId": 1,
           "buyerId": 1,
          "seatId": 10422
         }
       ]
}

 

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"
    }
]

Attachments

    Outcomes