Deals API for Buyers V1 to V2 Migration Guide

Warning

In Q3 2024, we will begin gradually phasing out of the Deals API v1.0, starting with sunsetting the POST method.

This document describes the main differences between Deals API v1 and v2, as well as the main attention points for Buyers to successfully migrate from v1 to v2.

The concept of revision, the main difference between two versions and supported in v2, effects every step of migration. The sections below detail how to meet the requirements of this new concept. Refer to V2 Deals API for Suppliers for detailed description of revisions.

Deals API Fields Mapping

As part of supporting the concept of revisions in Deals API v2, all Deals API fields have been split into deals fields and revisions fields. Some fields from v1 have been changed or replaced in v2; there are also new revision specific fields. See below deal and revision fields as per v1 and v2, with notes explaining the use of those fields in v2 when necessary.

Deals Object Fields

Deals Object Fields

v1 Field	v2 Field
ssp_bid_request_name	ssp_bid_request_name
deal_id	deal_id
dsp_seat	dsp_seat
ssp_name	ssp_name
not supported	revisions

Revisions Object Field

Revisions Object Field

v1 Deals	v2 Revisions	Notes
dsp_deal_status	dsp_status	renamed field
dsp_note	dsp_note	no changes
not supported	number	The number of the revision

Deals API GET Method Changes

To GET the updated information on your deals from Deals API, please make sure you send your GET requests to the following endpoint:

<!-- The version is changed from v1 to v2 -->
https://my.bidswitch.com/api/v2/ssp/<seat-id>/deals/

Pagination and sorting by the updated field are supported in v2.

https://my.bidswitch.com/api/v2/ssp/ssp_id/deals/?page=1&page_size=1&sorting=updated&sorting_dir=desc

GET Return Example

 {
    "count": 1,
    "next": null,
    "previous": null,
    "deals": [
        {
            "ssp_bid_request_name": "sspBidRequestName",
            "deal_id": "some_deal_id",
            "dsp_seat": "74",
            "ssp_name": "sspName",
            "buyers": [
                "abc",
                "def"
            ],
            "contract_type": "non-guaranteed",
            "creation_date": "2024-03-01T18:05:27.044440Z",
            "status": "active",
            "is_created_from_deals_discovery": false,
            "updated": "2024-03-04T13:50:44.655511Z",
            "revisions": [
                {
                    "dsp_status": "active",
                    "dsp_note": "some note",
                    "dsp_update_time": "2024-03-04T13:50:44.655507Z",
                    "ssp_update_time": "2024-03-01T18:16:16.982488Z",
                    "created": "2024-03-01T18:16:16.997433Z",
                    "number": 1,
                    "dsp_revision_status_error": "",
                    "display_name": "Some display name",
                    "inventory_source": [
                        "pub-123"
                    ],
                    "contact_email": "someone@example.com",
                    "guaranteed_units_purchased_count": 23000,
                    "start_time": "2019-10-02T15:01:23.045123Z",
                    "end_time": "2036-11-02T15:01:23.045123Z",
                    "currency_code": "USD",
                    "price": "5432.1200000000000000000",
                    "auction_type": 3,
                    "price_method": "cpm",
                    "private_auction": 1,
                    "creative_type": "native",
                    "targeting": null,
                    "ssp_note": null,
                    "ssp_ext": null,
                    "ssp_status": "active"
                }
            ]
        }
    ]
}

PUT Request JSON Example

 {
    "deals": [
        {
            "ssp_bid_request_name": "sspBidRequestName",
            "deal_id": "some_deal_id",
            "dsp_seat": "74",
            "ssp_name": "sspName",
            "revisions": [
                {
                    "dsp_status": "active",
                    "number": 1
                }
            ]
        }
    ]
}

To update a deal with PUT method, use the same request body as per the example above.