V2 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 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.

Revision History Workflow Diagram

Supplier IDs

Within BidSwitch, Suppliers have 3 identifiers due to historical reasons. The Deals 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 file

  • The Seat ID, with is an unchangeable integer and a persistent identifier for newer services, such as the Deals 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 API. The Deals 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/

Creating a Deal

To create a new deal, post the details to Deals 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. See the V2 Deals API for Suppliers section for details.

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". 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/

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

Deals Object Fields

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

Deal Object Fields

Field

Type

Description

buyers

array of strings

(Required for SSP) Specifies the Advertisers/Agencies at the dsp_seat that should have access to this deal. You should use their ID with the DSP, e.g. ["3566751798272", "67276530973"]. At least 1 ID is required.

For some Buyers, if you do not know the correct ID you can include a human readable version, e.g. "Brand Advertiser X" but this does not work with partners that are fully automated end-to-end.

Google DV360

Important: Google DV360 only allow one buyer in this field and it must be their top-level DV360 Partner ID.

  • To obtain the correct ID you need to contact your buyer on DV360, as only they can provide you with this ID

  • This ID cannot be their DV360 Advertiser ID, as only partner-level accounts have rights to accept deals in negotiations. More context around these different DV360 IDs/Account levels and what can be done with each can be found here.

  • DV360 Partner ID information

  • DV360 Deals Negotiation Information

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 buyers field must be a The TradeDesk Seat ID and may only contain one ID. You can GET the available seat IDs at this endpoint along with the matching Seat Name https://my.bidswitch.com/api/v1/ssp/<ssp-seat>/seats/, e.g:

[{"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:

  • "guaranteed": A deal with a guarantee around certain delivery terms.

  • "non-guaranteed": A deal without any delivery terms guaranteed.

deal_id

string

(Required) This is the deal ID which will be sent in bid requests, e.g. "deal-877-twttx". Note: It has a maximum character limit of 256 and you cannot use any of the following symbols in the Deal ID, as doing so will result in bid request invalidation:

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

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 buyers field, e.g. "16"

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 active by both parties is currently traded.

During negotiations, after creating the deal, all of the Deal Object fields become read-only as well as most revision object fields, except for dsp_deal_status and dsp_note.

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_deal_status does not increment the revision as this signifies the terms have been accepted. For a Buyer, only the dsp_deal_status and dsp_note fields can be changed without requiring an increase in the revision number.

ssp_name

string

(Required for DSPs) Specifies the Supplier name to whom you wish to sent this deal, e.g. "Sandbox SSP". Note this is filled automatically by BidSwitch for Suppliers.

ssp_bid_request_name

string

(Required for DSPs) Specifies the Supplier name that will be passed in the bid request, this maps to the ext.ssp in the BidSwitch protocol.

status

string

(Read Only) Indicates the overall status of the Deal as managed within BidSwitch. This status evaluates the ssp_status and dsp_status and matches the lowest level. For example if an SSP indicates a deal is active but the DSP has paused the deal, the overall status is paused. Can take the following values:

  • "active"

  • "accepted"

  • "created"

  • "paused"

  • "rejected"

Revisions Object

Deals API - Revisions Object

Field

Type

Description

auction_type

int

(Required for SSPs) Indicates the auction type:

  • 1 First price

  • 2 Second price

  • 3 Fixed price

audio

object

(Required for audio deals) Describes the details of the audio ad slot available, e.g. audio.duration. See the Deals Audio Object section for complete details. Depending on the deal type, one of the Audio, Display, or Video fields is required to describe the inventory.

contact_email

string

(Required for SSPs) Supplier contact details e.g. "email@example.com". Passes a contact to the Buyer so that negotiations can take place more smoothly.

creative_type

string

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

  • "display"

  • "video"

  • "audio"

  • "native"

currency_code

string

(Optional) The currency code in ISO 4217, e.g. "usd". The default is USD

display

object

(Required for display deals) Describes the details of the display ad slot available using an array of the sizes object. See the Deals Display Object section for complete details. Depending on the deal type, one of the Audio, Display, or Video fields is required to describe the inventory.

display_name

string

(Required for SSPs) A user friendly (human readable) description of the agreement. Only alphanumeric symbols and a period allowed, e.g. "2021 Summer Fashion Deal".

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. "Can you change the start date to the first of the month?"

dsp_status

string

(Required for DSPs) Indicates the status of the Deal on the Buyer side. Can take the following values:

  • "active"

  • "accepted"

  • "pending"

  • "paused"

  • "rejected"

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. "2019-10-02T15:01:23.045123456Z"

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. "2019-10-02T15:01:23.045123456Z". The end time must be at least 1 hour in the future from the time of the request.

guaranteed_units_purchased_count

int

(Required for SSPs) 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.

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 [a-zA-Z0-9-_: .], e.g. ["pub-id-1642", "pub-id-1776"]. Each inventory source name has a maximum length of 250 characters.

number

integer

(Required for updates) This is a field generated by BidSwitch. When a Supplier changes the value of any field(s), excluding the ssp_status field, the number is incremented. This field displays the latest revision logged with BidSwitch and indicates the total number of revisions the deal has been through.

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. 5.22. A non-zero price is required in this field.

price_method

string

(Required for SSPs) Indicates the pricing method, the only possible value is "cpm".

private_auction

int

(Required for SSPs) Indicates the auction type, either private or open. This field takes the following values.

  • 1 Indicating a private auction

  • 0 Indicating an open auction

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. "We've changed the price as requested".

ssp_status

string

(Required for SSPs) Indicates the status of the Deal on the Supplier side. Can take the following values:

  • "active"

  • "accepted"

  • "pending"

  • "paused"

  • "rejected"

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"

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. "2019-10-02T15:01:23.045123456Z".

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:

  1. Get your authorization token as described in API Authorization.

  2. Test the token with a GET request for deals.

  3. Create a deal or multiple deals with a POST request. You can get the DSP seat in the Demand Partners –> Connected partners section of the BidSwitch UI.

  4. Make sure the deal or deals creation from the previous step was successful with a GET response.

  5. Make a PUT request for the created deal.

  6. Send a GET request 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 Request The request data is inconsistent

  • 403 Forbidden The client does not have access rights to the content

  • 404 Not Found The 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 of 256 characters.

  • The "contact_email" field has a max length of 256 characters.

  • The "deal_id" field has a max length of 128 characters.

  • 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_type and buyers fields cannot be changed.

  • Supply-side targeting information 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_source field has a maximum limit of 250 characters.

  • The display_name field has a maximum limit of 240 characters.

  • The deal_id field has a maximum limit of 100 characters.

  • The contact_email field has a maximum limit of 250 characters.

  • The auction_type field cannot be changed once created.

  • The targeting field is not supported.

  • Once a deal has been activated by DV360 (i.e. dsp_deal_status set to active or paused), you may only change the value of the following fields:

    • If the contract_type is non-guaranteed: start_time and end_time

    • If the contract_type is guaranteed you may only update the ssp_deal_status field

  • For DV360, once a deal has been submitted, i.e. dsp_deal_status = created_in_dsp or created_in_bidswitch, you may only update the following fields:

    • display_name

    • contact_email

    • price_method

    • guaranteed_units_purchased_count

    • currency_code

    • skippable

    • creative_type

    • display_sizes

    • duration_match

    • duration

    • ssp_deal_status