Deal Buyer Access Service

Transcription

1 Deal Buyer Access Service Deal Buyer Access Service This read-only service lets buyers view information about the negotiated deals they have with Console 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. REST API JSON Fields Examples On This Page REST API View all deals you have with sellers: GET View all deals you have with a specific seller: GET View a specific deal: GET View multiple deals by ID using a comma-separated list: GET Search for a deal by name, ID, or code: GET ID, name, or code" Find out which fields you can filter and sort by: GET JSON Fields

2 Field Type (Length) Description id int The ID of the deal. code name description string (100) string (255) string (65535) 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. The name of the deal. 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".

3 floor_price double Deprecated. Refer to the ask_price fi eld instead. The minimum CPM value that the buyer must bid to be eligible for the deal. If use_deal_floor is false, flo or_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_price. For a full list of available currencies, use the read-only Currency Service. use_deal_floor Boolean 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_modified timestamp The date and time when the deal was last modified.

4 seller object The selling member who is offering the deal. For more details, see Seller below. buyer object The buying member who can target this deal. For more details, see Buyer below. type object The type of deal. For Console 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. brands categories languages technical_attributes array of objects array of objects array of objects array of objects The brands of creatives that are eligible for the deal. For more details, see Brand s below. The categories that describe the creatives that are eligible for the deal. For more details, see Categories below. The language associated with creatives that are eligible for the deal. For more details, see Languages below. The technical attributes of creatives that are eligible for the deal. For more details, see Technical Attributes below. ask_price int The price associated with the deal. This is the minimum amount the seller will accept for this inventory.

5 suggested_min_bid_price int 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 AppNexus contract. For deals with external suppliers, this amount will include additional margin to account for discrepancies. Bidding the suggested_min_bid_pri ce helps ensure that you are eligible for the deal but there is no guarantee that your bid will win. sizes array 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_preference string 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.

6 audit_status_option string 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 Creativ es object will override these settings. payment_type string 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. brand_restrict Boolean Specifies whether the deal is restricted only to the brands listed in the Brands obj ect. true: Deal is restricted only to the listed brands. false: Other brands are also allowed to serve.

7 category_restrict Boolean Specifies whether the deal is restricted only to the categories listed in the Catego ries object. true: Deal is restricted only to the listed categories. false: Other categories are also allowed to serve. language_restrict Boolean Specifies whether the deal is restricted only to the languages listed in the Langu ages object. true: Deal is restricted only to the listed languages. false: Other languages are also allowed to serve. technical_attribute_restrict Boolean 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. creatives array 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 int Read-only. The member ID of the seller.

8 name string Read-only. The member name of the seller. Buyer The buyer object contains the following fields. Field Type Description id int The member ID of the buyer. bidder_id int The bidder ID of the member. For Console buyers, this will always be 2. name string The member name of the buyer. Type The type object contains the following fields. Field Type (Length) Description

9 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. AppNexus as a buying platform can make no guarantee that first look deals actually give you the first look at an impression. For examples showing how these different types of auctions work, see Deal Auction Mechanics (customer login required). name string (255) The name of the type of deal. Possible values: "Open Auction", "Private Auction", or "First Look".

10 Brands Each brands object contains the following fields: Field Type Description id int The ID of the brand that is eligible for the deal. You can use the Brand Service to retrieve brand IDs. name string The name of the brand that is eligible for the deal. override Boolean 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 int The ID of the categories that is eligible for the deal. You can use the C ategory Service to retrieve category IDs. name string The name of the category that is eligible for the deal. override Boolean 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 int The ID of the language that is eligible for the deal. You can use the La nguage Service to retrieve language IDs. name string The name of the language that is eligible for the deal. override Boolean If set to true, a language can serve for a deal even if the ad quality profile would have blocked it.

11 Technical Attributes Each technical_attribute object contains the following fields: Field Type Description id int The ID of the technical attribute that is eligible for the deal. You can use the Technical Attribute Service to retrieve technical attribute IDs. name string The name of the technical attribute that is eligible for the deal. override Boolean 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 int The 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. Sizes Each object in the size_targets array contains the following fields. Field Type Description width string The width of the creative. height string The height of the creative. Examples

