V1 Deals Sync API for Suppliers

Warning

In Q3 2024, we will begin gradually phasing out of the Deals Sync API v1.0, starting with sunsetting the POST method. Please follow the Deals API for Suppliers V1 to V2 Migration Guide.

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 propogate the submitted Deals information to the specified Buyer and also ensure that all of the details are correct so that at time of delivery there should be no technically impediments to prevent the deal from running successfully.

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 file

• The 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.

Creating a Deal

Warning

This method is no longer supported in V1 Deals Sync API

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 -->
https://my.bidswitch.com/api/v1/ssp/<seat-id>/deals/

Note

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

v1 POST request

{
    "deals": [
        {
            "deal_id": "id:123:playoff-campaign",
            "display_name": "Deal Busters",
            "dsp_seat": "16",
            "buyers": [
                "abc",
                "def"
            ],
            "inventory_source": [
                "pub-123"
            ],
            "contact_email": "someone@example.com",
            "guaranteed_units_purchased_count": 23000,
            "start_time": "2019-10-02T15:01:23.045123456Z",
            "end_time": "2019-11-02T15:01:23.045123456Z",
            "ssp_deal_status": "active",
            "price": 5432.12,
            "currency_code": "usd",
            "price_type": "auction",
            "price_method": "cpm",
            "bid_floor": 2.678,
            "deal_type": "private_auction",
            "contract_type": "guaranteed",
            "creative_type": "video",
            "display_sizes": [
                {
                    "w": 320,
                    "h": 70
                },
                {
                    "w": 80,
                    "h": 250
                }
            ],
            "duration": 15,
            "duration_match": "equals_to_duration",
            "skippable": "skippable"
        }
    ]
}

Updating a Deal

To update an existing deal, put the details to Deals Sync API, ensuring your specify the correct "deal_id".

<!-- PUT to this endpoint where the <seat-id> is your BidSwitch Seat ID -->
https://my.bidswitch.com/api/v1/ssp/<seat-id>/deals/

v1 PUT request

{
    "deals": [
        {
            "deal_id": "id:123:yolo-campaign",
            "dsp_seat": "16",
            "buyers": [
                "abc",
                "def"
            ],
            "inventory_source": [
                "pub-123"
            ],
            "contact_email": "someone@example.com",
            "guaranteed_units_purchased_count": 23000,
            "start_time": "2019-10-02T15:01:23.045123456Z",
            "end_time": "2019-11-02T15:01:23.045123456Z",
            "update_time": "2019-10-02T15:01:43.045123456Z",
            "ssp_deal_status": "paused",
            "price_method": "cpm",
            "display_name": "Deal Busters",
            "contract_type": "guaranteed",
            "creative_type": "video",
            "display_sizes": [
                {
                    "w": 320,
                    "h": 70
                },
                {
                    "w": 80,
                    "h": 250
                }
            ],
            "duration": 15,
            "duration_match": "equals_to_duration",
            "skippable": "skippable"
        }
    ]
}

Reporting

To get the details of your deals, make a get request to this endpoint.

<!-- GET to this endpoint where the <seat-id> is your BidSwitch Seat ID -->
https://my.bidswitch.com/api/v1/ssp/<seat-id>/deals/

v1 GET response

{
    "deals": [
        {
            "deal_id": "id:123:yolo-campaign",
            "display_name": "Deal Busters",
            "dsp_seat": "16",
            "buyers": [
                "abc",
                "def"
            ],
            "inventory_source": [
                "pub-123"
            ],
            "contact_email": "someone@example.com",
            "guaranteed_units_purchased_count": 23000,
            "start_time": "2019-10-02T15:01:23.045123456Z",
            "end_time": "2019-11-02T15:01:23.045123456Z",
            "dsp_update_time": "2019-11-02T15:01:43.045123456Z",
            "ssp_deal_status": "active",
            "dsp_update_status": "created_in_dsp",
            "price": 5432.12,
            "currency_code": "usd",
            "price_type": "auction",
            "bid_floor": 2.678,
            "creative_type": "video",
            "display_sizes": [
                {
                    "w": 320,
                    "h": 70
                },
                {
                    "w": 80,
                    "h": 250
                }
            ],
            "duration": 15,
            "duration_match": "equals_to_duration",
            "skippable": "skippable"
        }
    ]
}

