Skip to end of metadata
Go to start of metadata

Deal Service

The Deal Service lets buyers, sellers, and external bidders set up and manage negotiated deals. Deals may provide buyers:

  • Preferential pricing on inventory
  • Access to exclusive inventory
  • Reduced competition on inventory
  • Other opportunities

Each deal is valid for a single buyer, but note that inventory included in a deal may be encompassed by other deals as well.

Buyers can use the Deal Buyer Access Service to view the deals available to them. To target deals, buyers can use the deal_targets field in the Profile Service.

On This Page

REST API

Add a new deal:

Modify an existing deal:

View all deals you have with buyers:

View a specific deal:

View multiple deals by ID using a comma-separated list:

Delete a deal:

If you delete a deal, all campaigns targeting the deal will stop serving. Deletions are permanent and cannot be reverted. Although deleted deals continue to be available in reporting, you will no longer have visibility into their specific settings.

Find out which fields you can filter and sort by:

JSON Fields

FieldType (Length)DescriptionDefaultRequired On
idintThe ID of the deal.Auto-incremented numberPUT/DELETE, in query string
codestring (100)

The custom code for the deal.

External Sellers

This field is mandatory and represents your internal deal ID, passed in the bid request through the PMP's object deal ID field.

nullPOST , for External Sellers

name

string (255)The name of the deal.null 

description

string (65535)The description of the deal. You can use this field to provide the buyer additional insight or details about the deal.null 

active

Boolean

 

If true, the deal is active. Note that the deal will be available to the buyer only when this field is true, start_date is in the past (or null), and end_date is in the future (or null).true

 

start_date

timestamp

The day and time when the deal starts being available to the buyer, in local time. If this is set, the format must be "YYYY-MM-DD HH:MM:SS".null (immediately)

 

end_date

timestamp

The day and time when the deal stops being available to the buyer, in local time. If this is set, the format must be "YYYY-MM-DD HH:MM:SS".

null (indefinitely)

 

profile_id

int

The ID of the profile associated to the deal. You can use a profile to specify publishers, placements, content categories, geographical areas, segments, segment groups, or sizes that need to be involved in the auction in order for the deal to be available to the buyer. For more details, see publisher_targets, placement_targets, content_category_targets, country_targets, region_targets, city_targets, dma_targets, segment_targets, segment_group_targets, site_targets, and size_targets in the Profile Service.

Any other targeting settings in the associated profile will not be respected.

null

 

package_idintThe package ID for the package from which the deal was created, if applicable. See Deal From Package Service.null 
floor_price

double

The minimum CPM value that the buyer must bid to be eligible for the deal.

If use_deal_floor is false, this field must be set to 0. In this case, note that although 0 is shown as the floor price, no deal floor is actually applied; if you have any other floors (in placements or yield management profiles), they will be applied, or if you do not have any other floors, the standard second-price auction mechanics will apply.

As of 2017, only ask_price is used. API POST and PUT calls referencing floor_price and use_deal_floor will work as follows:

  • If the API call includes ask_price only, this is the value that will be used.
  • If the API call includes only a floor_price value, this value will be converted into the ask_price value.

0, if use_deal_floor is false

 

currency

enum

The currency for the floor_price. For a full list of available currencies, use the read-only Currency Service

"USD"

 

use_deal_floorBoolean

If true, the floor_price is applied for the deal.

When use_deal_floor is true, the deal's floor price overrides any other floors you may have, i.e., in placements or yield management profiles.

As of 2017, only ask_price is used. API POST and PUT calls referencing floor_price and use_deal_floor will work as follows:

  • If the API call includes ask_price only, this is the value that will be used.
  • If the API call includes only a floor_price value, this value will be converted into the ask_price value.
true 
last_modifiedtimestampRead-only. The date and time when the deal was last modified, in local time.  
data_protectedBoolean

If true, settings for allow_creative_add_on_view, allow_creative_add_on_click, and visibility_profile_id are used for this deal. If false, network and publisher settings are used.

