Ad Set-Level Targeting

The endpoints described in this guide can be used to set up the targeting of an ad set.

Deal ID

This endpoint provides the ability to manage Deal ID targeting configurations at the ad set level.
This would allow configuring the way ad sets can target bid requests coming. This allows configuring how your ad set will display ads on placements associated with a Deal-ID
If there is no Deal ID targeting (the default case), every open-auction bid request can be targeted.

List of methods:

HTTP Request	Description
GET /preview/marketing-solutions/ad-sets/{ad-set-id}/targeting/deal-ids	Get the list of deal-ids used for targeting filtering for the specified ad set
PUT /preview/marketing-solutions/ad-sets/{ad-set-id}/targeting/deal-ids	Set the list of deal_ids used for targeting filtering for the specified ad set
POST /preview/marketing-solutions/ad-sets/{ad-set-id}/targeting/deal-ids/disable	Disable the deal-ids targeting configuration filtering for the specified ad set

Get Targeting Deal IDs for a Ad Set

Get the list of Deal IDs used for targeting filtering for the specified ad set. Parameters

Field Name	Type	Description
ad-set-id required	string	Ad-set id.

Sample Response Body

{
    "data":
    {
        {
            "type": "AdSetTargetingDealIds",
            "attributes": {
                "dealIds": [
                    {
                       "dealIdentifier": "one id",
                       "supplyVendorId": "another id"
                    },...
                ]
            }
        }, ...
    },
    "errors": [     /* omitted if no errors */
        ... /* list of potential specific error? */
    ],
    "warnings": [     /* omitted if no warnings*/
        ... /* list of potential specific warning? */
    ]
}

Available SupplyVendorsYou can find the list of available Supply Vendors for the advertiser using the GET request described here.

Request Handling specifications

for Deal IDs that have inactive supply-vendors, they are listed but a warning is also sent for each Deal ID in this case.
if no Deal ID targeting is set, a 200 is returned with a null data
similar behavior as for the get supply-vendor targeting endpoint.

Set Targeting Deal Ids for an Ad Set

Set the list of Deal ID used for targeting filtering for the specified ad set. Parameters

Field Name	Type	Description
ad-set-id required	string	Ad-set id.

Request Handling specifications

any existing configuration is overwritten
no empty list is allowed as an input
only the valid deal-ids are supported in the list (i.e. one with an active supply-vendor)
filter the duplicate entries

{
    "data":
    {
        "type": "AdSetTargetingDealIds",
        "attributes": {
            "dealIds": [
                {
                    "dealIdentifier": "one id",
                    "supplyVendorId": "another id"
                },...
            ]
        }
    }
}

{
    "data": null,
    "errors": [ /* omitted if no errors */
        ... /* list of potential specific error? */
    ],
    "warnings": [ /* omitted if no warnings*/
        ... /* list of potential specific warning? */
    ]
}

Disable Targeting Deal Ids for an Ad Set

Disable the deal-ids targeting configuration filtering for the specified ad set Parameters

Field Name	Type	Description
ad-set-id required	string	Ad-set id.

Request Handling specifications

If specified AdSet is not found → forbidden
If everything is ok, a 200 is returned, with warnings if any

Sample Response Body

{
    "data": null,
    "errors": [ /* omitted if no errors */
        ... /* list of potential specific error? */
    ],
    "warnings": [ /* omitted if no warnings*/
        ... /* list of potential specific warning? */
    ]
}

Video Positioning

This endpoint provides the ability to manage the configuration of video targeting filters at an ad set level. You will be able to configure how your video ad sets can be placed.

Please noteIf there is no video positioning filter configuration (default case), the ad set can be placed anywhere.

List of methods:

HTTP Request	Description
GET /preview/marketing-solutions/ad-sets/{ad-set-id}/targeting/video-positioning	Get the details of all the configured filters from a video positioning targeting ad set.
PUT /preview/marketing-solutions/ad-sets/{ad-set-id}/targeting/video-positioning	Create or update the video positioning targeting filters for the specified ad set.
POST /preview/marketing-solutions/ad-sets/{ad-set-id}/targeting/video-positioning/disable	Disable the video targeting filtering configuration for the specified ad set.

If you want to see the current filters of an ad-set, use the GET endpoint.
To create a filter configuration for the first time, use the PUT endpoint. It will create and apply the filters to the selected ad-set.
To update the current filters from an ad-set, use the PUT endpoint. The request will overwrite the current configuration of the selected ad-set.
To stop using the filters applied to an ad-set, use the POST endpoint. This will disable the current configuration applied to the ad-set and return it to the default case without filters. Then, the functionality will return to the original one, and the ad set will be placed everywhere again.

Get Video Positioning Filters for a Ad Set

Get the details of all the configured filters from a video positioning targeting ad set. Parameters

Field Name	Type	Description
ad-set-id required	string	Ad-set id.

Sample Response Body

{
  "data": {
    "type": "string",
    "attributes": {
      "videoPlacement": [
        "InBanner","InStream"
      ],
      "playbackMethod": [
        "AutoSoundOn"
      ],
      "skippable": "Required",
      "videoInstreamPosition": [
        "PreRoll"
      ],
      "videoPlayerSize": [
        "Small"
      ],
      "videoAspectRatio": [
        "Horizontal"
      ]
    }
  },
  "warnings": [
    ...
  ],
  "errors": [
    ...
  ]
}

