---
updatedAt: 2026-06-28T20:00:39.000Z
agentTools:
  projectIndex: https://developers.taboola.com/backstage-api/llms.txt
---

# Upload display ads by URL

Create and update display ad [campaign items](https://developers.taboola.com/backstage-api/docs/campaign-items-overview) by providing a URL to your creative asset. The system downloads the asset from the URL, validates it, uploads it to the Taboola CDN, and creates the display ad — no direct file upload required. Just provide an HTTPS URL pointing to your image or video asset.

> 📘 Display ads
>
> Display ads are graphical advertisements in fixed ad placements, delivered as static images, video, or animated HTML5 at standard IAB sizes (e.g. `300x250`, `728x90`, `300x600`). Unlike native ads, they are visually distinct from the surrounding page and immediately recognizable as advertising.
>
> Display ads use [`creative_type`](https://developers.taboola.com/backstage-api/docs/item-creative-type) = `DISPLAY`.

# Supported asset types

| Type  | Extensions                     | MIME types                                                        |
| :---- | :----------------------------- | :---------------------------------------------------------------- |
| Image | jpg, jpeg, png, gif, bmp, webp | `image/jpeg`, `image/png`, `image/gif`, `image/bmp`, `image/webp` |
| Video | mp4, mpg, mpeg, flv, webm      | `video/mp4`, `video/mpg`, `video/flv`, `video/webm`               |

# Constraints

* `asset_url` must be a valid HTTPS URL.
* Maximum file size is 195 MB.
* Provide either `hosted_display_data.id` (existing asset) or `hosted_display_data.asset_url` (new upload) — not both.
* `display_ad_type` is resolved automatically from the file type. Do not set it manually.
* `mime_type`, `dimensions`, `ad_tag`, and `duration_in_seconds` are read-only fields populated by the system.

# Create a campaign item with an asset URL

Uses the [Mass create items](https://developers.taboola.com/backstage-api/reference/create-a-batch-of-campaign-items) endpoint:

```http Request path
POST api/1.0/{account_id}/campaigns/{campaign_id}/items/mass
```
```json Request object
{
  "collection": [
    {
      "url": "https://www.example.com/landing-page",
      "creative_type": "DISPLAY",
      "custom_data": {
        "creative_name": "My Display Ad"
      },
      "display_data": {
        "hosted_display_data": {
          "asset_url": "https://cdn.example.com/assets/banner.jpg"
        }
      }
    }
  ]
}
```
```json Response
{
  "results": [
    {
      "id": "12345",
      "url": "https://www.example.com/landing-page",
      "creative_type": "DISPLAY",
      "display_data": {
        "display_ad_type": "HOSTED_IMAGE",
        "ad_tag": "<taboola-tag type=\"image\" href=\"${CLICK_URL}{item_url}\" src=\"https://cdn.taboola.com/hosted-display-creatives/image/example.jpg\"></taboola-tag>",
        "dimensions": [
          {
            "height": 675,
            "width": 1200
          }
        ],
        "hosted_display_data": {
          "id": 67890,
          "duration_in_seconds": 0,
          "asset_url": "https://cdn.taboola.com/hosted-display-creatives/image/example.jpg",
          "mime_type": "image/jpeg",
          "social_hosted_display_data": {
            "source_external_id": null
          }
        }
      }
    }
  ]
}
```

> 📘 Response fields
>
> `display_ad_type` is resolved automatically (e.g. `HOSTED_IMAGE`, `HOSTED_VIDEO`). The response returns the Taboola CDN URL in `asset_url` and the resolved `mime_type`. `ad_tag` and `dimensions` are returned at the `display_data` level. For video assets, the response also includes `duration_in_seconds`.

# Update a campaign item with a new asset URL

Uses the [Update a campaign item](https://developers.taboola.com/backstage-api/reference/update-a-campaign-item) endpoint:

```http Request path
PUT api/1.0/{account_id}/campaigns/{campaign_id}/items/{item_id}
```
```json Request object
{
  "display_data": {
    "hosted_display_data": {
      "asset_url": "https://cdn.example.com/assets/new-banner.png"
    }
  }
}
```
```json Response (fragment)
{
  "id": "12345",
  "display_data": {
    "display_ad_type": "HOSTED_IMAGE",
    "hosted_display_data": {
      "asset_url": "https://cdn.taboola.com/hosted-display-creatives/image/new-banner.png",
      "mime_type": "image/png"
    }
  },
  ...
}
```

# Reuse an existing asset by ID

Reference an existing asset by `id` instead of `asset_url` to reuse it across campaign items. Uses the same [Mass create items](https://developers.taboola.com/backstage-api/reference/create-a-batch-of-campaign-items) endpoint.

```http Request path
POST api/1.0/{account_id}/campaigns/{campaign_id}/items/mass
```
```json Request object
{
  "collection": [
    {
      "url": "https://www.example.com/landing-page",
      "creative_type": "DISPLAY",
      "display_data": {
        "hosted_display_data": {
          "id": 67890
        }
      }
    }
  ]
}
```
```json Response (fragment)
{
  "results": [
    {
      "id": "12346",
      "url": "https://www.example.com/landing-page",
      "creative_type": "DISPLAY",
      "display_data": {
        "display_ad_type": "HOSTED_IMAGE",
        "hosted_display_data": {
          "id": 67890,
          "asset_url": "https://cdn.taboola.com/hosted-display-creatives/image/example.jpg"
        }
      },
      ...
    }
  ]
}
```

# Bulk create with mixed asset sources

A single bulk request can combine URL-based and ID-based assets. Uses the same [Mass create items](https://developers.taboola.com/backstage-api/reference/create-a-batch-of-campaign-items) endpoint.

```http Request path
POST api/1.0/{account_id}/campaigns/{campaign_id}/items/mass
```
```json Request object
{
  "collection": [
    {
      "url": "https://www.example.com/page1",
      "creative_type": "DISPLAY",
      "display_data": {
        "hosted_display_data": {
          "asset_url": "https://cdn.example.com/image.jpg"
        }
      }
    },
    {
      "url": "https://www.example.com/page2",
      "creative_type": "DISPLAY",
      "display_data": {
        "hosted_display_data": {
          "id": 67890
        }
      }
    }
  ]
}
```
```json Response (fragment)
{
  "results": [
    {
      "id": "12347",
      "url": "https://www.example.com/page1",
      "display_data": {
        "display_ad_type": "HOSTED_IMAGE",
        "hosted_display_data": {
          "asset_url": "https://cdn.taboola.com/hosted-display-creatives/image/uploaded.jpg"
        }
      },
      ...
    },
    {
      "id": "12348",
      "url": "https://www.example.com/page2",
      "display_data": {
        "display_ad_type": "HOSTED_IMAGE",
        "hosted_display_data": {
          "id": 67890,
          "asset_url": "https://cdn.taboola.com/hosted-display-creatives/image/example.jpg"
        }
      },
      ...
    }
  ]
}
```

# Error responses

| Scenario                              | HTTP code | Message                                                                                                                       |
| :------------------------------------ | :-------- | :---------------------------------------------------------------------------------------------------------------------------- |
| Both `id` and `asset_url` provided    | 400       | Cannot provide both `display_data.hosted_display_data.id` and `display_data.hosted_display_data.asset_url`. Provide only one. |
| Neither `id` nor `asset_url` provided | 400       | Missing field: `display_data.hosted_display_data.id` or `display_data.hosted_display_data.asset_url`.                         |
| Empty `asset_url`                     | 400       | `assetUrl` cannot be empty.                                                                                                   |
| Non-HTTPS URL                         | 400       | Invalid asset URL. Only valid `https` URLs are supported.                                                                     |
| Unsupported file type                 | 400       | Unsupported file type. Supported: images (jpg, png, gif, bmp, webp), videos (mp4, mpg, flv, webm), and HTML (zip).            |
| File too large (known size)           | 400       | Asset too large: {'{X}'}MB exceeds max 195MB.                                                                                 |
| File too large (after download)       | 400       | Asset too large: exceeds max 195MB.                                                                                           |
| URL unreachable                       | 400       | Failed to download asset from URL: (details).                                                                                 |
| Display not enabled for account       | 403       | Display items are not enabled for this account.                                                                               |