Deals Synchronisation

Deals Synchronisation is a feature built by BidSwitch to support Buyers and Suppliers sharing deal information with one another. It offers two ways by which you can share the relevant information with your trading partners. The BidSwitch Deals API, and a deals management spreadsheet which can uploaded/downloaded from the myBidSwitch UI. The deals management spreadsheet serves three main purposes:

  • Buyers and Suppliers that do not have an API integration can use the spreadsheet to synchronise deal details with each other, and use the spreadsheet as the basis for entering deal information into their own system if needed.
  • Buyers or Suppliers that have integrated using the API can automatically pull updates into their own system or push changes to BidSwitch, which will be reflected in the spreadsheet i.e. API updates will be reflected in the spreadsheet and vice versa.
  • In addition to syncing deal information, the information in the spreadsheet is used by BidSwitch to ensure that deal trading is conducted as efficiently as possible and/or troubleshoot under-performing deals.
../_images/deals-sync.png

Managing Deals in the UI

To create new deals or update existing deals, upload a version of the deals management spreadsheet with your changes. Uploaded changes are based on each Deal ID, therefore either new deals can be added or existing deals updated. Currently you cannot delete a deal, but you can set its status to paused if you do not want it to be traded.

  1. Get a copy of the spreadsheet from the Deals Synchronisation ‣ Download Deals pane. This contains all of your current deals, or you can download a blank template if you have none.
  2. Add or update the deal information for each Deal ID, making sure you include information in all of the required columns, see the Spreadsheet Columns section for an explanation of each.
  3. Save your changes
  4. Upload the changes to the Deals Synchronisation.
    • Your changes will be immediately updated in the BidSwitch UI
    • For partners with an API integration, changes will be updated in their system once they pull them from the API
    • For your partners also using a spreadsheet, the deals which you have with each will be added/update in their spreadsheet
    • Spreadsheet validation is done on a per row basis, so if you upload changes to 10 deals but have made an error in one row, the UI will show you the Deal ID of the entry you need to fix. The 9 correct entries will be updated.

Spreadsheet Columns

The Deals Synchronisation spreadsheet can be downloaded from the UI Deals Synchronisation ‣ Download Deals page. It contains for following columns which are used to manage deals.

  • You need to include information in all of the required columns for a Deal ID to be properly updated.
  • Some of the below fields are for either SSPs or DSPs only, and they are marked as such.
Excel Sheet Columns
Column Description
deal_id

(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 invalid symbols in the Deal ID:

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

display_name (Required) This is the name of the deal which will be shown in your partners UI, e.g. "Deal name.". Only alphanumeric symbols and a period allowed.
dsp_seat (Required. SSP Only) Specifies the Buyer that is party to this deal. If you have a Deal ID that should be available to multiple Buyers, add a separate row for each Buyer.
ssp_id (Required. DSP Only) Specifies the Supplier that is party to this deal.
buyers (Required) Specifies the Advertiser/Agencies that should have access to this deal, e.g. ["GetYourGuide", "booking"]
inventory_source (Required) The display name of the inventory source. Only alphanumeric symbols and a period allowed to use, e.g. "Some Publisher."
contact_email (Required. SSP Only) Supplier contact details e.g. "adops@example.com"
guaranteed_units_purchased_count (Required) For guaranteed deals, this must be an integer specifying the minimum number of impressions guaranteed by the Supplier e.g. 23000. Should be 0 if contract type is non-guaranteed.
contract_type

(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_date (Required) Specifies the start date of the deal, the format uses YYYY-MM-DD, e.g. "2019-10-02"
start_time (Required) Specifies the start time of the deal, the format uses HH:MM:SS, e.g. 15:01:23. The default time zone is UTC
end_date (Required) Specifies the end date of the deal, the format uses YYYY-MM-DD, e.g. "2019-10-02".
end_time (Required) Specifies the end time of the deal, the format uses HH:MM:SS, e.g. 15:01:23. The default time zone is UTC
ssp_update_time Filled by BidSwitch. 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 Filled by BidSwitch. pecifies 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

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

  • "active"
  • "paused"
dsp_deal_status

(Required, DSP Only) Indicates the status of the Deal on the Buyer side. Can take the following values.

  • "active": Deal status active. Line item assigned, valid creative assigned.
  • "paused": Deal paused by buyer.

You might also see some of the following statuses in the spreadsheet if the deal has yet to be updated by a partner using an API integration.

  • "pending": In some DSP this status means deal is not active and there is some action needed by the buyer to activate it.
  • "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.
currency_code (Required) The currency code in ISO 4217, e.g. "usd"
price (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 (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

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

  • "fixed"
  • "auction"
price_method (Required) Indicates the pricing method, the only possible value is "cpm"
deal_type

(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

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

  • "display"
  • "video"
  • "audio"
display_sizes (Required) A comma separated list of Width x Height indicating the possible ad slot sizes, e.g. 320x70, 320x250
duration (Required for Video/Audio) The duration of the video/audio creative in seconds, e.g. 10.5
duration_match

(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

(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