V1 Deals API for Buyers

Warning

In Q3 2024, we will begin gradually phasing out of the Deals API v1.0, starting with sunsetting the POST method. Please follow the Deals API for Buyers V1 to V2 Migration Guide.

The API enables you to programmatically update and negotiate deals with Suppliers.

Important

• Deals are only created by Suppliers, therefore your can only update existing deals.

• The maximum number of deals objects per post or put request is 50.

Syncing Deal Data

It is expected that to receive updated information your system should make regular get requests to the Deals API. The Deals API will not push data to your system. To get the details of your deals, make regular get requests to this endpoint, which will return all of your deal details.

<!-- GET this endpoint where the <dsp-id> is the BidSwitch Seat ID -->
<!-- and <version> is v1 or v2 -->
https://my.bidswitch.com/api/v1/dsp/<dsp-id>/deals/

v1 Deals GET response example

{   
    "deals": [
        {
            "deal_id": "id:123:yolo-campaign",
            "display_name": "Deal Busters",
            "ssp_name": "exampleSSP",
            "buyers": [
                "abc",
                "def"
            ],
            "inventory_source": [
                "pub-123",
                "pub-321"
            ],
            "contact_email": "someone@example.com",
            "guaranteed_units_purchased_count": 23000,
            "start_time": "2019-10-02T15:01:23.045123456Z",
            "end_time": "2019-11-02T15:01:23.045123456Z",
            "dsp_update_time": "2019-11-02T15:01:43.045123456Z",
            "ssp_update_time": "2019-11-02T15:01:43.045123456Z",
            "deal_type": "private_auction",
            "contract_type": "guaranteed",
            "dsp_deal_status": "active",
            "price_method": "cpm",
            "price": 5432.12,
            "currency_code": "usd",
            "price_type": "auction",
            "bid_floor": 2.678,
            "revision_id": 3,
            "creative_type": "video",
            "display_sizes": [
                {
                    "w": 320,
                    "h": 70
                },
                {
                    "w": 80,
                    "h": 250
                }
            ],
            "duration": 15,
            "duration_match": "equals_to_duration",
            "skippable": "skippable"
        }
    ]
}

Updating a Deal

To update an existing deal, PUT the changes to the Deals API, ensuring you specify the correct "deal_id" and changes in the request body.

<!-- PUT to this endpoint where the <dsp-id> is your BidSwitch Seat ID -->
<!-- and <version> is v1 or v2 -->
https://my.bidswitch.com/api/v1/dsp/<dsp-id>/deals/

Deals PUT update example

{
  "deals": [
    {
      "deal_id": "id:123:playoff-campaign",
      "display_name": "Deal Busters",
      "ssp_name": "abc-123",
      "ssp_bid_request_name": "rubicon",
      "buyers": [
        "abc",
        "def"
      ],
      "inventory_source": [
        "pub-123"
      ],
      "contact_email": "someone@example.com",
      "guaranteed_units_purchased_count": 23000,
      "start_time": "2019-10-02T15:01:23.045123456Z",
      "end_time": "2019-11-02T15:01:23.045123456Z",
      "ssp_deal_status": "active",
      "price": 5432.12,
      "currency_code": "usd",
      "price_type": "auction",
      "price_method": "cpm",
      "bid_floor": 2.678,
      "deal_type": "private_auction",
      "contract_type": "guaranteed",
      "creative_type": "video",
      "display_sizes": [
        {
          "w": 320,
          "h": 70
        },
        {
          "w": 80,
          "h": 250
        }
      ],
      "duration": 15,
      "duration_match": "equals_to_duration",
      "skippable": "skippable"
    }
  ]
}

Request/Response Fields

Deals API Fields