Please noteIf the ad set has no filters configured a 200 code will be returned, and the data node will be null.

Create or Update Video Positioning Filters

Create or update the video positioning targeting filters for the specified ad set. Parameters

Field Name	Type	Description	Possible values
ad-set-id required	string	Ad-set id.
videoPlacement	array < string >	The place where the video will be placed.	InBanner InArticle InFeed Interstitial InStream
playbackMethod	array < string >	Playback method.	AutoSoundOn AutoSoundOff ClickSoundOn MouseOverSoundOn EnteringViewportSoundOn EnteringViewportSoundOff
skippable	string	If the video is skippable.	Required Blocked null
videoPlayerSize	array < string >	The size of the video player.	Small Medium Large ExtraLarge
videoAspectRatio	array < string >	Aspect ratio of the video.	Horizontal Square Vertical
videoInstreamPosition	array < string >	In order to use this attribute the videoPlacement attribute must contain the InStream value.	PreRoll MidRoll PostRoll

Request Handling specifications

Any new configuration specified overwrites the existing one.
At least one filter must be set appropriately, i.e., not null and not empty. In case you want to disable the current filters and return to the default configuration, use the disable request.
A valid request must contain at least a non-null data node with non-null attributes.
To use the videoInstreamPosition field, videoPlacement must contain the “InStream” value.

{
  "data": {
    "type": "string",
    "attributes": {
      "videoPlacement": [
        "InBanner", "InStream"
      ],
      "playbackMethod": [
        "AutoSoundOn"
      ],
      "skippable": "Required",
      "videoInstreamPosition": [
        "PreRoll"
      ],
      "videoPlayerSize": [
        "Small"
      ],
      "videoAspectRatio": [
        "Horizontal"
      ]
    }
  }
}

{
  "data": {
    "type": "string",
    "attributes": {}
  },
  "warnings": [
    ...
  ],
  "errors": [
    ...
  ]
}

Disable Video Positioning Filters

Disable the video positioning filtering configuration for the specified ad set. Parameters

Field Name	Type	Description
ad-set-id required	string	Ad-set id

{}

{
  "data": {
    "type": "string",
    "attributes": {}
  },
  "warnings": [
    ...
  ],
  "errors": [
    ...
  ]
}

Supply-vendors

This endpoint provides the ability to get a list of active supply vendors.

Get List of available SupplyVendors

List available SupplyVendors for advertiser users

{
    "data":
    [
        {
            "type": "SupplyVendor",
            "id": "1224323412",
            "attributes": {
                "name": "my SSP name"
            }
        }, ...
    ],
    "errors": [     /* omitted if no errors */
        ... /* list of potential specific error? */
    ],
    "warnings": [     /* omitted if no warnings*/
        ... /* list of potential specific warning? */
    ]
}

Request Handling specifications

Invalid or inactive supply vendors are filtered out

Validation Errors and Warnings

In addition to general API errors, you may encounter validation errors when creating or managing targetings. Below is a list of error codes for Video Positioning validation and a more detailed description of their meaning.

Error code	Description
campaign—deal-ids—empty-deal-id-list-not-allowed	The API consumer cannot send an empty list of dealIds. this error is also issued if the list empty because every provided dealId has inactive supply-vendors

Warning code	Description
campaign—deal-ids—unsupported-supply-vendor	The provided list contains a dealId with an invalid or inactive supply vendor
campaign—deal-ids—inactive-supply-vendors	The configuration contains a Deal ID with an inactive supply-vendors

Below is a list of error codes for Deal IDs validation and a more detailed description of their meaning.

Error code	Description
campaign—video-positioning—only-video-type-adset-supported	The ad set type is not video, it will return a 400 error code.
campaign—video-positioning—empty-video-rule-filters-not-allowed	The payload data was sent with an empty filter list.
campaign—video-positioning—video-rule-filters-all-null-not-allowed	The payload data was sent with all filters set to null.
campaign—video-positioning—instream-position-and-not-in-video-placement	The payload data was sent with instream position values without setting instream in video placement.

Preview Endpoints

MarketPlace Outcome (MPO)

Ad Set-Level Targeting

Deal ID

Get Targeting Deal IDs for a Ad Set

Set Targeting Deal Ids for an Ad Set

Disable Targeting Deal Ids for an Ad Set

Video Positioning

Get Video Positioning Filters for a Ad Set

Create or Update Video Positioning Filters

Disable Video Positioning Filters

Supply-vendors

Get List of available SupplyVendors

Validation Errors and Warnings

​Deal ID

​Get Targeting Deal IDs for a Ad Set

​Set Targeting Deal Ids for an Ad Set

​Disable Targeting Deal Ids for an Ad Set

​Video Positioning

​Get Video Positioning Filters for a Ad Set

​Create or Update Video Positioning Filters

​Disable Video Positioning Filters

​Supply-vendors

​Get List of available SupplyVendors

​Validation Errors and Warnings

Deal ID

Get Targeting Deal IDs for a Ad Set

Set Targeting Deal Ids for an Ad Set

Disable Targeting Deal Ids for an Ad Set

Video Positioning

Get Video Positioning Filters for a Ad Set

Create or Update Video Positioning Filters

Disable Video Positioning Filters

Supply-vendors

Get List of available SupplyVendors

Validation Errors and Warnings