Exchange Targeting¶

This article describes resources that enable you to read and define exchange targeting.

Overview¶

A line can target one or more publishers, available private marketplace deals and inventory sets.

Publisher. To learn more, refer to Exchanges.
Deal. To learn more, refer to Deals.
Inventory Sets. To learn more, refer to Inventory Sets.

The Yahoo DSP supports EXCHANGES targeting for lines serving display and video ads.

Endpoint¶

/traffic/lines/{id}/targeting

A GET request enables you to view exchanges targeted by the specified line.
A POST request enables you to target exchanges with the specified line.

Resources¶

The targeting resource is the standard Yahoo DSP resource for targeting consumers based on their profiles, behaviors, and ad content.

The targeting resource is defined by the following EXCHANGES targeting type-specific fields:

Parameter	Parameter Type	Definition	Data Type	Required
`id`	path	Specifies the line ID.	`integer`	Y
`publishers`	body	Specifies the IDs of the exchanges to target.	`array`	Y
`includePublishers`	body	Indicates if the added Publisher IDs are to be targeted (included) or blocked (excluded). `true` - (Default Value) All IDs in the `publishers` field will be targeted (included). `false` - All IDs in the `publishers` field will be blocked (excluded).	`boolean`	N
`deals`	body	Specifies private marketplace deals to target. To learn more, refer to Deals Payload Object.	`array`	Y
`dealsIncluded`	body	A read-only array that identifies the private marketplace deals targeted for the line. For detailed field reference, refer to Deal.	`array`	N/A
`publishersIncluded`	body	A read-only array that identifies the publishers/exchanges included in targeting. For detailed field reference, refer to Exchange.	`array`	N/A
`publishersExcluded`	body	A read-only array that identifies the publishers/exchanges excluded from targeting. For detailed field reference, refer to Exchange.	`array`	N/A
`inventorySets`	body	The IDs of the inventory sets to be targeted or blocked. For more details, refer to Inventory Sets.	`array`	N
`inventorySetsIncluded`	body	Indicates if the added inventory set IDs are to be targeted (included) or blocked (excluded). `true` - (Default Value) All IDs in the `inventorySets` field will be targeted (included). `false` - All IDs in the `inventorySets` field will be blocked (excluded).	`boolean`	Y
`priorityBuckets`	body	An array that contains 2 or 3 priority buckets. Each bucket contains targeted deals and exchanges and has an assigned priority. For details, refer to Priority Bucket Post Object and Priority Bucket Get Object.	`array`	N/A

Note

For a complete list of targeting resource fields, refer to Targeting Object.

Deals Payload Object¶

You can use the deals object to add or update the deals that a line targets. The object contains the following fields:

Name	Description	Data Type
`added`	Specifies an array of deals to target. Deals are identified by `dealId`. To retrieve a list of deals for targeting, use the Read Target Deals resource.	`array`
`removed`	Deal IDs to be removed from targeting.	`array`
`clearAll`	Indicates if all existing targeted deals should be removed. By default, `false`. If `true`, remove all targeted deals. This will disable `EXCHANGES` targeting. If `false`, do not remove any targeted deals.	`boolean`

Name

Description

Data Type

added

Specifies an array of deals to target. Deals are identified by dealId.

To retrieve a list of deals for targeting, use the Read Target Deals resource.

array

removed

Deal IDs to be removed from targeting.

array

clearAll

Indicates if all existing targeted deals should be removed. By default, false.

If true, remove all targeted deals. This will disable EXCHANGES targeting.
If false, do not remove any targeted deals.

boolean

Priority Bucket Post Object¶

Use the priorityBucket object to prioritize certain deals and publishers when you target inventory. The object contains the following fields:

