Targeted PMP APIs

Document created by david.simerly on Apr 10, 2018Last modified by david.simerly on Jul 10, 2018
Version 2Show Document
  • View in full screen mode

PubMatic's Targeted Deals API lets buyers create deals based on their targeting specifications. The Targeted Deals API provides methods to enable buyers to create, update, and search for a list of targeted PMP and PMP Targeted deals.

 

Methods

Method Path
HTTP Method Type
Description
Link to Definition
/curateddeals
POST
Create a new Targeted Deal in the PubMatic system.

Create a Targeted Deal

/curateddeals
GET
Update a Targeted Deal.
/curateddeals/$ID
PUT
Find the details of Targeted Deals.Combined Deal Search

 

Create a Targeted Deal

Creating a targeted deal generates one child deal for each publisher, based on the selected offers. Deal creation is asynchronous, returning a status of In Progress until child deal creation completes, at which time you can fetch the child deal(s) and updated status using a GET call.

 

Create Request

URL

$URI_PREFIX/curateddeals

HTTP Method

POST

 

The following sections describe what goes into creating a Targeted Deal:

 

 

Create Request Header

Header Name

Type

Value

Description

Authorization

String

Bearer ${access_token}

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

 

Create Request Body

Parameters

Type

Required

Supported

Validations

Description

flooreCPM

float

Yes

Yes

Value between 0.00 to 999.99

Minimum eCPM value for the Targeted Deal.

auctionType

Integer

Yes

Yes

2 = Second Price

Indicates the auction type.

Currently Targeted Deals support only Second Price auctions.

startDate

Date

Yes

Yes

  1. After current date
  2. Before endDate
  3. Format: 2018-03-17T07:00:00.000Z

Start date for the Targeted Deal.

endDate

Date

Yes

Yes

  1. After current date
  2. After startDate
  3. Format: 2018-03-17T07:00:00.000Z

End date for the Targeted Deal.

timeZone

Integer

Yes

Yes

1 = PST

Currently Targeted Deals support only PST timezone from the demand side.

targeting

Long

Yes

Yes

Targeting present in system

Create targeting using the Targeting APIs (for Publishers & Demand Partners), then use the ID returned in the response for this parameter.

loggedInOwnerId

Long

Yes

Yes

User has access to given resource.

DSP/ATD ID.

loggedInOwnerTypeId

Integer

Yes

Yes

Possible values:

5 = DSP

7 = ATD

Indicates whether the owner logged in as ATD or DSP.

advertiserWhiteListing

Boolean

Yes

No

 

Currently unsupported.

advertiserCategories

Array of Long

No

No

Currently unsupported.
advertisers

Array of Long

No

No

 

Currently unsupported.
advertiserDomains

Array of Long

No

No

 

Currently unsupported.
status

Integer

No

No

Always null for create.

Status of the Targeted Deal.

additionalInfo

String

No

No

 

Currently unsupported.
buyerEmails

Array of String

No

No

 

Currently unsupported.
dspEmails

Array of String

No

No

 

Currently unsupported.
additionalEmails

Array of String

No

No

 

Currently unsupported.
offers

Array of Long

Yes

Yes

Limited to one offer per publisher.

Fetch targeted offer ID using the Offers API.

dealDspBuyerMappings

Array of DSP buyer mappings

Yes

Yes

Mapped DSP and ATDs.

For DSP ATDs or ATD DSPs mapped to the Targeted Deal.

 

Create Sample Request

{
  "flooreCPM": 0.01,
  "auctionType": 2,
  "startDate": "2018-03-17T07:00:00.000Z",
  "endDate": "2033-01-01T07:59:59.000Z",
  "timeZone": "1",
  "targeting": 92902,
  "loggedInOwnerId": "22",
  "loggedInOwnerTypeId": 5,
  "advertiserWhiteListing": false,
  "advertiserCategories": [],
  "advertisers": [],
  "advertiserDomains": [],
  "status": null,
  "additionalInfo": "",
  "buyerEmails": [],
  "dspEmails": [],
  "additionalEmails": [],
  "offers": [
    33909,
    33910
  ],
  "dealDspBuyerMappings": [
    {
      "dspId": "22",
      "buyerId": 104,
      "seatId": null
    }
  ]
}

 

Create Response

The following sections describe the make up of a response returned by a create Targeted Deal request:

 

 

Create Response Body

Parameters

Type

Description

id

Long

ID of the new Targeted Deal.

dealId

String

An auto-generated alphanumeric ID used by publishers.

name

String

The deal name.

description

String

Not currently supported.

targeting

Long

The targeting ID associated with the Targeted Deal. Use this value to view targeting parameters associated with the Targeted Deal.

flooreCPM

float

Minimum eCPM value for the Targeted Deal.

startDate

Date

Start date for the Targeted Deal.

