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/ssp/<dsp-id>/deals/

Updating a Deal

Note

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

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 <ssp-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"
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.
dsp_seat string (Required) Specifies your seat ID with BidSwitch.
ssp_id string (Required) Specifies the Supplier to whom you wish to send this deal.
buyers array of strings (Required) Specifies the Advertiser/Agencies that should have access to this deal, e.g. ["GetYourGuide", "booking"]
inventory_source array of strings (Required) The display name of the inventory source. Only alphanumeric symbols and a period allowed to use, e.g. "Some Publisher."
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"
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

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

Updating a Deal Request

{
    "deals":[
        {
            "deal_id":"id:123:playoff-campaign",
            "display_name":"Play-offs NYC",
            "ssp_id":"abc-123",
            "dsp_seat":"abc13",
            "buyers":[
                "abc",
                "def"
            ],
            "inventory_source":[
                "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",
            "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":"Play-offs NYC",
            "ssp_id":"312",
            "dsp_seat":"abc133",
            "buyers":[
                "abc",
                "def"
            ],
            "inventory_source":[
                "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",
            "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"
        }
    ]
}