Name	Description	Data Type
`id`	The unique identifier for a particular bucket. If it is null, DSP creates a new bucket.	`integer`
`bucketPriority`	Represents the priority assigned to the current priority bucket; two buckets cannot have the same priority. The priority can have one of the following values: `TOP_PRIORITY_BUCKET`, `SECOND_PRIORITY_BUCKET`, `THIRD_PRIORITY_BUCKET`.	`string`
`publishers`	Specifies the exchange IDs that DSP targets in the current priority bucket. DSP includes or excludes exchanges, depending on the `publishersIncluded` flag.	`array`
`publishersIncluded`	Indicates if the publishers added to this bucket are either all included or excluded. If `true`, all selected publishers are included. If `false`, all selected publishers are excluded.	`boolean`
`deals`	Specifies the private marketplace deals that DSP will target in the current priority bucket. For details, refer to Deals Payload Object.	`array`
`inventorySets`	The IDs of the inventory sets to be targeted or blocked. For more details, refer to Inventory Sets.	`array`
`inventorySetsIncluded`	Indicates if the added inventory set IDs are to be targeted (included) or blocked (excluded). `true` - (Default Value) All IDs in the `inventorySets` field will be targeted (included). `false` - All IDs in the `inventorySets` field will be blocked (excluded).	`boolean`

Priority Bucket Get Object¶

The priorityBucket response object differs a bit from the object used for POST. It contains the following fields:

Name	Description	Data Type
`id`	The unique identifier for a particular bucket.	`integer`
`bucketPriority`	The priority DSP assigns to the current bucket; two buckets cannot have the same priority. The priority can have one of the following values: `TOP_PRIORITY_BUCKET`, `SECOND_PRIORITY_BUCKET`, `THIRD_PRIORITY_BUCKET`.	`string`
`publishersIncluded`	A read-only array that contains the publisher IDs or exchange IDs that DSP will target in the current priority bucket. For details, refer to Exchange.	`array`
`publishersExcluded`	A read-only array that contains the publisher IDs or exchange IDs that DSP will exclude from targeting (across all priority buckets). For details, refer to Exchange.	`array`
`dealsIncluded`	A read-only array that contains the private marketplace deals that DSP will target in the current priority bucket. For details, refer to Deal.	`array`
`inventorySetsIncluded`	A read-only array that contains the inventory set IDs that will be targeted in the current priority bucket. For more details, refer to Inventory Sets.	`array`
`inventorySetsExcluded`	A read-only array that contains the inventory set IDs that will be blocked in the current priority bucket. For more details, refer to Inventory Sets.	`array`

Read Target Exchanges¶

To get a list of available publishers/exchanges, refer to Exchanges.

Read Target Deals¶

Retrieves a list of deals that may be targeted for the specified line.

GET /traffic/targeting/deals?accountId={accountId}&lineId={lineId}&query={query}

All of the accepted parameters are query parameters.

Parameters¶

Parameter	Description	Data Type	Required
`accountId`	Specifies the advertiser ID.	`integer`	N
`lineId`	Specifies the line ID.	`integer`	Y
`query`	Specifies the search term. Use URL encoding conventions (i.e. a space should be replaced with a `+` or `%20`). Provide a partial search string or leave it empty to get all results.	`string`	Y

Sample Request URL¶

GET https://dspapi.admanagerplus.yahoo.com/traffic/targeting/deals?lineId=365277&query=spot

Sample Response¶

{
  "response": [
    {
      "status": "ACTIVE",
      "id": 102,
      "name": "nospotbuy",
      "exchangeId": 3,
      "exchangeDealId": "nospotbuy",
      "description": "nospotbuy",
      "reservePrice": 0,
      "spotbuy": false,
      "accountIsExcluded": false
    },
    {
      "status": "ACTIVE",
      "id": 89,
      "name": "spotbuydeal",
      "exchangeId": 9,
      "exchangeDealId": "1233",
      "description": "spotbuy",
      "reservePrice": 1,
      "spotbuy": false,
      "accountIsExcluded": false
    }
  ],
  "errors": null,
  "timeStamp": "2017-07-13T04:19:40Z"
}

Add/Update Deal Targeting¶

Add or update the deals targeted by the specified line.

POST /traffic/lines/{id}/targeting/

Parameters¶

Specify the line ID in the URL path. Specify all other parameters in the body of the application/json payload.

Parameter

Parameter Type

Definition

Data Type

Required

id

path

