BidSwitch Deals API for Suppliers

The BidSwitch Deals API integrates with Deal Management APIs of Buyers that are connected to BidSwitch, allowing BidSwitch connected Suppliers to push private or open deals to just one API. BidSwitch will then propogate the submitted Deals information to the specified Buyer and also ensure that all of the details are correct so that at time of delivery there should be no technically 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 your deal details to the Deals API, specifying the relevant Buyer.

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

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

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

Creating a Deal

To create a new deal, post the details to Deals API.

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

Note

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

Updating a Deal

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

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

Important

Once a deal has been activated by the Buyer (i.e. dsp_deal_status set to active), you are prohibited from changing the value of any fields apart from ssp_deal_status

Reporting

To get the details of your deals, make a get request to this endpoint.

<!-- GET to this endpoint where the <ssp-id> is your BidSwitch Seat ID -->
https://my.bidswitch.com/api/v1/ssp/<ssp-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 Buyer UI, e.g. "Some Deal. In-App Only". Only alphanumeric symbols and a period allowed.

dsp_seat

string

(Required) Specifies the Buyer to whom you wish to send this deal. These are the valid seat IDs:

  • "16" Google DV360

buyers

array of strings

(Required) Specifies the Advertisers/Agencies that should have access to this deal in the DSP’s system. You should use their seat ID with the DSP, e.g. ["3566751798272", "67276530973"]. Note: Google DV360 only allow one buyer in this field and it has to be an integer, to obtain it you need to contact your buyer on DV360.

inventory_source

  • string*

(Required) The display name of the inventory source. Should represent the seller who is actually negotiating the deal. For The Trade Desk this ID has to match with the seller_id of the inventory source as specified in ads.txt, sellers.json and the Supply Chain Object. Only alphanumeric symbols and a period, colon, underscore, space, and dash are allowed [a-zA-Z0-9-_: .], e.g. "Some Publisher."

contact_email

string

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

(Required) Indicates the status of the Deal on the Supplier side. Can take the following values:

  • "active"

  • "paused"

dsp_deal_status

string

(Response only) 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 bidfloor 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 for Display) 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

Buyer Restrictions

For DV360, once a deal has been submitted, i.e. dsp_deal_status = created_in_dsp or created_in_bidswitch, you may only update the following fields:

  • display_name

  • contact_email

  • start_time

  • end_time

  • price_method

  • bid_floor

  • price

  • guaranteed_units_purchased_count

  • currency_code

  • skippable

  • creative_type

  • display_sizes

  • duration_match

  • duration

  • ssp_deal_status

Creating Deal Request

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

Updating Deal Request

{
    "deals": [
        {
            "deal_id": "id:123:yolo-campaign",
            "dsp_seat": "16",
            "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",
            "update_time": "2019-10-02T15:01:43.045123456Z",
            "ssp_deal_status": "paused",
            "price_method": "cpm",
            "display_name": "Deal Busters",
            "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"
        }
    ]
}

Deal Reporting Response

{
    "deals": [
        {
            "deal_id": "id:123:yolo-campaign",
            "display_name": "Deal Busters",
            "dsp_seat": "16",
            "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_deal_status": "active",
            "dsp_update_status": "created_in_dsp",
            "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"
        }
    ]
}