Deals Sync API for Buyers V1 to V2 Migration Guide

Warning

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

This document describes the main differences between Deals Sync 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 Sync API for Suppliers for detailed description of revisions.

Deals Sync API Fields Mapping

As part of supporting the concept of revisions in Deals Sync API v2, all Deals Sync 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 Sync API GET Method Changes

To GET the updated information on your deals from Deals Sync 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.