Specifies the line ID.

integer

deals

body

Specifies a payload object that defines the deals to be added, removed, or cleared for targeting.

object

types

body

Specifies an array of targeting types to update, enable, or disable.

EXCHANGES targeting type must be specified to apply the changes.

To learn more, refer to Targeting Types.

array

Sample Request URL¶

POST https://dspapi.admanagerplus.yahoo.com/traffic/lines/365277/targeting/

Sample Request Body¶

{
  "deals": {
    "removed": [],
    "clearAll": false,
    "added": [
      2264423
    ]
  },
  "types": [
    {
      "name": "EXCHANGES",
      "isTargeted": true
    }
  ]
}

Sample Response¶

{
  "response": {
    "types": [
      {
        "name": "EXCHANGES",
        "isTargeted": true
      }
    ],
    "dealsIncluded": [
      {
        "id": 2264423,
        "name": "deal for targeting",
        "exchangeId": 3,
        "exchangeDealId": "43434",
        "description": "line deal",
        "reservePrice": 1,
        "spotbuy": false,
        "accountIsExcluded": false,
        "status": "ACTIVE"
      }
    ]
  },
  "errors": null,
  "timeStamp": "2019-10-17T13:46:22.796Z"
}

Add/Remove Publisher Targeting¶

Add or update the publishers targeted by the specified line.

POST traffic/lines/{id}/targeting/

Parameters¶

Specify the line ID in the URL path. Specify all other parameters in the body of the application/json payload.

Parameter	Parameter Type	Definition	Data Type	Required
`id`	path	Specifies the line ID.	`integer`	Y
`publishers`	body	Specifies an array of publishers to target.	`array`	Y
`includePublishers`	body	Indicates if the added Publisher IDs are to be targeted (included) or blocked (excluded). `true` - (Default Value) All IDs in the `publishers` field will be targeted (included). `false` - All IDs in the `publishers` field will be blocked (excluded).	`boolean`	N
`types`	body	Specifies an array of targeting types to update, enable, or disable. `EXCHANGES` targeting type must be specified to apply the changes. To learn more, refer to Targeting Types.	`array`	Y

Sample Request URL¶

POST traffic/lines/365277/targeting/

Sample Request Body¶

{
  "publishers": [
    1,
    2
  ],
  "includePublishers": true,
  "types": [
    {
      "name": "EXCHANGES",
      "isTargeted": true
    }
  ]
}

Sample Response¶

{
  "response": {
    "types": [
      {
        "name": "EXCHANGES",
        "isTargeted": true
      }
    ],
    "publishersIncluded": [
      {
        "id": 1,
        "name": "MoPub"
      },
      {
        "id": 2,
        "name": "One by AOL: Mobile"
      }
    ]
  },
  "errors": null,
  "timeStamp": "2019-10-17T13:54:40.077Z"
}

Add/Update Inventory Set Targeting¶

Add or update the inventory sets to be targeted or blocked by the specified line.

POST /traffic/lines/{id}/targeting/

Parameters¶

Specify the line ID in the URL path. Specify all other parameters in the request body.

Parameter	Parameter Type	Definition	Data Type	Required
`id`	path	Specifies the line ID.	`integer`	Y
`inventorySets`	body	Specifies an array of inventory sets to target or block.	`array`	Y
`inventorySetsIncluded`	body	Indicates if the added inventory set IDs are to be targeted (included) or blocked (excluded). true - (Default Value) All IDs in the inventorySets field will be targeted (included). false - All IDs in the inventorySets field will be blocked (excluded).	`boolean`	Y
`types`	body	Specifies an array of targeting types to update, enable, or disable. `EXCHANGES` targeting type must be specified to apply the changes. To learn more, refer to Targeting Types.	`array`	Y

Sample Request URL¶

POST /traffic/lines/1893493/targeting

Sample Request Body¶

