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:

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

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

❗️

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

❗️

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:

• 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

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

❗️

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

{}

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

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