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.

Note

The 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 Seller Restricted Targeting can use the deal_targets field in the Profile Service.

REST API

HTTP Method	Endpoint	Description
`GET`	https://api.appnexus.com/deal	View all deals you have with buyers.
`GET`	https://api.appnexus.com/deal?id=DEAL_ID	View a specific deal.
`GET`	https://api.appnexus.com/deal?id=1,2,3	View multiple deals by ID using a comma-separated list.
`GET`	https://api.appnexus.com/deal/meta	Find out which fields you can filter and sort by.
`POST`	https://api.appnexus.com/deal	Add a new deal.
`PUT`	https://api.appnexus.com/deal?id=DEAL_ID	Modify an existing deal.
`DELETE`	https://api.appnexus.com/deal?id=DEAL_ID	Delete a deal. Warning: 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.

JSON fields

Field	Type (Length)	Description
`active`	boolean	If `true`, the deal is active. Default: `true` Note: 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`).
`adserver_lists`	array of objects	Each object identifies an ad server list that will be applied to the deal. To learn more, see Ad Server Lists below. Default: `null`
`allow_creative_add_on_click`	boolean	If `true`, allow any creative to serve that adds users to a segment on click. Default: `true`
`allow_creative_add_on_view`	boolean	If `true`, allow any creative to serve that adds users to a segment on view. Default: `false`
`allowed_media_subtypes`	array of objects	The media subtypes allowed for the deal. To learn more, see Allowed Media Subtypes below.
`allowed_media_types`	array of objects	The media types allowed for the deal. To learn more, see Allowed Media Types below.
`ask_price`	double	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. Note: This field is required for Programmatic Guaranteed deals and is the agreed upon price between the seller and the buyer. Required On: `PUT` and `POST` Default: auto-generated number
`auction_type`	object	The 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.
`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`: No ad profile restrictions will be applied to this deal. Creatives specifically listed in the Creatives object will override these settings. Default: `none`
`brands`	array of objects	The brands of creatives that are eligible for the deal. For more details, see Brands below. Default: null
`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. Default: `true`
`buyer`	object	The buying bidder and member who can target this deal. A deal will only ever use the `buyer` field or the `buyer_seats` field, not both. For more details, see Buyer below. Required On: `POST`
`buyer_seats`	object	The buying bidder and seat who can target this deal. A deal will only ever use the `buyer` field or the `buyer_seats` field, not both. For more details, see Buyer Seats below.
`buyer_bidders`	object	The buying bidder who can target this deal. For more details, see Buyer Bidders below. Default: `null`
`buyer_members`	object	The Xandr member ID of the buyer who can target this deal. For more details, see Buyer Members below. Default: `null`
`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. Default: `true`
`code`	string (100)	The custom code for the deal. Note: This field is mandatory and represents your internal deal ID, passed in the bid request through the PMP's object deal ID field. Required On: `POST` Default: `null`
`created_by`	string	Specifies whether this deal was created by the seller or the buyer (using the Deal From Package Service).
`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. Default: `"USD"`
`data_protected`	boolean	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. Default: `false`
`description`	string (65535)	The description of the deal. You can use this field to provide the buyer additional insight or details about the deal. Default: `null`
`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"`. Default: `null` (immediately)
`floor_price`	double	The minimum CPM value that the buyer must bid to be eligible for the deal. Note: - 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. Default: `0`, if `use_deal_floor` is `false`
`id`	int	The ID of the deal. Required On: `PUT` and `DELETE` Default: auto-incremented number
`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. Default: `true`
`last_modified`	timestamp	Read Only. The date and time when the deal was last modified, in local time.
`media_preference`	string	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.
`name`	string (255)	The name of the deal. Default: `null`
`package_id`	int	The package ID for the package from which the deal was created, if applicable. See Deal From Package Service. Default: `null`
`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. Default: `default`
`priority`	int	The bidding priority for deals when `id` in the `type` object = `2`/Private Auction. Possible values: `1` - `20`, where `20` is the highest priority. Default: `5`
`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. Warning: Any other targeting settings in the associated profile will not be respected. Default: `null`
`seller`	object	Read Only. The selling member who is offering the deal. For more details, see Seller below.
`size_preference`	string	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.
`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"`. Default: `null` (immediately)
`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. Default: `true`
`type`	object	The type of deal. For sellers, a deal can be an open auction or a private auction. 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 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. Default: `true`
`version`	int	Specifies the version of the deal object. Possible values are: `1` = External supply partner deals and legacy Monetize setups `2` = Monetize seller deals Required On: `POST` Default: `1`
`visibility_profile_id`	int	The unique ID of the visibility profile that will be applied to a deal. This ID can be retrieved from the Visibility Profile Service.
`line_item_ids`	array of int	A list consists of line items' IDs present in a deal. This array is filled when deal version is 2, otherwise this is a null array. This is a read-only field returned in a `GET` request.
`seller_targeting_restriction`	object	Indicates whether the deal restricts which attributes an Invest buyer can target whilst also targeting this deal. See Seller Restricted Targeting below.
`is_archived`	Boolean	True if the deal has been archived. Archived deals do not participate in auctions and do not generate bid requests. However, they continue to be available in the UI, via APIs and in reporting. Default: `false`

Seller

The seller object contains the following fields:

Field	Type	Description
`id`	int	- Read Only. - Seller's member ID The member ID of the seller.
`name`	string	- Read Only. - Seller's member name The member name of the seller.

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
`id`	int	The member ID of the buyer. Required On: `POST`
`bidder_id`	int	Read Only. The bidder ID of the member. For buyers, this will always be `2`.
`name`	string	Read Only. The member name of the buyer.

Example of the buyer object

"buyer": {
                "bidder_id": 2,
                "bidder_name": "Microsoft Invest",
                "id": 9155,
                "name": "Hearts & Science (AT&T)"
            },
"buyer_seats": null

Buyer bidders

The buyer_bidders object can be set on a POST, and can be updated with a PUT. When a seller is enabled for multi-buyer deals. the buyer_bidders object can be set in combination with buyer_seats and buyer_members.

The buyer_bidders object contains the following fields:

Field	Type	Description
`bidder_name`	string	Read Only. The name of the bidder.
`id`	int	The bidder ID of the buyer. The bidder ID is `2`. Required On: `POST`

Example of the buyer_bidders object

"buyer_bidders": [{
    "bidder_id": 1,
    "bidder_name": "Example Bidder"
}],

Buyer members

The buyer_members object can be set on a POST, and can be updated with a PUT. When a seller is enabled for multi-buyer deals, the buyer_members object can be set in combination with buyer_seats and buyer_bidders.

The buyer_members object contains the following fields:

Field	Type	Description
`bidder_id`	int	Read Only. The bidder ID of the member. For Invest buyers, this will always be `2`.
`bidder_name`	string	Read Only. The name of the bidder.
`id`	int	The member ID of the buyer. Required On: `POST`
`name`	string	Read Only. The member name of the buyer.

Example of the buyer_members object

"buyer_members": [{
    "bidder_id": 1,
    "bidder_name": "Example Bidder",
    "id": "456",
    "name": "Example Buyer Member"
}],

Buyer seats

Deals with seats can be set up using the buyer_seats object via the API.

When a new deal is set up via with, the API will be populated with the buyer_seats object. You can use the Invest buyer's member ID in the code field as well as bidder_id. New deals with external DSPs can also be set up with buyer seat IDs. You can check which external DSPs are using buyer seat IDs here.