{
 "id":1893493,
 "inventoryTypes":[
    "WEB"
 ],
 "positions":[
    "UNKNOWN"
 ],
 "bots":[
    "IAS"
 ],
 "siteLists":{
    "clearAll":false,
    "added":[

    ]
 },
 "contextuals":{
    "addedDoubleVerifyAuthenticBrandSafety":[

    ],
    "addedIAB":[

    ],
    "excludeIAB":true
 },
 "deals":{
    "removed":[

    ],
    "added":[

    ]
 },
 "publishers":[
    1
 ],
 "includePublishers":true,
 "inventorySets":[
    428
 ],
 "inventorySetsIncluded":true,
 "mobilePlacements":[
    "REWARDED"
 ],
 "types":[
    {
       "name":"INVENTORY_TYPE",
       "isTargeted":true
    },
    {
       "name":"AD_POSITION",
       "isTargeted":true
    },
    {
       "name":"BOT",
       "isTargeted":true
    },
    {
       "name":"SITE_LISTS",
       "isTargeted":true
    },
    {
       "name":"CONTEXTUALS",
       "isTargeted":true
    },
    {
       "name":"EXCHANGES",
       "isTargeted":true
    },
    {
       "name":"MOBILE_PLACEMENT",
       "isTargeted":true
    }
 ]
}

Sample Response¶

{
  "response": {
      "enableViewabilityFreqCap": false,
      "frequencyCapValue": 0,
      "serveUnknownUser": true,
      "frequencyCapPeriod": "UNLIMITED",
      "hhFrequencyCapEnabled": false,
      "lineFrequencyCap": {
          "frequencyCapValueMinute": 1,
          "frequencyCapValueHour": 1,
          "frequencyCapValueDay": 0,
          "frequencyCapValueWeek": 2,
          "frequencyCapValueMonth": 0,
          "frequencyCapPeriodMultiHour": 0,
          "frequencyCapValueMultiHour": 0,
          "lineId": 1893493
      },
      "adInitiations": [
          "ALL"
      ],
      "playerSizes": [
          "ALL"
      ],
      "bots": [
          "IAS"
      ],
      "positions": [
          "UNKNOWN"
      ],
      "weatherTemperatures": {
          "allTemperatures": true
      },
      "weatherConditions": [
          "ALL"
      ],
      "weatherUVs": [
          "ALL"
      ],
      "weatherHumidities": {
          "allHumidities": true
      },
      "inventoryTypes": [
          "WEB"
      ],
      "languages": [
          "ALL"
      ],
      "browsers": [
          "ALL"
      ],
      "mobileBrowsers": [
          "ALL"
      ],
      "os": [
          "ALL"
      ],
      "mobileOs": [
          "ALL"
      ],
      "deviceTypes": [
          "ALL"
      ],
      "videoContentLength": [
          "ALL"
      ],
      "mobileMakes": [
          "ALL"
      ],
      "mobileModels": [
          "ALL"
      ],
      "publishersIncluded": [
          {
              "id": 1,
              "name": "MoPub"
          }
      ],
      "geosIncluded": [
          {
              "id": "########can",
              "name": "Canada",
              "level": "Country",
              "key": "can",
              "excluded": false,
              "woeid": "23424775"
          }
      ],
      "geosExcluded": [],
      "mobileCarriers": [
          "ALL"
      ],
      "isps": [
          "ALL"
      ],
      "mobilePlacements": [
          "REWARDED"
      ],
      "types": [
          {
              "isTargeted": true,
              "name": "PRIORITIZED_INVENTORY"
          },
          {
              "isTargeted": true,
              "name": "GEOGRAPHY"
          },
          {
              "isTargeted": false,
              "name": "DEMOGRAPHIC"
          },
          {
              "isTargeted": true,
              "name": "INVENTORY_TYPE"
          },
          {
              "isTargeted": false,
              "name": "WEATHER"
          },
          {
              "isTargeted": false,
              "name": "AUCTION_TYPE"
          },
          {
              "isTargeted": false,
              "name": "MOBILE_MEASUREMENT"
          },
          {
              "isTargeted": false,
              "name": "SELLER_RELATIONSHIPS"
          },
          {
              "isTargeted": true,
              "name": "AD_POSITION"
          },
          {
              "isTargeted": false,
              "name": "VIEWABILITY"
          },
          {
              "isTargeted": true,
              "name": "FREQUENCY_CAPPING"
          },
          {
              "isTargeted": false,
              "name": "AB_TESTING"
          },
          {
              "isTargeted": false,
              "name": "SEGMENT"
          },
          {
              "isTargeted": false,
              "name": "TECHNOLOGY"
          },
          {
              "isTargeted": false,
              "name": "DAY_PARTING"
          },
          {
              "isTargeted": false,
              "name": "ENHANCED_DAY_PARTING"
          },
          {
              "isTargeted": false,
              "name": "SITE_LISTS"
          },
          {
              "isTargeted": false,
              "name": "CONTEXTUALS"
          },
          {
              "isTargeted": false,
              "name": "LANGUAGES"
          },
          {
              "isTargeted": true,
              "name": "EXCHANGES"
          },
          {
              "isTargeted": false,
              "name": "CONNECTION"
          },
          {
              "isTargeted": false,
              "name": "SEAT_LEVEL_SITE_LISTS"
          },
          {
              "isTargeted": true,
              "name": "MOBILE_PLACEMENT"
          },
          {
              "isTargeted": true,
              "name": "SEAT_LEVEL_CONTEXTUALS"
          },
          {
              "isTargeted": true,
              "name": "BOT"
          },
          {
              "isTargeted": true,
              "name": "AUDIENCE_ESCALATION_TYPE"
          },
          {
              "isTargeted": false,
              "name": "USER_IDENTITY_BIDDING_GROUP"
          },
          {
              "isTargeted": true
          }
      ],
      "enableSegmentExpansion": false,
      "isAllCountriesTargeted": false,
      "inventorySetsIncluded": [
          {
              "id": 428,
              "name": "Traffic inventory set test",
              "parentAccountId": 12345,
              "count": 2,
              "createdDate": "2023-06-21T10:23:41Z",
              "lastModifiedDate": "2023-06-21T10:31:30Z",
              "createdBy": "Vukašin Djuketi?",
              "lastModifiedBy": "Vukašin Djuketi?",
              "publishers": [
                  {
                      "id": 1,
                      "name": "MoPub"
                  }
              ],
              "status": "ACTIVE",
              "dealsList": [
                  {
                      "id": 6,
                      "name": "test",
                      "exchangeDealId": "123123",
                      "exchangeId": 3,
                      "accounts": [],
                      "accountGroups": [],
                      "programmaticGuaranteed": true,
                      "status": "ACTIVE",
                      "restricted": false
                  }
              ],
              "advertiserSharingSettings": {
                  "type": "ALL",
                  "advertisers": []
              }
          }
      ],
      "inventorySetsExcluded": []
  },
  "errors": null,
  "timeStamp": "2023-06-21T10:49:52.549Z"
}

