V2 Deals Sync API for Suppliers¶
The BidSwitch Deals Sync 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 propagate the submitted Deals to the specified Buyer and ensure that all of the details are correct so that at time of delivery there should be no technical impediments that prevent the deal from running successfully.
The main difference between V1 and V2 of this API is the concept of revisions. Each deal
may exist in a number of revisions as it undergoes changes/negotiation. Only the
latest revision that has been accepted and activated by both parties is what currently
trades, i.e. the revision with both ssp_status and dsp_status set to active.
Supplier IDs¶
Within BidSwitch, Suppliers have 3 identifiers due to historical reasons. The Deals Sync API uses your Seat ID as the identifier for its endpoints. The 3 identifiers are as follows.
The Supplier Name, which is a changeable string depending on business reasons, e.g.
Magnite CTV (formerly Telaria). Within the myBidSwitch UI this is the name used.The Supplier ID, which is an unchangeable string and used as a persistent identifier for some services such as Creative Blocking, e.g.
tremor. You can find all Supplier IDs in the sellers.txt fileThe Seat ID, with is an unchangeable integer and a persistent identifier for newer services, such as the Deals Sync API, e.g.
88. It can find in the myBidSwitch UI as part of your account URL. You can find all Seat IDs seller_details endpoint.
Syncing Deal Data¶
It is expected that to receive updated information your system should make regular
get requests to the Deals Sync API. The Deals Sync API will not push data to your system. To get
the details of your deals use this endpoint, which will return all of your deal details.
<!-- GET this endpoint where the <seat-id> is the BidSwitch Seat ID -->
<!-- and <version> is v1 or v2 -->
https://my.bidswitch.com/api/v2/ssp/<seat-id>/deals/
You can sort the list of deals by the date of the latest update in ascending or descending order. By default deals are sorted in descending order.
https://my.bidswitch.com/api/v2/ssp/<seat-id>/deals/?sorting=updated&sorting_dir=desc
https://my.bidswitch.com/api/v2/ssp/<seat-id>/deals/?sorting=updated&sorting_dir=asc
Filtering Deals¶
The list of deals can be filtered by the following:
Filter |
Type |
|---|---|
dsp_seat |
string |
status |
string |
deal_id |
string |
display_name |
string |
is_created_from_deals_discovery |
boolean |
Note
The is_created_from_deals_discovery=true filter returns a list of deals created in Deals Discovery and already activated by Buyers - only then they become available in Deals Sync API
https://my.bidswitch.com/api/v2/ssp/<seat-id>/deals/?is_created_from_deals_discovery=true
https://my.bidswitch.com/api/v2/ssp/<seat-id>/deals/?deal_id=deal_id_example
Creating a Deal¶
To create a new deal, post the details to Deals Sync API.
<!-- POST to this endpoint where the <seat-id> is your BidSwitch Seat ID -->
<!-- and <version> is v1 or v2 -->
https://my.bidswitch.com/api/v2/ssp/<seat-id>/deals/
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.
The maximum number of deals objects per post or put request is 50.
If a deal is created in the paused status, it won’t be available for activation by Buyers.
Updating a Deal¶
To update an existing deal, put the details to Deals Sync API, ensuring your specify the
correct "deal_id". Deals are uniquely identified in the system through a
combination of the Deal ID and the revision number, so you
should ensure these are correctly set when updating the terms of a deal.
<!-- PUT to this endpoint where the <seat-id> is your BidSwitch Seat ID -->
<!-- and <version> is v1 or v2 -->
https://my.bidswitch.com/api/v2/ssp/<seat-id>/deals/
Deleting a Deal¶
Warning
Deleting a deal is permanent and cannot be undone. When you delete a deal, the record on it is removed from the database. Please pay extra attention when performing this action.
If a deal has never been activated by a Buyer, you can permanently delete it. Make sure you use the correct deal_id of the deal to be deleted.
<!-- DELETE to this endpoint where the <seat-id> is your BidSwitch Seat ID -->
https://my.bidswitch.com/api/v2/ssp/<seat-id>/deals/?deal_id=deal_id_example
Request Response Fields¶
The request or response body is made of a deals array, with each deal possibly containing a number of deal revisions in a array in the following layout. See the field description table and examples for more details:
deals:
deal1:
revision1:
revision2:
deal2:
revision1:
revision2:
Deals Object¶
Field |
Type |
Description |
|---|---|---|
deals |
array of objects |
(Required) Contains an array of deal objects and their relevant information. Each deal is described by the deal object and the revisions contained within it. |
Deal Object¶
Field |
Type |
Description |
|---|---|---|
buyers |
array of strings |
(Required for SSP) Specifies the Advertisers/Agencies at the For some Buyers, if you do not know the correct ID you can include a human
readable version, e.g. Google DV360 Important: Google DV360 only allow one buyer in this field and it must be their top-level DV360 Partner ID.
Finding the correct DV360 ID¶
<!-- Another clue to the correct Partner ID is -->
<!-- in the Google URL which has both partner and advertiser -->
displayvideo.google.com/#ng_nav/p/<this-id>/a/1111/cs
<!-- Here the partner ID for deals sync is 123456 -->
displayvideo.google.com/#ng_nav/p/123456/a/1111/cs
The Trade Desk The [{"seat_id": 12, "seat_name": "custom buyer"}]
|
creation_date |
string |
(Response Only) The isodatetime of when the given deal was created. |
contract_type |
string |
(Required for SSP) Specifies the contract type, the possible values are:
|
deal_id |
string |
(Required) This is the deal ID which will be sent in bid requests, e.g.
|
dsp_seat |
string |
(Required) Specifies the DSP party to this deal. This should match the
DSP ID of your trading partner in BidSwitch and who represents the agency set in the
|
revisions |
array of objects |
(Required for SSP) Passes the details of the deal. Each deal may exists in a
number of revisions but only the revision marked as During negotiations, after creating the deal, all of the Deal Object fields
become read-only as well as most revision object fields, except for
These can be used by the Buyer to signify acceptance or ask for changes. If a Buyer requests changes, they should respond with updated terms and specify the revision number to which the terms apply. Should the Supplier accept these, the revision number increases as it requires changes to the initial deal. Likewise, should a Supplier make self-initiated changes to the initial terms the revision increases. Only updating the |
ssp_name |
string |
(Required for DSPs) Specifies the Supplier name to whom you wish to sent this
deal, e.g. |
ssp_bid_request_name |
string |
(Required for DSPs) Specifies the Supplier name that will be passed in the
bid request, this maps to the |
status |
string |
(Read Only) Indicates the overall status of the Deal as managed within
BidSwitch. This status evaluates the
|
Revisions Object¶
Field |
Type |
Description |
|---|---|---|
auction_type |
int |
(Required for SSPs) Indicates the auction type:
|
audio |
object |
(Required for audio deals) Describes the details of the audio ad slot
available, e.g. |
contact_email |
string |
(Required for SSPs) Supplier contact details e.g. |
creative_type |
string |
(Required for SSPs) Indicates the acceptable creative type for this deal, the possible values are:
|
currency_code |
string |
(Optional) The currency code in ISO 4217, e.g. |
display |
object |
(Required for display deals) Describes the details of the display ad slot
available using an array of the |
display_name |
string |
(Required for SSPs) A user friendly (human readable) description of the
agreement. Only alphanumeric symbols and a period allowed, e.g.
|
dsp_note |
string |
(Optional) Passes information from the Buyer to Supplier. This is a read-only
field for Suppliers and may only be changed by Buyers, e.g.
|
dsp_status |
string |
(Required for DSPs) Indicates the status of the Deal on the Buyer side. Can take the following values:
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.
|
dsp_revision_status_error |
string |
(SSP Response Only) Returns the error message from the Buyer system if there is an issue. |
dsp_update_time |
string |
(Response Only) Specifies the time when the Buyer last updated the deal
status, the format uses RFC 3339, and the default time zone is UTC,
e.g. |
end_time |
string |
(Required for SSPs) Specifies the end time of the deal, the format uses RFC3339,
and the default time zone is UTC, e.g. |
guaranteed_units_purchased_count |
int |
(Required for SSPs) For guaranteed deals, specifies the minimum number of
impressions guaranteed by the Supplier e.g. |
inventory_source |
array of strings |
(Required for SSPs) The ads.txt ID for the publisher(s) from whom the deal
inventory is sourced. This helps to ensure the ads.txt authorization status is correct for deals verification on both ends within real time trading and during
negotiations. Only alphanumeric symbols and a period, colon, underscore, space,
and dash are allowed |
number |
integer |
(Required for updates) This is a field generated by BidSwitch.
When a Supplier changes the value of any field(s), excluding the When making an update you should specify the revision number to which the changes apply. |
price |
float |
(Required for SSPs) Represents an amount of money for a deal, e.g. |
price_method |
string |
(Required for SSPs) Indicates the pricing method, the only possible value is
|
private_auction |
int |
(Required for SSPs) Indicates the auction type, either private or open. This field takes the following values.
|
ssp_ext |
array of objects |
(Optional) A freeform array of valid JSON objects. This can be used to pass arbitrary information from SSPs to DSPs. You should ensure your partners are aware of what you intend to pass in this field. |
ssp_note |
string |
(Optional) Passes information from the Supplier to Buyer. This is a read-only
field for Buyers and may only be changed by Suppliers, e.g.
|
ssp_status |
string |
(Required for SSPs) Indicates the status of the Deal on the Supplier side. Can take the following values:
|
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. |
start_time |
string |
(Required for SSPs) Specifies the start time of the deal, the format uses
RFC3339, and the default time zone is UTC, e.g.
|
targeting |
object |
(Optional) Can be used to include or exclude certain targeting criteria from the deal, e.g. device and geo, see the Deals Targeting Object section or details. Note: this field is not supported by DV360. |
video |
object |
(Required for video deals) Describes the details of the video inventory, see the Deals Video Object. Depending on the deal type, one of the Audio, Display, or Video fields is required to describe the inventory. |
Request/Response Examples¶
The following example is valid for all forms of request and response, see the Request/Response Fields table for a complete definition of each field and whether restrictions apply to it. You should also check the DV360 Notes and The Trade Desk Notes sections as these buyers have some of their own requirements.
Request Example¶
{
"deals": [
{
"deal_id": "test",
"dsp_seat": "1",
"buyers": [
"100500"
],
"contract_type": "guaranteed",
"ssp_bid_request_name": "sandbox_ssp",
"revisions": [
{
"number": 1,
"display_name": "Display Name",
"inventory_source": [
"test-pub-234"
],
"contact_email": "test@email.com",
"guaranteed_units_purchased_count": 0,
"start_time": "2020-03-29T10:15:09.791000Z",
"end_time": "2021-01-01T00:00:00Z",
"ssp_status": "active",
"currency_code": "USD",
"price": 0.25,
"auction_type": 3,
"price_method": "cpm",
"private_auction": 0,
"creative_type": "display",
"display": {
"sizes": [
{
"h": 70,
"w": 320
}
]
},
"targeting": {
"device": {
"geo": {
"type": "include",
"values": [
{
"country": "US",
"region": "US-CA"
},
{
"country": "RU"
}
]
},
"type": {
"type": "include",
"values": [
1,
2
]
}
},
"inventory_type": [
"site"
],
"site": {
"domain": {
"type": "exclude",
"values": [
"my.site.com"
]
}
}
},
"dsp_note": "dsp note example",
"ssp_note": "ssp note example",
"ssp_ext": [
{
"key name": "value"
}
]
}
]
}
]
}
Response Example¶
{ "count": 41,
"previous": "https://my.bidswitch.com/api/v2/ssp/255/deals/?page=3&page_size=1",
"next": null,
"deals": [
{
"deal_id": "test",
"dsp_seat": "1",
"ssp_name": "test_ssp",
"buyers": [
"100500"
],
"contract_type": "guaranteed",
"ssp_bid_request_name": "sandbox_ssp",
"status": "created",
"creation_date": "2020-10-19T17:35:37.044175Z",
"revisions": [
{
"number": 1,
"display_name": "Display Name",
"inventory_source": [
"test"
],
"contact_email": "test@email.com",
"guaranteed_units_purchased_count": 0,
"start_time": "2020-03-29T10:15:09.791000Z",
"end_time": "2021-01-01T00:00:00Z",
"dsp_status": "created",
"ssp_status": "active",
"currency_code": "USD",
"price": "0.2500000000000000000",
"auction_type": 3,
"price_method": "cpm",
"private_auction": 0,
"creative_type": "display",
"display": {
"sizes": [
{
"h": 70,
"w": 320
}
]
},
"targeting": {
"device": {
"geo": {
"type": "include",
"values": [
{
"country": "US",
"region": "US-CA"
},
{
"country": "RU"
}
]
},
"type": {
"type": "include",
"values": [
1,
2
]
}
},
"inventory_type": [
"site"
],
"site": {
"domain": {
"type": "exclude",
"values": [
"my.site.com"
]
}
}
},
"dsp_note": "dsp note example",
"ssp_note": "ssp note example",
"ssp_ext": [
{
"key name": "value"
}
],
"dsp_update_time": "2020-03-21T12:43:58.285208Z",
"ssp_update_time": "2020-03-18T03:09:04.827891Z"
}
]
}
]
}
Troubleshooting¶
To make sure your integration with BidSwitch was successful, proceed as follows:
Get your authorization token as described in API Authorization.
Test the token with a
GETrequest for deals.Create a deal or multiple deals with a
POSTrequest. You can get the DSP seat in the Demand Partners –> Connected partners section of the BidSwitch UI.Make sure the deal or deals creation from the previous step was successful with a
GETresponse.Make a
PUTrequest for the created deal.Send a
GETrequest and make sure the deal has 2 revisions.
Should you encounter a problem on any of the steps above, please contact BidSwitch support.
Standard HTTP responses¶
400 Bad RequestThe request data is inconsistent403 ForbiddenThe client does not have access rights to the content404 Not FoundThe server can not find the requested resource, even if the endpoint is valid
The Trade Desk Notes¶
The buyers field must be a The Trade Desk Seat ID and may only contain one ID. You can GET the available seat IDs at this endpoint along with the matching Seat Name
my.bidswitch.com/api/v1/ssp/<ssp-seat>/seats/, e.g:
[{"seat_id": 12, "seat_name": "custom buyer"}]
The
"display_name"field has a max length of256characters.The
"contact_email"field has a max length of256characters.The
"deal_id"field has a max length of128characters.The recommended limit for
GETmethod is 200 items per page.You cannot reject a deal once it has been activated by The Trade Desk.
With guaranteed deals the only available pricing is fixed price.
Once created, the
contract_type,auction_typeandbuyersfields cannot be changed.Supply-side
targetinginformation associated with the deal is supported as part of the integration.
DV360 Notes¶
Each Deal ID should be unique, i.e don’t create deals using the same Deal ID for multiple different buyers.
The
inventory_sourcefield has a maximum limit of 250 characters.The
display_namefield has a maximum limit of 240 characters.The
deal_idfield has a maximum limit of 100 characters.The
contact_emailfield has a maximum limit of 250 characters.The
auction_typefield cannot be changed once created.The
targetingfield is not supported.Once a deal has been activated by DV360 (i.e.
dsp_deal_statusset toactiveorcreated), you may only change the value of the following fields:If the
contract_typeis non-guaranteed:price,start_timeandend_timeIf the
contract_typeis guaranteed you may only update thessp_deal_statusfield
Once a deal is updated, a new revision is created for that deal. The revision needs to be accepted by the Buyer on DV360 side. Revisions and updates are delivered in up to 15 minutes.
For DV360, once a deal has been submitted, i.e. dsp_deal_status =
created_in_dsporcreated_in_bidswitch, you may only update the following fields:display_namecontact_emailprice_methodguaranteed_units_purchased_count
currency_codeskippablecreative_typedisplay_sizes
duration_matchdurationssp_deal_status