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

You can use this endpoint to read, create, and update deal objects.

/traffic/deals

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

  • Use the GET method to read existing deals.
  • Use the POST method to add new deals.
  • Use the PUT method to update existing deals.

Resources

The deals resource is defined by the following following fields:

Table 106 Deal Object Fields
Name Description Type Add Update
id Specifies the deal ID. integer N/A Required
name Specifies the name of the deal. string Required Required
status

Specifies the current status of the deal. Options include:

  • If ACTIVE, the deal is active.
  • If INACTIVE, the deal is inactive.
string Required Required
exchangeId

Specifies the exchange ID.

To learn more, see Exchanges.

integer Required Required
exchangeDealId Specifies the unique ID for the deal on the exchange. string Required Required
description Specifies a brief description of the deal. string Required Required
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.

  • If 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.
  • If 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:

  • If true, all advertisers may target the deal except those specified in accounts and accountGroups array parameters.
  • If 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 Deals by ID

Returns the deal data for the specified deal ID.

GET /traffic/deals/{id}

Parameters

The resource takes a single parameter that is specified in the path of the endpoint.

Table 107 Read Deals by ID Parameters
Parameter Parameter Type Description Data Type Required?
id path Specifies the deal ID. integer Y

Example Request

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 by Query

Returns a list of deals that meet the specified query parameters.

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

Parameters

The resource takes multiple query parameters that can you can append to the endpoint path.

Table 108 Read Deals by Query Parameters
Parameter Parameter Type Description Data Type Required?
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. Options include:

  • If ASC, data is sorted in ascending order.
  • If DESC, data is sorted in decending order.
string N
query query

Specifies the search term.

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

string N

Example Request

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 Deals

Updates an existing deal.

PUT /traffic/deals/{id}

The deal id parameter is specified in the endpoint path. All other parameters are specified in the body of the application/json payload.

Note

Partial updates are supported; fields that are either not passed or passed as null are ignored.

Parameters

The id parameter is specified in the endpoint path. All other parameters are specified in the body of the application/json payload.

Table 109 Update Deal Parameters
Name Path Description Type Required
id path Specifies the deal ID. integer Y
name body Specifies the name of the deal. string N
status body

Specifies the current status of the deal. Options include:

  • If ACTIVE, the deal is active.
  • If INACTIVE, the deal is inactive.
string Y
exchangeId body

Specifies the exchange ID.

To learn more, see Exchanges.

integer N
exchangeDealId body Specifies the unique ID of the deal on the exchange. string N
description body Specifies a brief description of the deal. string N
reservePrice body Acceptable reserve price for the deal. number N
spotbuy body

Indicates that the deal is a spot buy.

  • If true, the deal is a spot buy deal and you must specify at least one advertiser in the accounts array and ensure that accountIsExcluded is set to false.
  • If false, the deal is a shared deal.
boolean N
accountGroupId body

Specifies an account group that can target the deal.

To learn more, see Account Groups.

number N
accountIsExcluded body

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

  • If true, all advertisers may target the deal except those specified in the accounts and accountGroups array parameters.
  • If false, an advertiser may target the only if it is specified in the accounts and accountGroups array parameters.
boolean N
accounts body

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 N
accountGroups body

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 N

Example Request

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

Example Payload

{
  "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 Deals

Creates 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.

Table 110 Create Shared Deals Parameters
Name Path Description Type Required
name body Specifies the name of the deal. string Y
status body

Specifies the current status of the deal.

  • If ACTIVE, the deal is active.
  • If INACTIVE, the deal is inactive.
string Y
exchangeId body

Specifies the exchange ID.

To learn more, see Exchanges.

integer Y
exchangeDealId body Specifies the unique ID for the deal on the exchange. string Y
description body Specifies a deal description. string Y
reservePrice body Specifies an acceptable reserve price for the deal. number N
spotbuy body

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

For shared deals, the spotbuy attribute must be false.

boolean Y
accountIsExcluded body

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

  • If true, all advertisers may target the deal except those specified in the accounts and accountGroups array parameters.
  • If false, an advertiser may target the only if it is specified in the accounts and accountGroups array parameters.
boolean Y
accounts body

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 N
accountGroups body

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 N

Example Request

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

Example Payload

{
   "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 Deals

Creates a new spot buy deal.

POST /traffic/deals

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

Parameters

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

Table 111 Create Spot Buy Deal Parameters
Name Path Description Type Required
name body Specifies the name of the deal. string Y
status body

Specifies the current status of the deal.

  • If ACTIVE, the deal is active.
  • If INACTIVE, the deal is inactive.
string Y
exchangeId body

Specifies the exchange ID.

To learn more, see Exchanges.

integer Y
exchangeDealId body Specifies a unique ID for the deal on the exchange. string Y
description body Specifies a brief description of the deal. string Y
reservePrice body Specifies an acceptable reserve price for the deal. number N
spotbuy body

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

For spot buy deals, the spotbuy attribute must be true.

boolean Y
accountIsExcluded body For spot buy deals, the accountIsExcluded attribute must be false. boolean Y
accountGroupId body

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 N
accounts body

Specifies an array of advertiser IDs that can target the deal.

At least one advertiser account ID must be specified in all spot buy deals.

array Y
accountGroups body Specifies an array of account group IDs that can target the deal. array N

Example Request

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

Example Payload

{
  "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 Deals

Deal deletion is not supported by the API.