false 
allow_creative_add_on_viewBooleanIf true, allow any creative to serve that adds users to a segment on view.false 
allow_creative_add_on_clickBooleanIf true, allow any creative to serve that adds users to a segment on click.true 
visibility_profile_idintThe unique ID of the visibility profile that will be applied to a deal. This ID can be retrieved from the Visibility Profile Service.  
size_preferencestring

Specifies how this deal handles private sizes. Private sizes are placement sizes (set in the private_sizes array in the Placement Service) that can be allowed to serve for a deal. There are two options:

  • standard: Private sizes are not available for this deal.
  • append: Private sizes can be used in addition to the specified placement size.

If a deal is created from a package, this setting is copied from the package to the deal.

  
audit_status_optionstring

Specifies how the deal handles creatives.

  • none: Creatives use existing ad quality settings.
  • provisional: Creatives in "pending" audit status will serve. Once these creatives are audited, the existing ad quality settings are used.
  • max_trust: No ad profile restrictions will be applied to this deal.

Creatives specifically listed in the Creatives object will override these settings.

none 
brand_restrictBoolean

Specifies whether the deal is restricted only to the brands listed in the Brands object.

  • true: Deal is restricted only to the listed brands.
  • false: Other brands are also allowed to serve.
true 
category_restrictBoolean

Specifies whether the deal is restricted only to the categories listed in the Categories object.

  • true: Deal is restricted only to the listed categories.
  • false: Other categories are also allowed to serve.
true 
language_restrictBoolean

Specifies whether the deal is restricted only to the languages listed in the Languages object.

  • true: Deal is restricted only to the listed languages.
  • false: Other languages are also allowed to serve.
true 
technical_attribute_restrictBoolean

Specifies whether the deal is restricted only to the technical attributes listed in the Technical Attributes object.

  • true: Deal is restricted only to the listed technical attributes.
  • false: Other technical attributes are also allowed to serve.
true 
created_bystringSpecifies whether this deal was created by the seller or the buyer (using the Deal From Package Service).  
sellerobjectRead-only. The selling member who is offering the deal. For more details, see Seller below.  
buyerobjectThe buying member who can target this deal. For more details, see Buyer below. POST
typeobject

The type of deal. For sellers, a deal can be an open auction or a private auction. For more details, see Type below.

  
auction_type objectThe auction type for the deal. A deal can have the following auction types: first price, second price, and fixed price. For more information, see Auction Type below.  
brandsarray of objects

The brands of creatives that are eligible for the deal. For more details, see Brands below.

null 
categoriesarray of objects

The categories that describe the creatives that are eligible for the deal. For more details, see Categories below.

  
languagesarray of objects

The language associated with creatives that are eligible for the deal. For more details, see Languages below.

  
technical_attributesarray of objects

The technical attributes of creatives that are eligible for the deal. For more details, see Technical Attributes below.

  
creativesarray of objects

A list of creatives that are specifically approved or banned for the deal. This list overrides any other ad quality setting. For more details, see Creatives below.

  
ask_pricedouble The floor_price plus the seller revenue share specified in your contract. This is the price shown to the buyer. It is the minimum they must bid in order to compete for the inventory.Auto-generated number 
priorityint

The bidding priority for deals when id in the type object = 2/Private Auction.

Possible values: 1 - 20, where 20 is the highest priority.

5 
payment_typestring

Specifies the payment type for the deal:

  • default: This deal uses the default payment type for the buyer of this deal. Includes CPM and may also include CPA, CPC, or both.
  • cpvm: This deal uses the Viewable CPM payment type. Only viewable impressions result in payment from the buyer.
default 
allowed_media_typesarray of objectsThe media types allowed for the deal. To learn more, see Allowed Media Types below.  
allowed_media_subtypesarray of objectsThe media subtypes allowed for the deal. To learn more, see Allowed Media Subtypes below.  
media_preferencestring

Specifies how this deal handles media types/subtypes. There are two options:

  • standard = use whatever media types are already on the auction (based on the placement settings)
  • append = include the media types on the auction + any private media types set on the placement

If a deal is created from a package, this setting is copied from the package to the deal.

 

 
adserver_lists
array of objectsEach object identifies an ad server list that will be applied to the deal. To learn more, see Ad Server Lists below.null 