Add/Update/Remove Priority Bucket Targeting¶

Add, update or remove priority buckets that contain targeted deals and targeted publishers for a specific line.

POST /traffic/lines/{id}/targeting/

Parameters¶

Specify the line ID in the URL path. Specify all other parameters in the body of the application/json payload.

Parameter	Parameter Type	Definition	Data Type	Required
`id`	path	Specify the line ID.	`integer`	Y
`priorityBuckets`	body	Specify an array of priority buckets. Priority buckets are payload objects that define the deals and publishers that DSP should target, and define the priority of those deals and publishers. For details, refer to Priority Bucket Post Object and Priority Bucket Get Object.	`array`	Y
`types`	body	Specify the array of targeting types to be updated, enabled, or disabled. The `EXCHANGES` targeting type must be added in order to apply the changes. For details, refer to Targeting Types.	`array`	Y

Parameter

Parameter Type

Definition

Data Type

Required

id

path

Specify the line ID.

integer

priorityBuckets

body

Specify an array of priority buckets. Priority buckets are payload objects that define the deals and publishers that DSP should target, and define the priority of those deals and publishers.

For details, refer to Priority Bucket Post Object and Priority Bucket Get Object.

array

types

body

Specify the array of targeting types to be updated, enabled, or disabled.

The EXCHANGES targeting type must be added in order to apply the changes.

