GuidesAPI ReferenceChangelog
GuidesAPI ReferenceChangelogLog In

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.

https://api.criteo.com/preview/marketing-solutions/ad-sets/{ad-set-id}/targeting/deal-ids

Parameters

Field Name

Type

Description

ad-set-id
required

string

Ad-set id.

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

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

https://api.criteo.com/preview/marketing-solutions/ad-sets/{ad-set-id}/targeting/deal-ids

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

https://api.criteo.com/preview/marketing-solutions/ad-sets/{ad-set-id}/targeting/deal-ids/disable

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

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

https://api.criteo.com/preview/marketing-solutions/ad-sets/{ad-set-id}/targeting/video-positioning

Parameters

Field Name

Type

Description

ad-set-id
required

string

Ad-set id.

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

🚧

Please note

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

https://api.criteo.com/preview/marketing-solutions/ad-sets/{ad-set-id}/targeting/video-positioning

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.

https://api.criteo.com/preview/marketing-solutions/ad-sets/{ad-set-id}/targeting/video-positioning/disable

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

https://api.criteo.com/preview/marketing-solutions/ad-sets/targeting/supply-vendors
{
    "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.


Did this page help you?