Request/Response Fields

Deals API Fields

Field	Type	Description
deals	array of objects	(Required) Contains an array of deals and their relevant information
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 request invalidation: , # % $ @ * & ? ! ` ~ " ' / \ | ( ) { } [ ]+ = ^ :
display_name	string	(Required) This is the name of the deal which will be shown in the Buyer UI, e.g. "Some Deal. In-App Only". Only alphanumeric symbols and a period allowed.
dsp_seat	string	(Required) Specifies the BidSwitch Buyer to whom you wish to send this deal, this is the ID normally used to identify your partners and can be found on the myBidSwitch UI Demand Partners ‣ Connected Partners page, e.g. "16" is Google DV360 and "93" is The Trade Desk
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"]. 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 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 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 https://my.bidswitch.com/api/v1/ssp/<ssp-seat>/seats/, e.g: [{"seat_id": 12, "seat_name": "custom buyer"}]
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.
contact_email	string	(Required) Supplier contact details e.g. "email@example.com"
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. Must be greater than 0 if contract type is guaranteed.
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
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".
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 date must be at least 1 hour in the future from the time of the request.
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"
dsp_update_time	string	(Response Only) Specifies the time when the Buyer last updated the deal status, the format uses RFC3339, and the default time zone is UTC, e.g. "2019-10-02T15:01:23.045123456Z"
ssp_deal_status	string	(Required) Indicates the status of the Deal on the Supplier side. Can take the following values: "active" "paused" "rejected"
dsp_deal_status	string	(Response only) Indicates the status of the Deal on the Buyer side. Can take the following values: "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 DSP UI or for them to create a line items. "error_in_dsp": An error occurred while pushing the deal to the Buyer. "active": Deal status active. Line item assigned, valid creative assigned. "pending": Deal status pending. In some DSP this status means deal is not active and there is certain action needed for the buyer. "paused": Deal paused by buyer. "rejected": Deal has been rejected.
currency_code	string	(Required) The currency code in ISO 4217, e.g. "usd"
price	float	(Required) Represents an amount of money for a fixed price deal, for fixed price auctions it should be equal to the bid floor, e.g. 5.22. Either bid_floor or price must be a positive value A non-zero price is required for a fixed price auction, for a variable price auction you may set the price to 0 Note: If a deal has been created by an advertiser in DV360, when uploading the deal information to BidSwitch the price type must match.
bid_floor	float	(Required) Specifies the bid floor for this deal at auction. For fixed price deals this specifies the deal price, e.g. 5.22. Either bid_floor or price must be a positive value A non-zero bidfloor is required for a variable price auction, for a fixed price auction this value must match the price value
price_type	string	(Required) Indicated whether the price is fixed or set at auction, the valid values are: "fixed" "auction"
price_method	string	(Required) Indicates the pricing method, the only possible value is "cpm"
deal_type	string	(Required) Indicates the deal type, these are the possible values. "private_auction": means that the imp.pmp.private_auction request value will be 1 "open_auction": means that the imp.pmp.private_auction request value will be 0
creative_type	string	(Required) Indicates the acceptable creative type for this deal, the possible values are: "display" "video" "audio" "native"
display_sizes	array of objects	(Required for Display) An array of objects indicating the possible ad slot sizes, e.g. [{"w":320, "h":70}]
duration	float	(Required for Video/Audio) The duration of the video/audio creative in seconds, e.g. 10.5
duration_match	string	(Required for video/audio) Indicates whether the creative duration meets the required duration, the possible values are: "equals_to_duration" The creative duration needs to be the same as the required duration "less_than_or_equals_to_duration" The creative duration needs to be the same as or less than required duration
skippable	string	(Required for video/audio) Indicates if the video/audio can be skipped, the possible values are "skippable": The creative must be skippable. "non-skippable": The creative must be non-skippable. "any": Can be either
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. "Could you lower the price from $5 to $3"
revision_id	integer	This is a read-only field generated by BidSwitch. When a Supplier changes the value of any field(s), excluding the ssp_deal_status field, the revision_id is incremented. This field displays the latest revision logged with BidSwitch and indicates the total number of revisions the deal has been through.

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 from BidSwitch support team.

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

5. Make a PUT response for the created deal.

6. Send a GET request and make sure the deal has 2 revisions.

Should you encounter any problems 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.

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.

• 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