Deals Discovery¶
Deals Discovery API¶
The BidSwitch Deals Discovery API integrates with Deals Management APIs of Suppliers that are connected to BidSwitch, allowing BidSwitch connected Buyers to search and filter for open deals (evergreen, seasonal, one-to-many, etc) set up through one API integration.
To integrate with this API, use the following steps.¶
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. If you have Read Only permissions you may only user
GETqueries. Request an API Account to access all API methods.Retrieve or update deal details from the relevant API depending on your integration, see either the V1 Deals API for Suppliers or V2 Deals API for Suppliers section.
When you push deal updates, BidSwitch makes these available to your partner Buyers also using the API. The details are also made available in spreadsheet format for partners not using an API.
Your system should pull regularly from the Deals Discovery API to get updates.
BidSwitch parses submitted Deals information from various Suppliers and holds them in our discovery portal. From the BidSwitch API, you can pull the up to date Deals data into your own deals discovery platform to present them to advertisers and agencies connected to your systems.
Note
One-to-one deals setup and management is conducted through the Deals Sync API, see the Deals Management section for details.
To view the list of existing deals, GET the following endpoint:
/api/v1/<dsp|ssp>/<seat_id>/deals_discovery/
The Deals Discovery API will not push data to your system. Your system should make regular GET requests to the Deals Discovery API to receive updated information.
For specific deals, GET and PUT/PATCH methods are allowed with the following endpoint:
/api/v1/<dsp|ssp>/<seat_id>/deals_discovery/<id>/
Suppliers can access their own deals with any status; Buyers can access deals with Active status, shared with them by the partner Supplier.
{
"status": "active",
"start_time": "2023-01-23T15:28:24.394000Z",
"end_time": "2023-05-23T15:28:24.394000Z",
"excluded_dsps": [1, 456, 4], // nullable
"description": "Some updated deal description",
"publishers": ["CNN", "googe.com", "nexus"], // nullable.
"inventory_image": "path_to_media_bucket/image.jpg", // nullable.
"weekly_total_impressions": 15,
"weekly_unique_impressions": 20,
"inventory": {
"display_sizes": ["180x180", "320x240"], // nullable
"duration": 10.2, // nullable
"duration_match": "less_than_or_equals_to_duration", // nullable
"skippable": "non-skippable", // nullable
},
"contact_email": "foo@bar.com",
"breakdowns": [{"type": "AGE", "value": [{"stringId": "AGE_18_24", "percentage": "40"}]}], // isn't available until dv3-integration
"apps_breakdowns": [{"app": {"type": "PLATFORM_TYPE_IPHONE", "appId": "some_value"}, "percentage": 60}], // isn't available until dv3-integration
}
}
{
"is_activated": true,
"buyers": "buyer1", "buyer2"
}
Creating a Deal¶
Currently the POST method is not supported for creating deals and you can only created deals using Bulk Management.
Important
Each Deal Discovery Deal activated by a Buyer will also become available through the deals sync API. Therefore, if a deal ID already exists and you attempt to create a new deal using the same Deal ID, the action will be rejected.
To avoid this happening, we suggest you check the Deals Sync API for a matching Deal ID when creating any new deals. See the V2 Deals API for Suppliers section for details.
Updating a Deal¶
To update an existing deal, PUT/PATCH the details to the following endpoint, making sure your specify the correct "id".
/api/v1/<dsp|ssp>/<seat_id>/deals_discovery/<id>
Bulk Management¶
You can use this feature to upload / update a number of deals with one request. Buyers can only use Bulk Management for mass activation.
Bulk Management allows GET and POST methods with the following endpoint:
/api/v1/<dsp|ssp>/<seat_id>/deals_discovery/bulk/
The GET method provides an .xlsx file with the list of deals. The POST method is used for uploading/updating deals.
Warning
When updating the deal information, pay attention to the Editable column of the spreadsheet and make sure you leave non-editable fields untouched. Changing a non-editable field will result in a spreadsheet validation error.
If the request is handled successfully, the system returns the 201 response code, otherwise the 400 response code is returned together with the response body.
{
"success": 33,
"failed": 1,
"deals": [ // exists only if "failed" > 0
{
"deal_id": "GRID-123456",
"ssp_name":"liveintent",
"display_name": "MENA Families Video",
"errors": [
"Invalid value in currency_code.",
"Second error"
]
}
]
}
Filtering¶
For a filtered list of deals, send a GET query with key=value parameters. Multiple values for one key should be separated by a comma, for example key=value1,value2.
Buyers and Suppliers have different sets of supported keys.
Key |
Supported by |
|---|---|
deal_id |
Buyers and Suppliers |
status |
Suppliers only |
inventory_format |
Buyers and Suppliers |
display_name |
Buyers and Suppliers |
floor_price_min |
Buyers and Suppliers |
floor_price_max |
Buyers and Suppliers |
excluded_dsps |
Suppliers only |
publishers |
Buyers and Suppliers |
urg_owners |
Buyers and Suppliers |
auction_type |
Buyers and Suppliers |
is_activated |
Buyers only |
ssp_id |
Buyers only |
countries |
Buyers and Suppliers |
inventory_types |
Buyers and Suppliers |
device_types |
Buyers and Suppliers |
content_types |
Buyers and Suppliers |
inventory_highlights |
Buyers and Suppliers |
Forecasting¶
The Deals Discovery API provides access to forecasting, allowing you to analyze the inventory capacity within certain Deal IDs. Forecasting data is based on historical data gathered by BidSwitch and available by a GET query on a specific Deal ID and updated once a week.
Deals Discovery Forecasting is represented by the following fields:
Field |
Type |
|---|---|
bid_requests |
integer |
bid_request_categories |
json |
average_ecpm |
float |
average_win_rate |
float |
The bid_request_categories field is returned if the list of deals has been filtered by any forecasting categories. It should meet the following conditions:
Only the following keys are supported:
countries, inventory_types, device_types, ad_types, ads_txt_statusesEach key represents the proportion of categories within 1000 avails. A key is represented by a float with up to 2 decimal places, > 0 and < 1. The sum of keys in each category always equals 1.
Values for the
countriescategory are 2 symbol country codes. RU is excluded from the calculation.Values for the
inventory_typescategory are as follows:application, website, dooh, tvValues for the
content_typescategory are as follows:display, video, native, audioValues for the
device_typescategory are as follows:MediaCenter, PC, Phone, Tablet, CTVValues for the
ads_txt_statusescategory are as follows:direct, unknown, reseller, unauthorized
"forecasting": {
"bid_requests": 12152,
"average_ecpm": 0.109333,
"average_win_rate": 0.020800,
"bid_request_categories": {
"ad_types": {
"display": 1.0
},
"countries": {
"CA": 0.5,
"US": 0.5
},
"device_types": {
"pc": 0.28,
"phone": 0.67,
"tablet": 0.05,
"connected_tv": 0.0
},
"inventory_types": {
"website": 0.78,
"application": 0.22
},
"ads_txt_statuses": {
"direct": 0.15,
"unknown": 0.75,
"reseller": 0.09,
"unauthorized": 0.0
}
}
}
Deals Discovery API Fields¶
Field |
Description |
Example |
|---|---|---|
deal_id |
(Required) The deal ID sent in bid requests.
Note: Do not use any of the following symbols:
|
|
display_name |
(Required) The name of the deal. Max length 150 symbols |
|
ssp_name |
(Only for DSP) Read-only field generated by BidSwitch. Defines the Supplier that owns the deal. |
|
ssp_bid_request_name |
(Only for DSP) Supplier name passed in bid request. Maps to the |
|
creative_type |
(Required) Deal definition by format. Cannot be edited once created. The following values are supported:
|
|
status |
(Required) (Only for SSP) Indicates the status of the Deal on the Supplier side. The following values are supported:
|
|
start_time |
(Required) The start date of the deal. Must be earlier than the end_time; the YYYY-MM-DD HH:MM:SS format is supported. Cannot be further than 1 year in the future. The default time zone is UTC |
|
end_time |
(Required) The end date of the deal, The YYYY-MM-DD HH:MM:SS format is supported. Cannot be later than the year 2036. The default time zone is UTC |
|
auction_type |
(Required) Indicates the auction type:
|
|
currency_code |
(Required) The currency code in ISO 4217, e.g. |
|
price |
(Required) Represents an amount of money for a deal, e.g. 5.22. Must not be equal to zero |
|
description |
(Required) Deal inventory description. Max length 290 symbols |
|
inventory_image |
(Optional) The URL of an image promoting deal inventory. If missing, the image from “Company Profile” will be used. JPG and PNG formats are supported. The image size cannot exceed 2MB |
|
weekly_total_avails |
(Optional) The number of bid requests expected per week (provided by the Supplier) |
|
weekly_unique_avails |
(Optional) The number of unique bid requests expected per week (provided by the Supplier) |
|
publishers |
(Required) Names of publishers that are packed with the deal, separated by commas (,) and should correspond to the names as presented in sellers.json. There is no character limit |
|
contact_email |
(Required) Supplier contact details |
|
excluded_dsps |
(Optional) Excluded Buyers that won’t be able to see the deal in the Deals Discovery environment. Only active Trading Pair Buyer seats are allowed. Should contain only numbers |
|
display_sizes |
(Required for Display format) A comma separated list of Width x Height indicating the possible ad slot sizes. Note: Don’t put a space after the separating comma |
|
duration |
(Required for Video/Audio formats) The duration of the video/audio creative in seconds |
|
duration_match |
(Required for Video/Audio formats) Indicates whether the creative duration meets the required duration, the supported values are:
|
|
skippable |
(Required for Video/Audio) Indicates if the video/audio can be skipped, the supported values are:
|
|
urg_owners |
(Optional) Underrepresented groups the owner is a member of, if any. Multiple choice is possible, the supported values are:
|
|
is_activated |
(Only for DSP) The deal activation flag for Buyers. Activated deals appear
in the Deal Sync environment (Deal Sync API and Deals Management UI):
|
|
buyers |
(Only for DSP) Specifies the Advertiser/Agencies that should have access to this deal. Multiple values should be separated by comma (,) |
|
inventory_highlights |
(Optional) Labels that help Buyers navigate to the most relevant inventory faster. Please add all suitable labels to the field for each deal when uploading your deals. The number of labels per deal is unlimited. If you want to input more than one label, separate labels with commas. |
|
Deals Discovery UI¶
Suppliers and Buyers connected to BidSwitch and not having an API integration can use the Deals Discovery UI for sharing, managing and activating deals. Suppliers can submit and edit deals using the UI, while Buyers can find and activate deals offering the most suitable inventory by using numerous deal filters. The data for filters is provided by Suppliers.
Deals Discovery UI for Suppliers¶
The Deals Discovery UI allows Suppliers to create, update and manage open deals they want to share with Buyers.
To create new deals or update existing deals, upload a version of the deals spreadsheet with your changes. Uploaded changes are based on each Deal ID, therefore either new deals can be added or existing deals updated.
Deals can have the following statuses:
Active - discoverable by Buyers and available for activation
Paused - temporarily undiscoverable by Buyers and only visible to you. Also paused in the Deals Management environment
Archived - permanently undiscoverable by Buyers, marked as Rejected in the Deals Sync environment
Currently you cannot delete a deal, but you can set its status to paused if you do not want it to be traded, or to archived if you want to make it completely unavailable for discovery and update. Note: archived status cannot be changed.
Get a copy of the spreadsheet from the pane. This contains all of your current deals, or you can download a blank template if you have none.
Add or update the deal information for each Deal ID, making sure you include information in all of the required columns.
Warning
When updating the deal information, pay attention to the Editable column of the spreadsheet and make sure you leave non-editable fields untouched. Changing a non-editable field will result in a spreadsheet validation error.
Save your changes in the spreadsheet.
Upload your changes.
Your changes will be immediately updated in the Deals Discovery 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 processed.
Go to to get the list of existing deals. Use the provided selection of filters to manage the list and only show the deals you need immediate access to according to the data you provided in the previously uploaded spreadsheet. Each filter gives a dropdown list of options to select from, except for the Deal ID or Name filter which works as a search field. For additional filters, press the Add More Filters button.
To access a deal edit screen, click on the Deal Name on the list. While on the edit screen, you can change the deal status and time frame, edit inventory related data, and see the deal forecasting. Yoy can also see how many times the deal was activated by Buyers and proceed to the Deals Management UI following the links. Each deal activation by a Buyer creates an identical entity for this deal in Deals Management.
To promote the most relevant inventory for certain periods of time and certain events, make sure you set a selection of Inventory labels for each deal you upload. Thus you will increase visibility of high performance deals in advance of tentpole events and help Buyers find the most relevant inventory faster.
Deals Discovery UI for Buyers¶
The Deals Discovery UI allows Buyers to search for open deals shared by partner Suppliers and offering the most suitable inventory, and then activate the chosen deals to start buying.
Go to to get the list of available deals. Use the provided selection of filters to manage the list and find the deals offering the inventory suitable for your needs. Each filter gives a dropdown list of options to select from, except for the Deal ID or Name filter which works as a search field. For additional filters, press the Add More Filters button.
Click on the Deal Name on the list of available deals to open the deal activation window. This window provides you with the deal forecasting, basic information on the deal and the deal activation options. You can activate the deal for all Buyers or only for those selected by you.
Upon activating a deal, you can no longer manage it in the Deals Discovery UI. Activated deals can only be managed in the Deals Management UI. In the Deals Discovery UI, those deals receive the Activated status which cannot be changed.
Deals can have the following statuses:
Activated - the deal was activated by you and manageable in Deals Management
Not Activated - the deal wasn’t activated and cannot be managed
Deals Discovery Forecasting¶
Deals Discovery forecasting allows Buyers to analyze the inventory capacity within certain Deal IDs basing on historical data collected by BidSwitch. This includes normalized static data on potential bid requests, average eCPM and win rate within a deal, and multiple dynamic metrics applied to the weekly amount of bid requests. The data is updated once in 7 days. Deals Discovery forecasting is available to both Deals Discovery UI and API users.
The following metrics are supported:
UI Naming |
Description |
|---|---|
BidSwitch Weekly Avails |
All potential bid requests within a specific Deal ID |
Average eCPM |
Average eCPM for all bid requests within a specific Deal ID |
Average Win Rate |
Average win rate for all bid requests within a specific Deal ID |
Ads.txt Status |
The proportion of weekly avails to the amount of requests distributed by Ads.txt status within a specific Deal ID |
Ad Type |
The proportion of weekly avails to the amount of requests distributed by ad type (e.g. Display) within a specific Deal ID |
Country |
The proportion of weekly avails to the amount of requests distributed by countries within a specific Deal ID |
Device Type |
The proportion of weekly avails to the amount of requests distributed by device type (e.g. PC) within a specific Deal ID |
Inventory Type |
The proportion of weekly avails to the amount of requests distributed by inventory type (for example, Website) within of specific Deal ID |
Deals Discovery Notifications¶
Both Suppliers and Buyers using Deals Discovery get notified of changes potentially effecting the deal delivery. You can configure the notifications you would like to receive on your Profile page. To access it, click on the user icon in the top right corner of your browser window.
The notification triggering events include General events related to the time frame when the deal is supposed to be active and trading (the time period between the start and end dates) and Delivery events associated with trading deals.
Note
Deals Discovery notification will be enabled in the general availability release
General Events¶
Event description |
Triggered by |
Notified |
|---|---|---|
Deal activated |
Buyer |
Supplier |
Deal updated |
Supplier |
Buyer |
Deal status changed |
Supplier |
Buyer |
Deal expires in 7 days |
BidSwitch |
Supplier |
Delivery Events¶
Event description |
Triggered by |
Notified |
|---|---|---|
No Yes bids on an activated deal |
BidSwitch |
Buyer |
Drop of Yes bids on an activated deal |
BidSwitch |
Buyer |
DV360 Inventory Packages Integration Notes¶
Note
The functionality described below is only available to Suppliers forming an active trading pair with DV360. It has limited availability and can be enabled upon request. Please contact your BidSwitch representative for details
Suppliers integrated with DV360 can submit and edit deals using both Deals Discovery UI and API. The deals you submit will be automatically published in the Inventory Packages UI and can be discovered using DV360 UI or API access. DV360 Inventory Packages, formerly known as Auction Packages, are part of Google DV360 Marketplace. Suppliers connected and trading with Google can integrate with DV360 in order for their open auction deals to be shared in Google Marketplace listings, while meeting quotas and limitations set on the Google side. Quotas and limitations are subject to change and can always be discussed with your BidSwitch account manager.
Bulk Management Changes¶
For Suppliers integrated with DV360, Bulk Management template is updated with the following new fields:
dv360_status: required; represents the deal status in Google Marketplace, can be set to
active,paused,archived, ordisabled. Only active deals can be discovered via Google Marketplacessp_forecasted_dimensions_website: optional; represents a forecast breakdown by a targeting dimension (used on Google’s side)
ssp_forecasted_dimensions_app: optional; represents a slice in the mobile app breakdown (used on Google’s side)
Additional API Fields¶
These API fields are only for Suppliers integrated with DV360.
Field |
Description |
|---|---|
dv360_status |
(Required) The deal status in DV360. At this moment the following statuses are supported:
|
ssp_forecasted_dimensions_website |
(Optional) A forecast breakdown by a targeting dimension. |
ssp_forecasted_dimensions_app |
(Optional) A slice in the mobile app breakdown. |