Digital Platform API - Deal Buyer Access service

Article
03/06/2024

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.

REST API

HTTP Method	Endpoint	Description
`GET`	`https://api.appnexus.com/deal-buyer-access`	View all deals you have with sellers
`GET`	`https://api.appnexus.com/deal-buyer-access?seller_member_id=SELLER_MEMBER_ID`	View all deals you have with a specific seller
`GET`	`https://api.appnexus.com/deal-buyer-access?id=DEAL_ID`	View a specific deal
`GET`	`https://api.appnexus.com/deal-buyer-access?id=1,2,3`	View multiple deals by ID using a comma-separated list
`GET`	`https://api.adnxs.com/deal-buyer-access?search="Deal_ID,DEAL_NAME,orCODE"`	Search for a deal by name, ID, or code
`GET`	`https://api.appnexus.com/deal-buyer-access/meta`	Find out which fields you can filter and sort by

JSON fields

Field	Type (Length)	Description
`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`).
`ask_price`	int	The price associated with the deal. This is the minimum amount the seller will accept for this inventory.
`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 Creatives object will override these settings.
`brands`	array of objects	The brands of creatives that are eligible for the deal. For more details, see Brands below.
`brand_restrict`	Boolean	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.
`buyer`	object	The buying member who can target this deal. For more details, see Buyer below.
`categories`	array of objects	The categories that describe the creatives that are eligible for the deal. For more details, see Categories below.
`category_restrict`	Boolean	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.
`code`	string (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.
`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.
`currency`	enum	The currency for the `floor_price`. For a full list of available currencies, use the read-only Currency Service.
`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.
`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. Note: 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.
`id`	int	The ID of the deal.
`languages`	array of objects	The language associated with creatives that are eligible for the deal. For more details, see Languages below.
`language_restrict`	Boolean	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.
`last_modified`	timestamp	The date and time when the deal was last modified.
`name`	string (255)	The name of the deal.
`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.
`seller`	object	The selling member who is offering the deal. For more details, see Seller below.
`sizes`	array of objects	The sizes of creatives that are eligible for the deal. For more details, see Size Targets below. Note: 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.
`start_date`	timestamp	The day and time when the deal starts being available to the buyer. Null corresponds to "immediately".
`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 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.
`technical_attributes`	array of objects	The technical attributes of creatives that are eligible for the deal. For more details, see Technical Attributes below.
`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.
`type`	object	The type of deal. For 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.
`use_deal_floor`	Boolean	If true, the `floor_price` is applied for the deal. Note: 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.

Seller

Field	Type	Description
`id`	int	Read-only. The member ID of the seller.
`name`	string	Read-only. The member name of the seller.

Buyer

Field	Type	Description
`id`	int	The member ID of the buyer.
`bidder_id`	int	The bidder ID of the member. For Xandr's UI 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
`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.
`name`	string (255)	The name of the type of deal. Possible values: - `"Open Auction"` - `"Private Auction"` - `"First Look"`.

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.

Field	Type	Description
`id`	int	The ID of the categories that is eligible for the deal. You can use the Category 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 Language 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.

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

View all deals you have with sellers

$ curl -b cookies -c cookies 'https://api.appnexus.com/deal-buyer-access'
{ 
    "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": "2013-12-01 00:00:00",
                "end_date": "2013-12-31 23:59:59",
                "floor_price": 2.5,
                "currency": "USD",
                "use_deal_floor": true,
                "last_modified": "2013-12-04 20:15:38",
                "seller": {
                    "id": 100004,
                    "name": "Seller 123"
                },
                "buyer": {
                    "id": 100005,
                    "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": "2013-12-01 00:00:00",
                "end_date": "2013-12-31 23:59:59",
                "floor_price": 2.5,
                "currency": "USD",
                "use_deal_floor": true,
                "last_modified": "2013-12-04 20:39:57",
                "seller": {
                    "id": 100006,
                    "name": "Seller 456"
                },
                "buyer": {
                    "id": 100007,
                    "bidder_id": 2,
                    "name": "Buyer 456"
                },
                "type": {
                    "id": 2,
                    "name": "Private Auction"
                },
                "brands": [
                    {
                        "id": 1,
                                                "name": "Example Brand"
                    }
                ]
            },
            ...
        ]
    }
}

View all deals you have with a specific seller

$ curl -b cookies -c cookies 'https://api.appnexus.com/deal-buyer-access?seller_member_id=100006'
{
    "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": "2013-12-01 00:00:00",
                "end_date": "2013-12-31 23:59:59",
                "floor_price": 2.5,
                "currency": "USD",
                "use_deal_floor": true,
                "last_modified": "2013-12-04 20:39:57",
                "seller": {
                    "id": 100006,
                    "name": "Seller 456"
                },
                "buyer": {
                    "id": 100007,
                    "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

$ curl -b cookies -c cookies 'https://api.appnexus.com/deal-buyer-access?id=63'
{
    "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": "2013-12-01 00:00:00",
            "end_date": "2013-12-31 23:59:59",
            "floor_price": 2.5,
            "currency": "USD",
            "use_deal_floor": true,
            "last_modified": "2013-12-04 20:39:57",
            "seller": {
                "id": 100006,
                "name": "Seller 456"
            },
            "buyer": {
                "id": 100007,
                "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, 2018, we want to find all deals that have not expired. To do this, we pass the min_end_date=2018-12-04 filter in the query string. Note, however, that deals with no end date will not show up in the response.

$ curl -b cookies -c cookies 'https://api.appnexus.com/deal-buyer-access?min_end_date=2018-12-04'
{
    "response": {
        "status": "OK",
        "count": 4,
        "start_element": 0,
        "num_elements": 100,
        "deals": [
            {
                "id": 60,
                "code": null,
                "name": null,
                "description": null,
                "active": true,
                "start_date": "2018-12-01 00:00:00",
                "end_date": "2018-12-31 23:59:00",
                "floor_price": 3.2,
                "currency": "USD",
                "use_deal_floor": true,
                "last_modified": "2018-12-04 18:47:39",
                "seller": {
                    "id": 100006,
                    "name": "Seller 456"
                },
                "buyer": {
                    "id": 100007,
                    "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": "2018-12-01 00:00:00",
                "end_date": "2018-12-31 23:59:59",
                "profile_id": null,
                "floor_price": 2.5,
                "currency": "USD",
                "use_deal_floor": true,
                "last_modified": "2018-12-04 20:15:38",
                "seller": {
                    "id": 100006,
                    "name": "Seller 456"
                },
                "buyer": {
                    "id": 100007,
                    "bidder_id": 2,
                    "name": "Buyer 456"
                },
                "type": {
                    "id": 2,
                    "name": "Private Auction"
                },
                "brands": [
                    {
                        "id": 1,
                                                "name": "Example Brand"
                    }
                ]
            },
            ...
        ]
    }
}

Partager via