Deals

This article describes resources for adding, updating, and reading shared deals and spot buy deals and for enabling advertisers and advertiser groups to access those deals.

Overview

A deal is a set of terms reflecting an agreement between an exchange and an advertiser that is executed programmatically via a deal ID.

Deals are negotiated offline between the publisher and advertiser networks. The network administrator can set up and share deals with advertiser groups or advertisers. The advertiser must then target the exchange with or without the deal ID.

Oath Ad Platforms DSP supports the two types of deals:

Shared Deals
In a shared deal the publisher offers supply on an exchange to all interested buyers.
Spot Buy Deals
In a spot buy deal the publisher offers supply to a single buyer, or a limited number of specified buyers.

Endpoint

/traffic/deals

The action taken depends on the HTTP method and the parameters specified.

  • Use the GET method to read an existing deal.
  • Use the POST method to create a new deal.
  • Use the PUT method to update an existing deal.

Resources

The deals resource is defined by the following following fields:

Table 95 Deal Fields
Name Description Type Create Update
id Specifies the deal ID. integer N/A Required
name Specifies the name of the deal. string Required Optional
status

Specifies the current status of the deal.

Allowed values:

  • :code:`ACTIVE: the deal is active.
  • INACTIVE: the deal is inactive.
string Required Optional
exchangeId

Specifies the exchange ID.

To learn more, see Exchanges.

integer Required Optional
exchangeDealId Specifies the unique ID for the deal on the exchange. string Required Optional
description Specifies a brief description of the deal. string Required Optional
reservePrice Specifies the acceptable reserve price for the deal. number Optional Optional
spotbuy

Indicates whether the deal is a spot buy deal or a shared deal.

  • true: the deal is a spot buy deal and you must specify at least one advertiser in the accounts array and ensure that the accountIsExcluded attribute is set to false.
  • false: the deal is a shared deal.
boolean Required Optional
accountGroupId

Specifies an account group that can target the deal.

An account group is a set of advertiser accounts that are managed as a group. To learn more, see Account Groups.

number Optional Optional
accountIsExcluded

For shared deals, specifies whether an advertiser may or may not access the deal:

  • true: all advertisers may target the deal except those specified in accounts and accountGroups array parameters.
  • false: an advertiser may target the deal only if it is specified in accounts and accountGroups array parameters.
boolean Required Optional
accounts

For shared deals, specifies an array of advertiser IDs that can or cannot target the deal depending on the value of the accountIsExcluded parameter.

If the accountIsExcluded parameter is true, account IDs specified in this array cannot target the deal.

array Optional Optional
accountGroups

For shared deals, specifies an array of account group IDs that can or cannot target the deal depending on the value of the accountIsExcluded parameter.

If the accountIsExcluded parameter is true, account group IDs specified in this array cannot target the deal.

An account group is a set of advertiser accounts that are managed as a group. To learn more, see Account Groups.

array Optional Optional

Read Deal

Get data for a specific deal.

GET /traffic/deals/{id}

Parameters

Table 96 Read Deal Parameters
Parameter Paramerer Type Description Data Type Required
id path Specifies the deal ID. integer Y

Example Request URL

GET https://dspapi.admanagerplus.yahoo.com/traffic/deals/2269365

Example Response

{
  "response": {
    "status": "ACTIVE",
    "id": 2269365,
    "name": "deal for targeting",
    "exchangeId": 3,
    "exchangeDealId": "43434",
    "description": "line deal",
    "reservePrice": 1,
    "spotbuy": false,
    "accountIsExcluded": false,
    "accounts": [
      1356341
    ]
  },
  "errors": null,
  "timeStamp": "2017-09-22T04:43:02Z"
}

Read Deals

Get a filtered list ofdeals.

GET /traffic/deals?query={query}&page={page}&limit={limit}&sort={sort}&dir={dir}

Parameters

Table 97 Read Deals Fields
Parameter Paramerer Type Description Data Type Required
query query

Specifies the search term.

Use URL encoding conventions (i.e. a space should be replaced with a + or %20).

string N
page query Specifies the page number. integer N
limit query Specifies the total number of items to return. The maximum value is 100. integer N
sort query Specifies the column to sort by. string N
dir query

Specifies the sort direction. Allowed values:

  • ASC: data is sorted in ascending order.
  • DESC: data is sorted in decending order.
string N

Example Request URL

GET https://dspapi.admanagerplus.yahoo.com/traffic/deals?page=1&limit=2

Example Response

{
  "response": [
   {
      "id": 1,
      "name": "Test_Deal_1",
      "exchangeId": 1,
      "exchangeDealId": "1",
      "description": "A deal description",
      "reservePrice": 0,
      "spotbuy": false,
      "status": "ACTIVE",
      "accountIsExcluded": false,
      "accounts": []
    },
    {
      "id": 2,
      "name": "Test_Deal_2",
      "exchangeId": 1,
      "exchangeDealId": "2",
      "description": "A deal description",
      "reservePrice": 0,
      "spotbuy": false,
      "status": "INACTIVE",
      "accountIsExcluded": false,
      "accounts": []
    }
  ],
  "errors": null,
  "timeStamp": "2017-04-12T04:49:06Z"
}

Update Deal

Update an existing deal.

PUT /traffic/deals/{id}

Partial updates are supported; values of supported fields which are not in the payload will remain unchanged.

Parameters

The Deal id is specified in the url path. All other fields are specified in the body of the application/json payload.

Example Request URL

PUT https://dspapi.admanagerplus.yahoo.com/traffic/deals/2269365

Example Request Body

{
  "status": "ACTIVE",
  "accounts": [1356341]
}

Example Response

{
  "response": {
    "status": "ACTIVE",
    "id": 2269365,
    "name": "Z_Auto_Deal-TEST9",
    "exchangeId": 3,
    "exchangeDealId": "43434",
    "description": "line deal",
    "reservePrice": 1,
    "spotbuy": false,
    "accountIsExcluded": false,
    "accounts": [
      1356341
    ],
    "accountGroups": []
  },
  "errors": null,
  "timeStamp": "2018-09-06T01:41:44Z"
}

Create Shared Deal

Create a new shared deal. The spotbuy parameter must be set to false.

POST /traffic/deals

Parameters

All parameters are specified in the body of the application/json payload.

Example Request URL

POST https://dspapi.admanagerplus.yahoo.com/traffic/deals

Example Request Body

{
   "response": {
       "status": "ACTIVE",
       "id": 2288331,
       "name": "testAK4",
       "exchangeId": 3,
       "exchangeDealId": "3",
       "description": "test",
       "reservePrice": 0,
       "spotbuy": false,
       "accountIsExcluded": true,
       "accountGroupId": 4,
       "accounts": [
           293457
       ],
       "accountGroups":[
          1
      ]
   },
   "errors": null,
   "timeStamp": "2018-05-25T22:47:49Z"
}

Example Response

{
  "response": {
    "status": "ACTIVE",
    "id": 2293549,
    "name": "deal for targeting 24",
    "exchangeId": 3,
    "exchangeDealId": "43434",
    "description": "line deal",
    "reservePrice": 1,
    "spotbuy": false,
    "accountIsExcluded": false,
    "accountGroupId": 2492,
    "accounts": [
      1356341
    ],
    "accountGroups": []
  },
  "errors": null,
  "timeStamp": "2018-09-06T01:52:03Z"
}

Create Spot Buy Deal

Create a new spot buy deal. The spotbuy parameter must be set to true and you must provide at least one advertiser ID in the accounts array.

POST /traffic/deals

Parameters

All parameters are specified in the body of the application/json payload.

Example Request URL

POST https://dspapi.admanagerplus.yahoo.com/traffic/deals

Example Request Body

{
  "name": "deal for targeting 25",
  "exchangeDealId": "43434",
  "description": "line deal",
  "reservePrice": 1,
  "exchangeId": 3,
  "spotbuy": true,
  "status": "ACTIVE",
  "accountIsExcluded": false,
  "accounts": [
    1356341
  ],
  "accountGroupId": 2492
}

Example Response

{
  "response": {
    "status": "ACTIVE",
    "id": 2293550,
    "name": "deal for targeting 25",
    "exchangeId": 3,
    "exchangeDealId": "43434",
    "description": "line deal",
    "reservePrice": 1,
    "spotbuy": true,
    "accountIsExcluded": false,
    "accountGroupId": 2492,
    "accounts": [
      1356341
    ],
    "accountGroups": []
  },
  "errors": null,
  "timeStamp": "2018-09-06T02:02:02Z"
}

Delete Deal

The DSP Traffic API does not support deletion of deals.