Skip to end of metadata
Go to start of metadata

Deal Buyer Access Service

This read-only service lets buyers view information about the negotiated deals they have with Xandr's UI sellers and external supply partners. A deal may provide a buyer preferential pricing, access to exclusive inventory, reduced competition on inventory, or other opportunities. Each deal is valid for a single buyer, but note that inventory included in a deal may be encompassed by deals with other buyers as well.

Buyers can use the deal_targets field in the Profile Service to target deals. Sellers can use the Deal Service to set up and manage deals.

On This Page

REST API

View all deals you have with sellers:

View all deals you have with a specific seller:

 View a specific deal:

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

Search for a deal by name, ID, or code:

Find out which fields you can filter and sort by:

JSON Fields

Field

Type (Length)

Description

id

intThe ID of the deal.
codestring (100)The custom code for the deal. For deals with external supply partners, this is generally the string that you will use to identify the deal.

name

string (255)The name of the deal.

description

string (65535)The description of the deal. For deals with external supply partners, the description may provide additional insight or details about the deal.

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).

start_date

timestamp

The day and time when the deal starts being available to the buyer. Null corresponds to "immediately".

end_date

timestamp

The day and time when the deal stops being available to the buyer. Null corresponds to "indefinitely".

floor_price

double

Deprecated. Refer to the ask_price field instead. The minimum CPM value that the buyer must bid to be eligible for the deal.

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

currency

enum

The currency for the floor_priceFor a full list of available currencies, use the read-only Currency Service
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 the seller may have, i.e., in placements or yield management profiles.

last_modifiedtimestampThe date and time when the deal was last modified.
sellerobjectThe 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.
typeobject

The type of deal. For Xandr's UI sellers, a deal can be an open auction or a private auction. For external supply partners, a deal can also be first-look access. For more details, see Type below.

brandsarray of objects

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

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.

ask_priceintThe  price associated with the deal. This is the minimum amount the seller will accept for this inventory.
suggested_min_bid_priceint

The minimum amount that will likely clear the ask price. This is the sum of the ask_price and the auction service charge specified in your Xandr contract. For deals with external suppliers, this amount will include additional margin to account for discrepancies.

Bidding the suggested_min_bid_price helps ensure that you are eligible for the deal but there is no guarantee that your bid will win.

sizesarray of objects

The sizes of creatives that are eligible for the deal. For more details, see Size Targets below.

If this array is not present in the response, there are no creative size requirements for the deal.

size_preferencestring

Specifies how this deal handles private sizes. Private sizes are placement sizes that a seller can allow 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.
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: Any creative is allowed to serve for this deal.

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

payment_typestringSpecifies 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.
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.
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.
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.
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.
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.

Seller

The seller object contains the following fields.

Field

Type

Description

id intRead-only. The member ID of the seller.
namestringRead-only. The member name of the seller.

Buyer

The buyer object contains the following fields.

Field

Type

Description

id intThe member ID of the buyer.
bidder_idintThe bidder ID of the member. For Xandr's UI buyers, this will always be 2.
namestringThe member name of the buyer.

Type

The type object contains the following fields.

Field

Type (Length)

Description

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.
  • 3 = First Look
    Deals considered "First Look" are offered only by external supply partners and have extremely varied auction logic depending on both the supply partner and the seller. You must contact the supply partner for details about how the deal works. Xandr as a buying platform can make no guarantee that first look deals actually give you the first look at an impression. 
namestring (255)The name of the type of deal. Possible values: "Open Auction", "Private Auction", or "First Look".

Brands

Each brands object contains the following fields:

Field

Type

Description

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

 If set to true, a brand can serve for a deal even if the ad quality profile would have blocked it.

Categories

Each categories object contains the following fields:

Field

Type

Description

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

 If set to true, a category can serve for a deal even if the ad quality profile would have blocked it.

Languages

Each languages object contains the following fields:

Field

Type

Description

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

 If set to true, a language can serve for a deal even if the ad quality profile would have blocked it.

Technical Attributes

Each technical_attribute object contains the following fields:

Field

Type

Description

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.
namestringThe name of the technical attribute that is eligible for the deal.
overrideBoolean

 If set to true, a technical attribute can serve for a deal even if the ad quality profile would have blocked it.

Creatives

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

Field

Type

Description

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

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.

Sizes

Each object in the size_targets array contains the following fields.

Field

Type

Description

width stringThe width of the creative.
heightstringThe height of the creative.

Examples

 View all deals you have with sellers
 View all deals you have with a specific seller
 View a specific deal
 View all deals that have not expired
  • No labels