BidSwitch Deals API for Buyers

The BidSwitch Deals API integrates with Deal Management APIs of Suppliers that are connected to BidSwitch, allowing BidSwitch connected Buyers to receive private or open deals data through just one API integration.

BidSwitch will parse the submitted Deals information from various Suppliers and route the appropriate Deals to you. This will allow you to ingest the Deals data into your own Deals Management Platform and present them to the Advertiser or Agencies that use your systems. The purpose of such systems integrations is to improve the trading volume and execution of deals by ensuring details are correct so that at time of delivery there should be no technical impediments to prevent the deal from running successfully.

Usage Overview

  1. Get your API Access Token, which will be passed in the request header. If you do not have an API token or user account, use the steps outlined in the API Authorization section. The following user permissions are applied to API functionality:

    • All API methods allowed: API Account

    • GET only: Read Only

  2. Push/pull deal details to the Deals API, specifying the relevant Supplier.

  3. BidSwitch will parse the details and submit them to the Supplier.

  4. Your system should pull regularly from the Deals API to get updates from Suppliers.

../_images/deals-api-dsp-presentation.png

Data Syncing

It is expected that to receive updated information your system will 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 a get request to this endpoint, which will return your deal details.

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

Updating a Deal

Note

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

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

To update an existing deal, put the details to Deals API, ensuring you specify the correct "deal_id" and changes.

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

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: Do not use any of the following symbols in the Deal ID, as doing so will result in request invalidation:

, # % $ @ * & ? ! ` ~ " ' / \ | ( ) { } [ ]+ = ^ :

display_name

string

(Required) 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_id

string

(Required) 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

(Required) Specifies the Advertiser/Agencies that should have access to this deal, e.g. ["GetYourGuide", "booking"]

inventory_source

string

(Required) The display name of the inventory source. Only alphanumeric symbols and a period, colon, underscore, space, and dash are allowed [a-zA-Z0-9-_: .], e.g. "Some Publisher."

ssp_name

string

(Response Only) Specifies the Supplier name to whom you wish to sent this deal, e.g. "Dish Networks"

contact_email

string

(Response Only) Supplier contact details e.g. "email@example.com"

guaranteed_units_purchased_count

int

(Required) 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

(Required) 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

(Required) 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". The start date must be at least 1 hour in the future from the time of the request.

end_time

string

(Required) 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 date should be no later than 2036.

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

(Required) The currency code in ISO 4217, e.g. "usd"

price

float

(Required) 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

(Required) 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

(Required) Indicated whether the price is fixed or set at auction, the valid values are:

  • "fixed"

  • "auction"

price_method

string

(Required) Indicates the pricing method, the only possible value is "cpm"

deal_type

string

(Required) 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

(Required) Indicates the acceptable creative type for this deal, the possible values are:

  • "display"

  • "video"

  • "audio"

  • "native"

display_sizes

array of objects

(Required) An array of objects indicating the possible ad slot sizes, e.g. [{"w":320, "h":70}]

duration

float

Required for Video/Audio The duration of the video/audio creative in seconds, e.g. 10.5

duration_match

string

(Required 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

(Required 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

Updating a Deal Request

{
    "deals": [
        {
            "deal_id": "id:123:playoff-campaign",
            "display_name": "Deal Busters",
            "ssp_id": "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"
        }
    ]
}

Data Syncing Response

{
    "deals": [
        {
            "deal_id": "id:123:yolo-campaign",
            "display_name": "Deal Busters",
            "ssp_id": "exampleSSP",
            "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",
            "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,
            "creative_type": "video",
            "display_sizes": [
                {
                    "w": 320,
                    "h": 70
                },
                {
                    "w": 80,
                    "h": 250
                }
            ],
            "duration": 15,
            "duration_match": "equals_to_duration",
            "skippable": "skippable"
        }
    ]
}