Exchange Targeting

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

Overview

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

  • Publisher. To learn more, see Exchanges.

  • Deal. To learn more, see Deals.

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, see 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, see Deal.

array

N/A

publishersIncluded

body

A read-only array that identifies the publishers/exchanges included in targeting.

For detailed field reference, see Exchange.

array

N/A

publishersExcluded

body

A read-only array that identifies the publishers/exchanges excluded from targeting.

For detailed field reference, see Exchange.

array

N/A

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, see Priority Bucket Post Object and Priority Bucket Get Object.

array

N/A

Note

For a complete list of targeting resource fields, see 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, see Deals Payload Object.

array

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, see 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, see Exchange.

array

dealsIncluded

A read-only array that contains the private marketplace deals that DSP will target in the current priority bucket.

For details, see Deal.

array

Read Target Exchanges

To get a list of available publishers/exchanges, see 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

Example Request URL

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

Example 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, see Targeting Types.

array

Y

Example Request URL

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

Example Request Body

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

Example 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, see Targeting Types.

array

Y

Example Request URL

POST traffic/lines/365277/targeting/

Example Request Body

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

Example Response

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

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, see 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, see Targeting Types.

array

Y

Example Request URL

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

Example 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
    }
  ]
}

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