V2 Deals Sync API for Buyers

The Deals Sync 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.

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, 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/v2/dsp/<dsp-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/dsp/<dsp-id>/deals/?sorting=updated&sorting_dir=desc
https://my.bidswitch.com/api/v2/dsp/<dsp-id>/deals/?sorting=updated&sorting_dir=asc

Filtering Deals

The list of deals can be filtered by the following:

Deal Filters

Filter	Type
ssp_name	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/dsp/<dsp-id>/deals/?is_created_from_deals_discovery=true
https://my.bidswitch.com/api/v2/dsp/<dsp-id>/deals/?deal_id=deal_id_example

Updating Deals

To update deals, make PUT requests to the Deals Sync API. The Deals Sync 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/v2/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 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" "pending" "broken"

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": Deal status active, Line item assigned, valid creative assigned "paused": Deal paused by the 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. "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 Buyer UI or for them to create a line items "error_in_dsp": An error occurred while pushing the deal to the Buyer "pending": In some Buyers this status means deal is not active and there is some action needed by the Buyer to activate it "rejected": Proposal 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" "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 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 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"
                }
            ]
        }
    ]
}

Standard HTTP responses

• 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

• Deals Sync API for Buyers V1 to V2 Migration Guide