V2 Deals API for Buyers

The Deals API enables you to programmatically update and negotiate deals with Suppliers. 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.

Note

  • Deals are only created by Suppliers, therefore your can only update existing deals.

  • The maximum number of deals objects per post or put request is 50.

Revision History Workflow Diagram

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, make regular GET requests to this endpoint, which will return all of your deal details.

<!-- GET this endpoint where the <dsp-id> is the BidSwitch Seat ID -->
<!-- and <version> is v1 or v2 -->
https://my.bidswitch.com/api/<version>/dsp/<dsp-id>/deals/

Updating Deals

To update deals, make PUT requests to the Deals API. The Deals API makes these changes available for your Supplier partners to pull these changes from our system. Deals are uniquely identified in the system through a combination of the Deal ID, the SSP Bid Request Name, and the revision number, so you should ensure these are correctly set when updating the terms of a deal.

<!-- PUT this endpoint where the <dsp-id> is the BidSwitch Seat ID -->
<!-- and <version> is v1 or v2 -->
https://my.bidswitch.com/api/<version>/dsp/<dsp-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) 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 my.bidswitch.com/api/v1/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) 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) 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) 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) 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) 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) 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 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) 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) 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) Indicates the pricing method, the only possible value is "cpm".

private_auction

int

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

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 are a valid request and response examples, 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 TradeDesk 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

{
    "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"
                }
            ]
        }
    ]
}