For details, refer to Targeting Types.

array

Sample Request URL¶

POST https://dspapi.admanagerplus.yahoo.com/traffic/lines/365277/targeting/

Sample Request Body¶

{
  "priorityBuckets": [
    {
      "id": null,
      "bucketPriority": "TOP_PRIORITY_BUCKET",
      "publishers": [],
      "publishersIncluded": true,
      "deals": {
        "added": [
          11,
          14
        ],
        "removed": [],
        "clearAll": false
      }
    },
    {
      "id": null,
      "bucketPriority": "SECOND_PRIORITY_BUCKET",
      "publishers": [
        3
      ],
      "publishersIncluded": true,
      "deals": {
        "added": [
          7
        ],
        "removed": [],
        "clearAll": false
      }
    },
    {
      "id": null,
      "bucketPriority": "THIRD_PRIORITY_BUCKET",
      "publishers": [
        4,
        5
      ],
      "publishersIncluded": true,
      "deals": {
        "added": [],
        "removed": [],
        "clearAll": false
      }
    }
  ],
  "types": [
    {
      "name": "EXCHANGES",
      "isTargeted": true
    }
  ]
}

Sample Response¶

{
  "response": {
    "types": [
      {
        "name": "EXCHANGES",
        "isTargeted": true
      }
    ],
    "priorityBuckets": [
      {
        "id": 2736,
        "bucketPriority": "TOP_PRIORITY_BUCKET",
        "dealsIncluded": [
          {
            "id": 11,
            "name": "Testing",
            "exchangeId": 4,
            "exchangeDealId": "123",
            "description": "asd",
            "spotbuy": false,
            "accountIsExcluded": false,
            "status": "INACTIVE"
          },
          {
            "id": 14,
            "name": "asdjaldk",
            "exchangeId": 4,
            "exchangeDealId": "laskdj",
            "description": "alskdj",
            "reservePrice": 12,
            "spotbuy": false,
            "accountIsExcluded": false,
            "status": "ACTIVE"
          }
        ],
        "publishersIncluded": [],
        "publishersExcluded": []
      },
      {
        "id": 2737,
        "bucketPriority": "SECOND_PRIORITY_BUCKET",
        "dealsIncluded": [
          {
            "id": 7,
            "name": "bryan",
            "exchangeId": 3,
            "exchangeDealId": "123123",
            "description": "testing",
            "reservePrice": 123.45,
            "spotbuy": false,
            "accountIsExcluded": false,
            "status": "ACTIVE"
          }
        ],
        "publishersIncluded": [
          {
            "id": 3,
            "name": "Yahoo Exchange"
          }
        ],
        "publishersExcluded": []
      },
      {
        "id": 2738,
        "bucketPriority": "THIRD_PRIORITY_BUCKET",
        "dealsIncluded": [],
        "publishersIncluded": [
          {
            "id": 4,
            "name": "Rubicon"
          },
          {
            "id": 5,
            "name": "OpenX"
          }
        ],
        "publishersExcluded": []
      }
    ]
  },
  "errors": null,
  "timeStamp": "2020-08-20T13:46:22.796Z"
}

Exchange Targeting¶

Overview¶

Endpoint¶

Resources¶

Deals Payload Object¶

Priority Bucket Post Object¶

Priority Bucket Get Object¶

Read Target Exchanges¶

Read Target Deals¶

Parameters¶

Sample Request URL¶

Sample Response¶

Add/Update Deal Targeting¶

Parameters¶

Sample Request URL¶

Sample Request Body¶

Sample Response¶

Add/Remove Publisher Targeting¶

Parameters¶

Sample Request URL¶

Sample Request Body¶

Sample Response¶

Add/Update Inventory Set Targeting¶

Parameters¶

Sample Request URL¶

Sample Request Body¶

Sample Response¶

Add/Update/Remove Priority Bucket Targeting¶

Parameters¶

Sample Request URL¶

Sample Request Body¶

Sample Response¶

Additional Resources¶