> ## Documentation Index
> Fetch the complete documentation index at: https://developers.criteo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Ad Set-Level Targeting

export const EndpointBadge = ({method = "GET", children}) => {
  const METHOD_STYLES = {
    GET: {
      bg: "mint-bg-[#2AB673]"
    },
    POST: {
      bg: "mint-bg-[#3064E3]"
    },
    PUT: {
      bg: "mint-bg-[#C28C30]"
    },
    PATCH: {
      bg: "mint-bg-[#DA622B]"
    },
    DELETE: {
      bg: "mint-bg-[#CB3A32]"
    },
    API: {
      bg: "mint-bg-black"
    }
  };
  const key = method.toUpperCase();
  const styles = METHOD_STYLES[key] ?? METHOD_STYLES.API;
  return <div className="relative mt-7">
      <span className={`absolute -top-2 -left-2 z-10 ${styles.bg} text-white px-2.5 py-0.5 rounded-full text-xs font-bold tracking-wide`}>
        {key}
      </span>
      {children}
    </div>;
};

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**<br />/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**<br />/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**<br />/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.

<EndpointBadge method="get">
  ```http theme={null}
  https://api.criteo.com/preview/marketing-solutions/ad-sets/{ad-set-id}/targeting/deal-ids
  ```
</EndpointBadge>

**Parameters**

| Field Name                    | Type   | Description |
| ----------------------------- | ------ | ----------- |
| **ad-set-id**<br />*required* | string | Ad-set id.  |

```json Sample Response Body theme={null}
{
    "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? */
    ]
}
```

<Info>
  **Available SupplyVendors**

  You can find the list of available Supply Vendors for the advertiser using the GET request described [here](/marketing-solutions/v2026-preview/docs/ad-set-level-targeting#validation-errors-and-warnings).
</Info>

<Danger>
  **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.
</Danger>

### **Set Targeting Deal Ids for an Ad Set**

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

<EndpointBadge method="put">
  ```http theme={null}
  https://api.criteo.com/preview/marketing-solutions/ad-sets/{ad-set-id}/targeting/deal-ids
  ```
</EndpointBadge>

**Parameters**

| Field Name                    | Type   | Description |
| ----------------------------- | ------ | ----------- |
| **ad-set-id**<br />*required* | string | Ad-set id.  |

<Danger>
  **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
</Danger>

<CodeGroup>
  ```json Sample Body Request theme={null}
  {
      "data":
      {
          "type": "AdSetTargetingDealIds",
          "attributes": {
              "dealIds": [
                  {
                      "dealIdentifier": "one id",
                      "supplyVendorId": "another id"
                  },...
              ]
          }
      }
  }
  ```

  ```json Sample Response Body theme={null}
  {
      "data": null,
      "errors": [ /* omitted if no errors */
          ... /* list of potential specific error? */
      ],
      "warnings": [ /* omitted if no warnings*/
          ... /* list of potential specific warning? */
      ]
  }
  ```
</CodeGroup>

### **Disable Targeting Deal Ids for an Ad Set**

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

<EndpointBadge method="post">
  ```http theme={null}
  https://api.criteo.com/preview/marketing-solutions/ad-sets/{ad-set-id}/targeting/deal-ids/disable
  ```
</EndpointBadge>

**Parameters**

| Field Name                    | Type   | Description |
| ----------------------------- | ------ | ----------- |
| **ad-set-id**<br />*required* | string | Ad-set id.  |

<Danger>
  **Request Handling specifications**

  * If specified AdSet is not found → forbidden
  * If everything is ok, a 200 is returned, with warnings if any
</Danger>

```json Sample Response Body theme={null}
{
    "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.

<Warning>
  **Please note**

  If there is no video positioning filter configuration (default case), the ad set can be placed anywhere.
</Warning>

 \
**List of methods**:

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

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

<EndpointBadge method="get">
  ```http theme={null}
  https://api.criteo.com/preview/marketing-solutions/ad-sets/{ad-set-id}/targeting/video-positioning
  ```
</EndpointBadge>

**Parameters**

| Field Name                    | Type   | Description |
| ----------------------------- | ------ | ----------- |
| **ad-set-id**<br />*required* | string | Ad-set id.  |

```json Sample Response Body theme={null}
{
  "data": {
    "type": "string",
    "attributes": {
      "videoPlacement": [
        "InBanner","InStream"
      ],
      "playbackMethod": [
        "AutoSoundOn"
      ],
      "skippable": "Required",
      "videoInstreamPosition": [
        "PreRoll"
      ],
      "videoPlayerSize": [
        "Small"
      ],
      "videoAspectRatio": [
        "Horizontal"
      ]
    }
  },
  "warnings": [
    ...
  ],
  "errors": [
    ...
  ]
}
```

<Warning>
  **Please note**

  If the ad set has no filters configured a 200 code will be returned, and the data node will be null.
</Warning>

 

### **Create or Update Video Positioning Filters**

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

<EndpointBadge method="put">
  ```http theme={null}
  https://api.criteo.com/preview/marketing-solutions/ad-sets/{ad-set-id}/targeting/video-positioning
  ```
</EndpointBadge>

**Parameters**

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

<Danger>
  **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](/marketing-solutions/v2026-preview/docs/ad-set-level-targeting#disable-video-positioning-filters).
  * 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.
</Danger>

<CodeGroup>
  ```json Sample Body Request theme={null}
  {
    "data": {
      "type": "string",
      "attributes": {
        "videoPlacement": [
          "InBanner", "InStream"
        ],
        "playbackMethod": [
          "AutoSoundOn"
        ],
        "skippable": "Required",
        "videoInstreamPosition": [
          "PreRoll"
        ],
        "videoPlayerSize": [
          "Small"
        ],
        "videoAspectRatio": [
          "Horizontal"
        ]
      }
    }
  }
  ```

  ```json Sample Body Response theme={null}
  {
    "data": {
      "type": "string",
      "attributes": {}
    },
    "warnings": [
      ...
    ],
    "errors": [
      ...
    ]
  }
  ```
</CodeGroup>

 

### **Disable Video Positioning Filters**

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

<EndpointBadge method="post">
  ```http theme={null}
  https://api.criteo.com/preview/marketing-solutions/ad-sets/{ad-set-id}/targeting/video-positioning/disable
  ```
</EndpointBadge>

**Parameters**

| Field Name                    | Type   | Description |
| ----------------------------- | ------ | ----------- |
| **ad-set-id**<br />*required* | string | Ad-set id   |

<CodeGroup>
  ```json Sample Body Request theme={null}
  {}
  ```

  ```json Sample Body Response theme={null}
  {
    "data": {
      "type": "string",
      "attributes": {}
    },
    "warnings": [
      ...
    ],
    "errors": [
      ...
    ]
  }
  ```
</CodeGroup>

 

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

<EndpointBadge method="get">
  ```http theme={null}
  https://api.criteo.com/preview/marketing-solutions/ad-sets/targeting/supply-vendors
  ```
</EndpointBadge>

<CodeGroup>
  ```json Sample Response Body theme={null}
  {
      "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? */
      ]
  }
  ```
</CodeGroup>

<Danger>
  **Request Handling specifications**

  * Invalid or inactive supply vendors are filtered out
</Danger>

## **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.<br />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. |