endDate

Date

End date for the Targeted Deal

creationTime

Date

The time the Targeted Deal was created.

modificationTime

Date

The time the Targeted Deal was last modified.

status

Integer

Status of the Targeted Deal. Possible values:

1 = Active

2 = Inactive

4 = Scheduled

5 = Completed

10 = InProgress

11 = Failed

12 = PartiallyFailed

childDeals

Array of child deals

Empty in case deal create can be fetched using GET API.

 

Other response parameters are reporting parameters and populate with actual values only on get and search calls.

 

Create Sample Response

{
  "id": 4275,
  "dealId": "PM-JMZJ-3145",
  "name": "PM-WNAJ-5640",
  "description": null,
  "targeting": 92902,
  "flooreCPM": 0.01,
  "startDate": "2018-03-17T07:00:00.000Z",
  "endDate": "2033-01-01T07:59:59.000Z",
  "creationTime": “2018-03-15T13:37:32.422Z”,
  "modificationTime": "2018-03-15T13:37:32.422Z",
  "status": {
    "id": 10,
    "name": "InProgress"
  },
  "childDeals": [],
  "impressions": -1,
  "revenue": -1,
  "bidEcpm": -1,
  "publisher": null,
  "bidRequestSent": -1,
  "totalBidResponses": {
    "dealNumbers": -1,
    "dealScore": -1,
    "dealReason": null,
    "dealAction": null
  },
  "auctionBids": -1,
  "blockedByFF": null,
  "blockedByLPF": null,
  "blockedByLB": null,
  "blockedByDealWhitelist": null,
  "winningImpressions": null,
  "totalNonZeroBids": null,
  "lostBidAuction": null,
  "totalNonZeroBidsNumbers": -1,
  "blockedByDWNumbers": -1,
  "blockedByLPFNumbers": -1,
  "blockedByFFNumbers": -1,
  "dealType": null,
  "fillRate": null,
  "timeoutRate": null,
  "winRate": null,
  "responseRate": null,
  "strEcpm": "-1.0",
  "dealDspBuyerMappings": null
}

 

Update a Targeted Deal

Updates details of Targeted Deals with the exception of those that are in-progress, which are read-only. You can update specific Targeted Deals using the ID provided in URL path parameter. New offers generate corrosponding new deals. Removed offers complete the corresponding deals.

 

Update Request

URL

$URI_PREFIX/curateddeals/$ID

HTTP Method

PUT

 

The following sections describe what goes into updating a Targeted Deal:

 

 

Update Request Header

Header Name

Type

Value

Description

Authorization

String

Bearer ${access_token}

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

 

Update Request Body

Parameters

Type

Required

Supported

Validations

Description

flooreCPM

float

Yes

Yes

Value between 0.00

to 999.99

Floor value for targeted deals.

auctionType

Integer

Yes

Yes

2 = Second Price

Indicates the auction type.

Currently Targeted Deals support only Second Price auctions.

startDate

Date

Yes

Yes

  1. After current date
  2. Before endDate
  3. Format: 2018-03-17T07:00:00.000Z

Start date for the Targeted Deal.

endDate

Date

Yes

Yes

  1. After current date
  2. After startDate
  3. Format: 2018-03-17T07:00:00.000Z

End date for the Targeted Deal.

timeZone

Integer

Yes

Yes

1 = PST

 

Currently Targeted Deals support only PST timezone from the demand side.
targeting

Long

Yes

Yes

Targeting present in system

User need to create targeting using targeting api and use id here.Targeting will store information of targeting. Currently audience,geo is supported.

loggedInOwnerId

Long

Yes

Yes

User has access to given resource.

DSP/ATD ID.

loggedInOwnerTypeId

Integer

Yes

Yes

Possible values:

5 = DSP

7 = ATD

Indicates whether the owner logged in as ATD or DSP.

advertiserWhiteListing

Boolean

Yes

No

 

 

Currently unsupported.
advertiserCategories

Array of Long

No

No

 

Currently unsupported.
advertisers

Array of Long

No

No

 

Currently unsupported.
advertiserDomains

Array of Long

No

No

 

Currently unsupported.
status

Integer

Yes

Yes

Possible values:

1 = Active

2 = Inactive/pause

4 = Schedule

Status of the Targeted Deal

additionalInfo

String

No

No

 

Currently unsupported.
buyerEmails

Array of String

No

No

 

Currently unsupported.
dspEmails

Array of String

No

No

 

Currently unsupported.
additionalEmails

Array of String

No

No

 

Currently unsupported.
offers

Array of Long

Yes

Yes

Limited to one offer per publisher.

Fetch targeted offer IDs using theOffers API.

dealDspBuyerMappings

Array of DSP buyer mappings

Yes

Yes

DSP and ATDs are mapped

