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/

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"
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 buyers at the DSP 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 allowed to use, 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"
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"
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
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
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"
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:

  • "unspecified": No creative duration criteria specified
  • "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

Creating Deal Request

{
    "deals": [
        {
            "deal_id": "id:123:playoff-campaign",
            "display_name": "Deal Busters",
            "dsp_seat": "16",
            "buyers": [
                "abc",
                "def"
            ],
            "inventory_source": "publisher.com",
            "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",
            "agencies": [
                "abc",
                "def"
            ],
            "publishers_id": [
                "pub_123",
                "pub_987"
            ],
            "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",
            "inventory_source": "publisher.com",
            "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": "publisher.com",
            "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"
        }
    ]
}