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

# Ads

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>;
};

## **Search Ads**

### Retrieving Ads for a Specific Advertiser

Ads created through Criteo's API will be returned for the designated advertiser ID. Only ads created through API and Commerce Growth are returned.

<EndpointBadge method="get">
  ```http theme={null}
  /advertisers/{advertiserId}/ads
  ```
</EndpointBadge>

 The API will return an array of the IDs, name, description (if specified), creative ID, ad set ID, start date and end date (if specified) for the specified advertiser ID. Please note that the advertiser ID is required in the request URL. The offset and limit are optionals.

**`offset`**\
0 based index of the first ad to return in the response. The default is 0.

**`limit`**\
The number of ads to be returned. The default is 50.

```json Example Response Body theme={null}
{
    "data": [
        {
            "id": "15",
            "type": "Ad",
            "attributes": {
                "name": "My first ad",
                "description": "Description of my first ad",
                "creativeId": "18",
                "adSetId": "345",
                "startDate": "2021-09-08T08:47:30.000Z",
                "endDate": "2021-10-08T08:47:30.000Z"
            }
        },
        {
            "id": "16",
            "type": "Ad",
            "attributes": {
                "name": "My second ad",
                "description": "",
                "creativeId": "19",
                "adSetId": "346",
                "startDate": "2021-04-29T11:05:00.000Z",
                "endDate": null
            }
        }
    ],
    "warnings": [],
    "errors": []
}
```

### Retrieving a Specific Ad

Ad created through Criteo's API will be returned for the designated ad ID.

<EndpointBadge method="get">
  ```http theme={null}
  /ads/{adId}
  ```
</EndpointBadge>

 The API will return an array of the ID, name, description (if specified), creative ID, ad set ID, start date and end date (if specified) for the specified ad ID. Please note that the ad ID is required in the request URL.

```json JSON theme={null}
{
    "data": {
        "id": "15",
        "type": "Ad",
        "attributes": {
          "name": "My first ad",
          "description": "Description of my first ad",
          "creativeId": "18",
          "adSetId": "345",
          "startDate": "2021-09-08T08:47:30.000Z",
          "endDate": "2021-10-08T08:47:30.000Z"
        }
    },
    "warnings": [],
    "errors": []
}
```

***

## **Creating A New Ad**

A new ad can be created for a specific advertiser and from an existing creative by making a POST call to the ads endpoint. The request body should specify the name, description (optional), creative id, adset id, start date and end date (optional) of the new ad.

<EndpointBadge method="post">
  ```http theme={null}
  /advertisers/{advertiserId}/ads
  ```
</EndpointBadge>

<CodeGroup>
  ```json Example POST Body theme={null}
  {
    "data": {
      "type": "AdWriteRequest",
      "attributes": {
        "name": "My new ad",
        "description": "Description of my new ad",
        "creativeId": "20",
        "adSetId": "347",
        "startDate": "2021-09-08T08:47:30.000Z",
        "endDate": "2021-10-08T08:47:30.000Z"
      }
    }
  }
  ```
</CodeGroup>

The API will return an array of the ID, name, description (if specified), creative id, adset id, start date and end date (if specified) of the new ad. Please note that the advertiser ID is required in the request URL.

<Warning>
  **Ad id null at creation**

  Ad Id will be set as null in the response. The ad id will be provided after ad deployment and can be retrieved using the "Get Existing Ads" endpoints.
</Warning>

```json Example Response Body theme={null}
{
    "data": {
        "id": null,
        "type": "Ad",
        "attributes": {
          "name": "My new ad",
          "description": "Description of my new ad",
          "creativeId": "20",
          "adSetId": "347",
          "startDate": "2021-09-08T08:47:30.000Z",
          "endDate": "2021-10-08T08:47:30.000Z"
        }
    },
    "warnings": [],
    "errors": []
}
```

***

## **Deleting an ad**

An ad can be deleted by specifying the ad ID in the URL path of a DELETE call to the ads' endpoint.

<EndpointBadge method="delete">
  ```http theme={null}
  /ads/{adId}
  ```
</EndpointBadge>

The API will return an array with the ad ID that was deleted.

```json Example Response Body theme={null}
{
    "errors": [],
    "warnings": []
}
```

***

## **Validation Errors**

**`user-request-forbidden-advertiser `**\
The user doesn't have the permission to access the specified advertiser.

**`user-request-forbidden-creative`**\
The user doesn't have the permission to access the specified creative.

**`user-request-forbidden-ad`**\
The user doesn't have the permission to access the specified ad.

**`invalid-action-with-managed-creative`**\
The action cannot be performed on a managed service creative. 

**`invalid-action-with-managed-ad`**\
The action cannot be performed on a managed service ad.

**`invalid-creative-action-with-status `**\
The action cannot be performed due to the status of the creative.

**`invalid-image`**\
One of the images provided is invalid. Please check the image requirements [here](https://help.criteo.com/kb/guide/en/image-ads-8hXUBDeeoo/Steps/775688)

**`invalid-redirection-url-image`**\
The redirection URL specified doesn't match the advertiser domain.

**`invalid-html-tag`**\
One of the HTML tags is not supported. Please check the list of supported ad servers [here](https://help.criteo.com/kb/guide/en/third-party-ads-QUSq5Astwy/Steps/775787,817360)

**`invalid-creative-request`**\
Invalid request on the Creative endpoint.

**`invalid-ad-request`**\
Invalid request on the Ad endpoint.