Field	Type	Description
deals	array of objects	(Required) Contains an array of deals and their relevant information
deal_id	string	(Required) This is the deal ID which will be sent in bid requests, e.g. "deal-877-twttx". Note: It has a maximum character limit of 256 and you cannot use any of the following symbols in the Deal ID, as doing so will result in request invalidation: , # % $ @ * & ? ! ` ~ " ' / \ | ( ) { } [ ]+ = ^ :
display_name	string	(Optional) This is the name of the deal which will be shown in the Supplier UI, e.g. "Some Deal. In App Only". Only alphanumeric symbols and a period allowed.
ssp_name	string	(Optional) Specifies the Supplier ID to whom you wish to send this deal, e.g "dish"
ssp_bid_request_name	string	(Required. DSP Only) Specifies the Supplier name that will be passed in the bid request, this maps to the ext.ssp in the BidSwitch protocol
buyers	array of strings	(Optional) Specifies the Advertiser/Agencies in your system that should have access to this deal, e.g. ["buyer_id_123", "buyer_id_254"]
inventory_source	array of strings	(Optional) The ads.txt ID for the publisher(s) from whom the deal inventory is sourced. This helps to ensure the ads.txt authorization status is correct for deals verification on both ends within real time trading and during negotiations. Only alphanumeric symbols and a period, colon, underscore, space, and dash are allowed [a-zA-Z0-9-_: .], e.g. pub-id-1642, pub-id-1776. Each inventory source name has a maximum length of 250 characters.
contact_email	string	(Response Only) Supplier contact details e.g. "email@example.com"
guaranteed_units_purchased_count	int	(Optional) For guaranteed deals, specifies the minimum number of impressions guaranteed by the Supplier e.g. 23000. Should be 0 if contract type is non-guaranteed.
contract_type	string	(Optional) Specifies the contract type, the possible values are: "guaranteed": A deal with a guarantee around certain delivery terms "non-guaranteed": A deal without any delivery terms guaranteed
start_time	string	(Optional) Specifies the start time of the deal, the format uses RFC3339, and the default time zone is UTC, e.g. "2019-10-02T15:01:23.045123456Z".
end_time	string	(Optional) Specifies the end time of the deal, the format uses RFC3339, and the default time zone is UTC, e.g. "2019-10-02T15:01:23.045123456Z". The end time must be at least 1 hour in the future from the time of the request.
ssp_update_time	string	(Response Only) Specifies the time when the inventory source was last updated, the format uses RFC3339, and the default time zone is UTC, e.g. "2019-10-02T15:01:23.045123456Z"
dsp_update_time	string	(Response Only) Specifies the time when the Buyer last updated the deal status, the format uses RFC3339, and the default time zone is UTC, e.g. "2019-10-02T15:01:23.045123456Z"
ssp_deal_status	string	(Response Only) Indicates the status of the Deal on the Supplier side. Can take the following values: "active" "paused"
dsp_deal_status	string	(Required) Indicates the status of the Deal on the Buyer side. Can take the following values: "created_in_bidswitch": Deal was created in BidSwitch and awaiting upload to the Buyer. "created_in_dsp": Deal was pushed to the Buyer and awaiting approval in the DSP UI or for them to create a line items. "error_in_dsp": An error occurred while pushing the deal to the Buyer. "active": Deal status active. Line item assigned, valid creative assigned. "pending": Deal status pending. In some DSP this status means deal is not active and there is certain action needed for the buyer. "paused": Deal paused by buyer.
currency_code	string	(Optional) The currency code in ISO 4217, e.g. "usd"
price	float	(Optional) Represents an amount of money for a fixed price deal, for fixed price auctions it should be equal to the bid floor, e.g. 5.22. Either bid_floor or price must be a positive value A non-zero price is required for a fixed price auction, for a variable price auction you may set the price to 0
bid_floor	float	(Optional) Specifies the bid floor for this deal at auction. For fixed price deals this specifies the deal price, e.g. 5.22. Either bid_floor or price must be a positive value A non-zero bid_floor is required for a variable price auction, for a fixed price auction this value must match the price value
price_type	string	(Optional) Indicated whether the price is fixed or set at auction, the valid values are: "fixed" "auction" Note: If a deal has been created by an advertiser in DV360, when uploading the deal information to BidSwitch the price type must match.
price_method	string	(Optional) Indicates the pricing method, the only possible value is "cpm"
deal_type	string	(Optional) Indicates the deal type, these are the possible values. "private_auction": means that the imp.pmp.private_auction request value will be 1 "open_auction": means that the imp.pmp.private_auction request value will be 0
creative_type	string	(Optional) Indicates the acceptable creative type for this deal, the possible values are: "display" "video" "audio" "native"
display_sizes	array of objects	(Optional) An array of objects indicating the possible ad slot sizes, e.g. [{"w":320, "h":70}]
duration	float	Optional for Video/Audio The duration of the video/audio creative in seconds, e.g. 10.5
duration_match	string	(Optional for video/audio) Indicates whether the creative duration meets the required duration, the possible values are: "equals_to_duration" The creative duration needs to be the same as the required duration "less_than_or_equals_to_duration" The creative duration needs to be the same as or less than required duration
skippable	string	(Optional for video/audio) Indicates if the video/audio can be skipped, the possible values are "skippable": The creative must be skippable. "non-skippable": The creative must be non-skippable. "any": Can be either
dsp_note	string	(Optional) Passes information from the Buyer to Supplier. This is a read-only field for Suppliers and may only be changed by Buyers, e.g. "Could you lower the price from $5 to $3"
revision_id	integer	This is a read-only field generated by BidSwitch. When a Supplier changes the value of any field(s), excluding the ssp_deal_status field, the revision_id is incremented. This field displays the latest revision logged with BidSwitch and indicates the total number of revisions the deal has been through.

Standard HTTP responses

• 403 Forbidden The client does not have access rights to the content

• 404 Not Found The server can not find the requested resource, even if the endpoint is valid