Create and update display ad campaign items 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 = 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 endpoint:

POST api/1.0/{account_id}/campaigns/{campaign_id}/items/mass

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

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

PUT api/1.0/{account_id}/campaigns/{campaign_id}/items/{item_id}

{
  "display_data": {
    "hosted_display_data": {
      "asset_url": "https://cdn.example.com/assets/new-banner.png"
    }
  }
}

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

POST api/1.0/{account_id}/campaigns/{campaign_id}/items/mass

{
  "collection": [
    {
      "url": "https://www.example.com/landing-page",
      "creative_type": "DISPLAY",
      "display_data": {
        "hosted_display_data": {
          "id": 67890
        }
      }
    }
  ]
}

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

POST api/1.0/{account_id}/campaigns/{campaign_id}/items/mass

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

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