For DSP ATDs mapped to it and for ATD DSPs mapped to it.

 

Update Sample Request

{
  "flooreCPM": 0.01,
  "auctionType": 2,
  "startDate": "2018-03-17T07:00:00.000Z",
  "endDate": "2033-01-01T07:59:59.000Z",
  "timeZone": "1",
  "targeting": 92902,
  "loggedInOwnerId": "22",
  "loggedInOwnerTypeId": 5,
  "advertiserWhiteListing": false,
  "advertiserCategories": [],
  "advertisers": [],
  "advertiserDomains": [],
  "status": 1,
  "additionalInfo": "",
  "buyerEmails": [],
  "dspEmails": [],
  "additionalEmails": [],
  "offers": [
    33909,
    33910
  ],
  "dealDspBuyerMappings": [
    {
      "dspId": "22",
      "buyerId": 104,
      "seatId": null
    }
  ]
}

 

Update Response

The following sections describe the make up of a response returned by an update Targeted Deal request:

 

 

Update Response Body

Body parameter

Type

Description

id

Long

ID of a Targeted Deal.

dealId

String

An auto-generated alphanumeric ID used by publishers.

name

String

The deal name.

description

String

Currently unsupported.

targeting

Long

The targeting ID associated with the Targeted Deal. Use this value to view targeting parameters associated with the Targeted Deal.

flooreCPM

float

Minimum eCPM value for the Targeted Deal.

startDate

Date

Start date for the Targeted Deal.

endDate

Date

End date for the Targeted Deal.

creationTime

Date

The time the Targeted Deal was created.

modificationTime

Date

The time the Targeted Deal was last modified.

status

Integer

Status of targeted deal.

1 = Active

2 = Inactive

4 = Scheduled

5 = Completed

10 = InProgress

11 = Failed

12 = PartiallyFailed

childDeals

Array of child deals

Empty in case deal create can be fetched using GET API.

 

Other response parameters are reporting parameters and populate with actual values only on get and search calls.

 

Update Sample Response

{
  "id": 4274,
  "dealId": "PM-HWJL-8558",
  "name": "PM-NTXM-2322",
  "description": null,
  "targeting": 92911,
  "flooreCPM": 0.01,
  "startDate": "2019-01-23T08:00:00.000Z",
  "endDate": "2019-01-24T07:59:59.000Z",
  "creationTime": "2018-03-15T13:33:45.000Z",
  "modificationTime": "2018-03-15T14:56:14.409Z",
  "status": {
    "id": 10,
    "name": "InProgress"
  },
  "childDeals": [],
  "impressions": -1,
  "revenue": -1,
  "bidEcpm": -1,
  "publisher": null,
  "bidRequestSent": -1,
  "totalBidResponses": {
    "dealNumbers": -1,
    "dealScore": -1,
    "dealReason": null,
    "dealAction": null
  },
  "auctionBids": -1,
  "blockedByFF": null,
  "blockedByLPF": null,
  "blockedByLB": null,
  "blockedByDealWhitelist": null,
  "winningImpressions": null,
  "totalNonZeroBids": null,
  "lostBidAuction": null,
  "totalNonZeroBidsNumbers": -1,
  "blockedByDWNumbers": -1,
  "blockedByLPFNumbers": -1,
  "blockedByFFNumbers": -1,
  "dealType": null,
  "fillRate": null,
  "timeoutRate": null,
  "winRate": null,
  "responseRate": null,
  "strEcpm": "-1.0",
  "dealDspBuyerMappings": null
}

 

Get a combined list of targeted PMP and PMPG deals.

 

Combined Deal Search Request

URI

${URI_PREFIX}/curateddeals/

HTTP Method

GET

 

The following sections describe what goes into requesting a combined deal search:

 

 

Combined Deal Search Request Query Parameters

Parameters

Type

Required

Validations

Description

ownerId

Long

Yes

DSP or ATD ID

User has access to given resource.

ownerTypeId

Integer

Yes

Possible values:

5 = DSP

7 = ATD

User has access to given resource.

pageNumber

Integer

Yes

NA

Page number for pagination.

pageSize

Integer

Yes

NA

Page Size for pagination.

view

String

Yes

Summary or Detail

 

 

Combined Deal Search Response

The following sections describe the make up of a response returned by a combined deal search request:

 

 

Combined Deal Search Response Body

Response Body Parameter

Type

Description

metaData

JSON

Search result meta data.

items

JSON Array

Items returned by the search.

id

Long

Unique ID of a Targeted Deal.

dealId

String

An auto-generated alphanumeric ID used by publishers.

name

String

The Targeted Deal name.

description

String

Deal description.

targeting

Long

The targeting ID associated with the Targeted Deal. Use this value to view targeting parameters associated with the Targeted Deal.

flooreCPM

float

Minimum eCPM value for the Targeted Deal.

