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

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

Y

deals

body

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

object

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

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"
}

Additional Resources