12 >> View all deals you have with sellers $ curl -b cookies -c cookies ' "response": "status": "OK", "count": 6, "start_element": 0, "num_elements": 100, "deals": [ "id": 62, "code": null, "name": "Private deal for buyer 1085 with floor of 2.5", "description": null, "active": false, "start_date": " :00:00", "end_date": " :59:59", "floor_price": 2.5, "currency": "USD", "use_deal_floor": true, "last_modified": " :15:38", "seller": "id": , "name": "Seller 123" "buyer": "id": , "bidder_id": 2, "name": "Buyer 123" "type": "id": 2, "name": "Private Auction" "brands": [ "id": 1, "name": "Example Brand" "ask_price": 2.75, "suggested_min_bid_price": 3, "sizes": [ "width": "300", "height": "250" ] "id": 63, "code": null, "name": "Private deal for buyer 1085 with floor of $2.50", "description": null, "active": false, "start_date": " :00:00", "end_date": " :59:59",

13 "floor_price": 2.5, "currency": "USD", "use_deal_floor": true, "last_modified": " :39:57", "seller": "id": , "name": "Seller 456" "buyer": "id": , "bidder_id": 2, "name": "Buyer 456" "type": "id": 2, "name": "Private Auction" "brands": [ "id": 1, "name": "Example Brand" ]... ]

14 >> View all deals you have with a specific seller

15 $ curl -b cookies -c cookies ' "response": "status": "OK", "count": 1, "start_element": 0, "num_elements": 100, "deals": [ "id": 63, "code": null, "name": "Private deal for buyer 1085 with floor of $2.50", "description": null, "active": false, "start_date": " :00:00", "end_date": " :59:59", "floor_price": 2.5, "currency": "USD", "use_deal_floor": true, "last_modified": " :39:57", "seller": "id": , "name": "Seller 456" "buyer": "id": , "bidder_id": 2, "name": "Buyer 456" "type": "id": 2, "name": "Private Auction" "brands": [ "id": 1, "name": "Example Brand" ], "ask_price": 2.75, "suggested_min_bid_price": 3, "sizes": [ "width": "300", "height": "250" ] ] >> View a specific deal

16 $ curl -b cookies -c cookies ' "response": "status": "OK", "count": 1, "start_element": 0, "num_elements": 100, "deal": "deals": "id": 63, "code": null, "name": "Private deal for buyer 1085 with floor of $2.50", "description": null, "active": false, "start_date": " :00:00", "end_date": " :59:59", "floor_price": 2.5, "currency": "USD", "use_deal_floor": true, "last_modified": " :39:57", "seller": "id": , "name": "Seller 456" "buyer": "id": , "bidder_id": 2, "name": "Buyer 456" "type": "id": 2, "name": "Private Auction" "brands": [ "id": 1, "name": "Example Brand" ], "ask_price": 2.75, "suggested_min_bid_price": 3, "sizes": [ "width": "300", "height": "250" ] >> View all deals that have not expired In this example, assuming today is December 4, 2013, we want to find all deals that have not expired. To do this, we pass the min_end_date=" :00:00" filter in the query string. Note, however, that deals with no end date will not show up in the response.

17 $ curl -b cookies -c cookies ' 00:00:00"' "response": "status": "OK", "count": 4, "start_element": 0, "num_elements": 100, "deals": [ "id": 60, "code": null, "name": null, "description": null, "active": true, "start_date": " :00:00", "end_date": " :59:00", "floor_price": 3.2, "currency": "USD", "use_deal_floor": true, "last_modified": " :47:39", "seller": "id": , "name": "Seller 456" "buyer": "id": , "bidder_id": 2, "name": "Buyer 456" "type": "id": 2, "name": "Private Auction" "brands": null, "ask_price": 3.5, "suggested_min_bid_price": 3.75, "id": 62, "code": null, "name": "Private deal for buyer 1085 with floor of 2.5", "description": null, "active": false, "seller_member_id": 1066, "start_date": " :00:00", "end_date": " :59:59", "profile_id": null, "floor_price": 2.5, "currency": "USD", "use_deal_floor": true, "last_modified": " :15:38", "seller": "id": , "name": "Seller 456" "buyer":

18 "id": , "bidder_id": 2, "name": "Buyer 456" "type": "id": 2, "name": "Private Auction" "brands": [ "id": 1, "name": "Example Brand" ]... ]

19