startDate

Date

Start date for the Targeted Deal.

endDate

Date

End date for the Targeted Deal.

creationTime

Date

The time the Targeted Deal was created.

modificationTime

Date

The time the Targeted Deal was last modified.

status

JSON Object

Deal Status.

childDeals

JSON Array

Array of child Targeted Deals.

publisher

JSON Object

Targeted Deal publisher (there may be multiple entries for multiple publishers).

dealType

String

PMP_TARGETED or PMP.

dealDspBuyerMappings

JSON Array

Available only on a Targeted Deal GET call, otherwise this value is NUL.

impressions

Long

Indicates a non-defaulted number of impressions.

revenue

double

Targeted Deal campaign revenue.

bidEcpm

float

 

bidRequestSent

long

Total number of bid requests sent.

totalBidResponses

long

Total number of bid responses received.

auctionBids

long

Total number of auction bids.

blockedByFF

JSON

Blocked by floor filtering.

blockedByLPF

JSON

Blocked by landing page filtering details.

blockedByLB

JSON

Blocked by Low Bids details.

blockedByDealWhitelist

JSON

Blocked deal whitelisting details.

winningImpressions

Long

Total paid impressions.

totalNonZeroBids

JSON

Total non-zero bids.

lostBidAuction

Long

Total number of lost bids.

totalNonZeroBidsNumbers

Long

Total non-zero bids

blockedByDWNumbers

Long

Bids blocked by Deal White List numbers.

blockedByLPFNumbers

Long

Bids blocked by Landing Page Filtering numbers.

blockedByFFNumbers

Long

bids blocked by Floor Filtering numbers.

fillRate

float

fillRate = paidImpressions *100 / totalImpressions

timeoutRate

float

timeout rate.

winRate

int

Number of win bids as a percentage of total bids.

 

Response Body for Combined Deal Search on Child Deals

Available only for Targeted Deals.

Parameters

Type

Description

id

Long

Unique ID of a targeted child deal.

curatedDealId

Long

ID of that child's parent Targeted Deal

dealMetaId

Long

ID of the PMP deal created for targeted child deal.

name

String

Targeted child deal name.

status

JSON Object

Targeted child deal status. 

statusDetail

String

Provides the reason why a targeted child deal may have failed.

pausedBy

Integer

1 if paused by publisher, otherwise NULL.

payLoad

JSON

JSON used for creation/modification of corresponding PMP deal.

owner

JSON

Publisher for which deal is created.

offerId

Long

ID of the offer for which targeted child deal was created.

dealType

String

Currently always PMP_TARGETED to indicate a targeted deal.

 

Combined Deal Search Sample Response

{
"metaData": {
"startIndex": 1,
"totalRecords": 186,
"pageNumber": 1,
"fetchSize": 1,
"endIndex": 1
},
"items": [
{
"id": 19,
"dealId": "PM-GWJF-6553",
"name": "PM-YDWX-8937",
"description": null,
"targeting": 87343,
"flooreCPM": 0.01,
"startDate": "2018-03-27T11:41:03.000Z",
"endDate": "2018-03-28T06:59:59.000Z",
"creationTime": "2018-03-27T11:41:02.000Z",
"modificationTime": "2018-03-27T11:43:01.000Z",
"status": {
"id": 1,
"name": "Active"
},
"childDeals": [
{
"id": 19,
"curatedDealId": 19,
"dealMetaId": 76963,
"name": "PM-YDWX-8937_DN-AMCV-8772",
"description": null,
"status": {
"id": 1,
"name": "Active"
},
"statusDetail": null,
"pausedBy": null,
"payLoad": null,
"owner": {
"id": 33233,
"companyName": "Test Account",
"name": null
},
"offerId": 26980,
"dealType": "PMP_TARGETED"
}
],
"impressions": -1,
"revenue": -1,
"bidEcpm": -1,
"publisher": {
"id": 33233,
"companyName": "Test Account",
"name": null
},
"bidRequestSent": -1,
"totalBidResponses": {
"dealNumbers": -1,
"dealScore": -1,
"dealReason": null,
"dealAction": null
},
"auctionBids": -1,
"blockedByFF": null,
"blockedByLPF": null,
"blockedByLB": null,
"blockedByDealWhitelist": null,
"winningImpressions": null,
"totalNonZeroBids": null,
"lostBidAuction": null,
"totalNonZeroBidsNumbers": -1,
"blockedByDWNumbers": -1,
"blockedByLPFNumbers": -1,
"blockedByFFNumbers": -1,
"dealType": "PMP_TARGETED",
"fillRate": null,
"timeoutRate": null,
"winRate": null,
"responseRate": null,
"strEcpm": "-1.0",
"dealDspBuyerMappings": null
}
]
}

 

⇧ Top

Attachments

    Outcomes