Seller

The seller object contains the following fields.

Field

Type

Description

Default

Required On
id intRead-only. The member ID of the seller.Seller's member ID 
namestringRead-only. The member name of the seller.Seller's member name 

Buyer

The buyer object can be set on a POST, but cannot be updated with a PUT. If you want to change the buyer, you need to create a new deal.

The buyer object contains the following fields.

Field

Type

Description

Default

Required On

id intThe member ID of the buyer. POST
bidder_idintRead-only. The bidder ID of the member. For buyers, this will always be 2.  
namestringRead-only. The member name of the buyer.  

Type

The type object contains the following fields.

Field

Type (Length)

Description

Default

Required On

id int

The ID representing the type of deal. Possible values:

  • 1 = Open Auction
    In an "Open Auction", buyers targeting the deals and buyers targeting the inventory via other means compete for the impression. If a buyer targeting a deal submits the highest bid and the bid clears the deal's floor, that buyer wins the auction, paying either the second-highest bid or the deal floor price, whichever is higher. If one of the non-deal buyers submits the highest bid, that buyer wins the auction, paying either the second-highest bid or ECP, whichever is higher. 
  • 2 = Private Auction
    In a "Private Auction", buyers targeting the private deals compete for the impression first. Then, if none of the deal buyers win, the auction is opened to buyers targeting the inventory via other means. If a buyer targeting a deal submits a bid higher than the deal's floor and higher than any other private auction bids, that buyer wins the auction, paying either the second-highest bid from the private auction or the deal floor price, whichever is higher. If no private auction deals clear their floors, the highest bid in the open auction wins, paying either the second-highest bid from the open auction or ECP, whichever is higher.

 

1 
namestring (255)Read-only. The name of the type of deal. Possible values: "Open Auction" or "Private Auction"."Open Auction" 

Auction Type

The auction_type object contains the following fields.

Field

Type (Length)

Description

Default

Required On

id int

The ID of the auction type:

  • 1 = First price
  • 2 = Second price (default)
  • 3 = Fixed price
2 
namestringRead-only. The name of the auction type. Possible values: "first_price", "second_price" or "fixed_price"."second_price" 

Brands

Each brands object contains the following fields:

Field

Type

Description

Default

Required On

id intThe ID of the brand that is eligible for the deal. You can use the Brand Service to retrieve brand IDs.  
name stringThe name of the brand that is eligible for the deal.  
overrideBoolean

 Set to true to allow a brand to serve for a deal even if the ad quality profile would have blocked it.

false 

Allowed Media Types

You can use this array to limit the media type, the general display style of creatives, that can serve on placements that are part of this deal.

Each allowed_media_types object contains the following fields:

Field

Type

Description

Default

Required On

idintThe ID of the media type. PUT/POST
namestringThe name of the allowed media type, for example "Banner".  
media_type_group_idintThe group ID for the media type.  
uses_sizesenumWhether the media type has size specifications. Possible values:
  • always
  • sometimes
  • never
  
last_modifieddateWhen the allowed_media_type object was last updated.  

Allowed Media Subtypes

You can use this array to limit the media subtype, the specific display style of creatives, that can serve on placements that are part of this deal.

Each allowed_media_subtypes object contains the following fields:

Field

Type

Description

Default

Required On

permitted_sizesarray of objects

The permitted sizes for creatives of the media subtype. See Permitted Sizes below for more details. Note that not all media subtypes have permitted size requirements.

 PUT/POST
native_assetsarray of objects

An array describing constraints on elements of native ads for this media subtype. Elements of a native ad can include the title, body content, and more. The format's constraints could be whether body content is required or recommended, or how long the text may be. For more information, see Native Assets below.

  
idintThe ID of the allowed_media_subtype. PUT and POST on JSON file  
namestring

The name of the allowed_media_subtype.

  
last_modifieddateWhen the allowed_media_subtype array was last modified.  
mediatype_idintThe ID of the media_type.  
media_type_namestringThe name of the media_type.  
media_type_group_idintThe ID of the group for the media type.  

Permitted Sizes

Each permitted_sizes object contains the following fields:

Field

Type

Description

Default

Required On

platform_widthint

The actual rendering width, in pixels, for creatives of this media subtype. This is also the width that appears in reporting.

  
platform_heightintThe actual rendering height, in pixels, for creatives of this media subtype. This is also the height that appears in reporting.  
validate_image_sizebooleanIf true, the image for creatives of this media subtype will be validated against the requirements defined by the following fields in this object:scaling_permittedaspect_ratio_tolerancemin_image_width, max_image_widthmin_image_height, and max_image_height.  
scaling_permittedboolean

If true, the image for creatives of this media subtype must have the same aspect ratio as platform_width / platform_height.

If false, the image for creatives of this media subtype must have a width and height exactly matching platform_width and platform_height.

  
aspect_ratio_tolerancedouble

If validate_image_size and scaling_permitted are both true , the image can deviate from the aspect ratio of platform_width and platform_height by this amount. For example, the aspect ratio for a platform_width and platform_height of 254x133 is 1.19:1. If the aspect_ratio_tolerance is 0.03, an aspect ratio between 1.16:1 and 1.22:1 would be acceptable.

  
min_image_widthintIf validate_image_size is true, the minimum acceptable image width, in pixels, for creatives of this media subtype.  
max_image_widthintIf validate_image_size is true , the maximum acceptable image width, in pixels, for creatives of this media subtype.  
min_image_heightintIf validate_image_size is true , the minimum acceptable image height, in pixels, for creatives of this media subtype.  
max_image_heightintIf validate_image_size is true , the maximum acceptable image height, in pixels, for creatives of this media subtype.  

Native Assets

Each native_assets object contains the following fields:

Field

Type

Description

Default

Required On

native_asset_namestring

The title of the ad.

  
min_text_length int

The minimum length for the text.

  
max_text_length int

The maximum length for the text.

  
requirementenum 

Whether this asset is required by this particular media subtype. This field can contain several levels of "requiredness":

  • "required"
  • "recommended"
  • "optional"
  

Categories

Each categories object contains the following fields:

Field

Type

Description

Default

Required On

id intThe ID of the categories that is eligible for the deal. You can use the Category Service to retrieve category IDs.  
name stringThe name of the category that is eligible for the deal.  
overrideBoolean

 Set to true to allow a category to serve for a deal even if the ad quality profile would have blocked it.

false 

Languages

Each languages object contains the following fields:

Field

Type

Description

Default

Required On

id intThe ID of the language that is eligible for the deal. You can use the Language Service to retrieve language IDs.  
name stringThe name of the language that is eligible for the deal.  
overrideBoolean

 Set to true to allow a language to serve for a deal even if the ad quality profile would have blocked it.

false 

Technical Attributes

Each technical_attribute object contains the following fields:

Field

Type

Description

Default

Required On

id intThe ID of the technical attribute that is eligible for the deal. You can use the Technical Attribute Service to retrieve technical attribute IDs.  
name stringThe name of the technical attribute that is eligible for the deal.  
overrideBoolean

 Set to true to allow a technical attribute to serve for a deal even if the ad quality profile would have blocked it.

false 

Creatives

The creatives array is limited to 100 creatives. Each creatives object contains the following fields:

Field

Type

Description

Default

Required On

id intThe ID of the creative that is approved or banned for the deal. You can use the Creative Service to retrieve creative IDs.  
status string

Specifies how this creative will be handled for this deal.
 

  • approved: This creative can always serve in this deal, regardless of any other ad quality settings or overrides.
  • banned: This creative can never serve in this deal, regardless of any other ad quality settings or overrides.
  

Ad Server Lists

Each adserver_lists object contains the following fields.

Field

Type

Description

Default

Required On

id intThe ID of the ad server list that will be applied to this deal. POST
name string

The name of the ad server list.

  
override
booleanIf true, apply this ad server list to the deal.  

Examples

Add a private auction deal with a floor of $2.50
Add a private auction deal with no floor
 Modify a deal
Modify a deal to add overrides and ban certain creatives
 View all deals you have with buyers
 View a specific deal
 Delete a deal