Video campaign creatives

📍
Video campaigns (aka brand video) require a special Taboola account.

Overview

Video campaign creatives are the actual video assets and creative elements used in video campaigns. This document covers the complete CRUD operations for managing video campaign creatives.

Managing video campaign creatives

Fetch operations

List video campaign creatives

Retrieve all creatives for a specific video campaign.

GET /backstage/api/1.0/{account_id}/video-campaigns/{campaign_id}/creative

GET /backstage/api/1.0/demo-advertiser/video-campaigns/12345/creative

{
  "results": [
    {
      "id": 67890,
      "advertiserId": "demo-advertiser",
      "campaignId": 12345,
      "vastUrl": "https://example.com/vast.xml",
      "name": "Product Demo Video",
      "isActive": true,
      "deleted": false,
      "landingPageUrl": "https://example.com/product-demo",
      "brandName": "Example Brand",
      "title": "Amazing Product Demo",
      "description": "Discover the features that make this product unique",
      "pixels": [
        {
          "url": "https://example.com/pixel.js",
          "type": "IMPRESSION"
        }
      ],
      "mediaSource": {
        "type": "URL",
        "url": "https://example.com/video.mp4"
      }
    },
    {
      "id": 78901,
      "advertiserId": "demo-advertiser",
      "campaignId": 12345,
      "vastUrl": "https://example.com/vast2.xml",
      "name": "Holiday Special Video",
      "isActive": true,
      "deleted": false,
      "landingPageUrl": "https://example.com/holiday-special",
      "brandName": "Example Brand",
      "title": "Holiday Special Offer",
      "description": "Limited time holiday promotion",
      "pixels": [
        {
          "url": "https://example.com/holiday-pixel.js",
          "type": "CONVERSION"
        }
      ],
      "mediaSource": {
        "type": "URL",
        "url": "https://example.com/holiday-video.mp4"
      }
    }
  ],
  "totalCount": 2
}

Get video campaign creative

Retrieve a specific video creative by its ID.

GET /backstage/api/1.0/{account_id}/video-campaigns/{campaign_id}/creative/{creative_id}

GET /backstage/api/1.0/demo-advertiser/video-campaigns/12345/creative/67890

{
  "id": 67890,
  "advertiserId": "demo-advertiser",
  "campaignId": 12345,
  "vastUrl": "https://example.com/vast.xml",
  "name": "Product Demo Video",
  "isActive": true,
  "deleted": false,
  "landingPageUrl": "https://example.com/product-demo",
  "brandName": "Example Brand",
  "title": "Amazing Product Demo",
  "description": "Discover the features that make this product unique",
  "pixels": [
    {
      "url": "https://example.com/pixel.js",
      "type": "IMPRESSION"
    }
  ],
  "mediaSource": {
    "type": "URL",
    "url": "https://example.com/video.mp4"
  }
}

Get video creative assets

Retrieve the media assets associated with a video creative.

GET /backstage/api/1.0/{account_id}/video-campaigns/{campaign_id}/creative/{creative_id}/assets

GET /backstage/api/1.0/demo-advertiser/video-campaigns/12345/creative/67890/assets

{
  "videoUrl": "https://example.com/video.mp4",
  "thumbnailUrl": "https://example.com/thumbnail.jpg",
  "previewUrl": "https://example.com/preview.gif",
  "vastUrl": "https://example.com/vast.xml",
  "duration": 30,
  "fileSize": 5242880,
  "format": "MP4",
  "resolution": "1920x1080"
}

Create operations

Create video campaign creative

Create a new video creative for a campaign.

POST /backstage/api/1.0/{account_id}/video-campaigns/{campaign_id}/creative

POST /backstage/api/1.0/demo-advertiser/video-campaigns/12345/creative

{
  "vastUrl": "https://example.com/new-vast.xml",
  "name": "New Product Launch Video",
  "landingPageUrl": "https://example.com/new-product",
  "brandName": "New Brand",
  "title": "Revolutionary New Product",
  "description": "Be the first to experience our latest innovation",
  "pixels": [
    {
      "url": "https://example.com/tracking-pixel.js",
      "type": "IMPRESSION"
    },
    {
      "url": "https://example.com/conversion-pixel.js",
      "type": "CONVERSION"
    }
  ],
  "mediaSource": {
    "type": "URL",
    "url": "https://example.com/new-video.mp4"
  }
}

[
  {
    "id": 78901,
    "advertiserId": "demo-advertiser",
    "campaignId": 12345,
    "vastUrl": "https://example.com/new-vast.xml",
    "name": "New Product Launch Video",
    "isActive": true,
    "deleted": false,
    "landingPageUrl": "https://example.com/new-product",
    "brandName": "New Brand",
    "title": "Revolutionary New Product",
    "description": "Be the first to experience our latest innovation",
    "pixels": [
      {
        "url": "https://example.com/tracking-pixel.js",
        "type": "IMPRESSION"
      },
      {
        "url": "https://example.com/conversion-pixel.js",
        "type": "CONVERSION"
      }
    ],
    "mediaSource": {
      "type": "URL",
      "url": "https://example.com/new-video.mp4"
    }
  }
]

Update operations

Update video campaign creative

Update an existing video creative. You can submit only the fields that need updating.

PUT /backstage/api/1.0/{account_id}/video-campaigns/{campaign_id}/creative/{creative_id}

PUT /backstage/api/1.0/demo-advertiser/video-campaigns/12345/creative/67890

{
  "name": "Updated Product Demo",
  "title": "Enhanced Product Features",
  "description": "Updated description with new features and benefits",
  "landingPageUrl": "https://example.com/updated-product-demo"
}

[
  {
    "id": 67890,
    "advertiserId": "demo-advertiser",
    "campaignId": 12345,
    "vastUrl": "https://example.com/vast.xml",
    "name": "Updated Product Demo",
    "isActive": true,
    "deleted": false,
    "landingPageUrl": "https://example.com/updated-product-demo",
    "brandName": "Example Brand",
    "title": "Enhanced Product Features",
    "description": "Updated description with new features and benefits",
    "pixels": [
      {
        "url": "https://example.com/pixel.js",
        "type": "IMPRESSION"
      }
    ],
    "mediaSource": {
      "type": "URL",
      "url": "https://example.com/video.mp4"
    }
  }
]

Sample error

{
  "error": "VALIDATION_ERROR",
  "message": "Name is required",
  "details": {
    "field": "name",
    "code": "REQUIRED_FIELD_MISSING"
  }
}

Delete operations

Delete video campaign creative

Delete a video creative from a campaign.

DELETE /backstage/api/1.0/{account_id}/video-campaigns/{campaign_id}/creative/{creative_id}

DELETE /backstage/api/1.0/demo-advertiser/video-campaigns/12345/creative/67890

[
  {
    "id": 67890,
    "advertiserId": "demo-advertiser",
    "campaignId": 12345,
    "vastUrl": "https://example.com/vast.xml",
    "name": "Product Demo Video",
    "isActive": false,
    "deleted": true,
    "landingPageUrl": "https://example.com/product-demo",
    "brandName": "Example Brand",
    "title": "Amazing Product Demo",
    "description": "Discover the features that make this product unique",
    "pixels": [
      {
        "url": "https://example.com/pixel.js",
        "type": "IMPRESSION"
      }
    ],
    "mediaSource": {
      "type": "URL",
      "url": "https://example.com/video.mp4"
    }
  }
]

Video campaign creative fields

Core fields

Field	Type	Required	Description
`id`	Long	No	Unique identifier for the video creative (auto-generated)
`advertiserId`	String	No	Advertiser ID (auto-populated)
`campaignId`	Long	No	ID of the campaign this creative belongs to
`vastUrl`	String	No	VAST XML URL for the video creative
`name`	String	Yes	Name of the video creative
`isActive`	Boolean	No	Whether the creative is active
`deleted`	Boolean	No	Whether the creative has been deleted

Content fields

Field	Type	Required	Description
`landingPageUrl`	String	No	Landing page URL for the video creative
`brandName`	String	No	Brand name associated with the creative
`title`	String	No	Title text displayed with the video
`description`	String	No	Description text displayed with the video

Tracking and media fields

Field	Type	Required	Description
`pixels`	Array	No	Array of tracking pixels
`mediaSource`	Object	No	Media source configuration

Pixel object fields

Field	Type	Required	Description
`url`	String	Yes	Pixel URL
`type`	String	Yes	Pixel type: `IMPRESSION`, `CONVERSION`, `CLICK`

Media source object fields

Field	Type	Required	Description
`type`	String	Yes	Media source type: `URL`, `UPLOAD`
`url`	String	No	Media URL (required if type is `URL`)

Status values

Creative status

Value	Description
`true`	Creative is active
`false`	Creative is inactive

Pixel types

Value	Description
`IMPRESSION`	Impression tracking pixel
`CONVERSION`	Conversion tracking pixel
`CLICK`	Click tracking pixel

Media source types

Value	Description
`URL`	Media hosted at external URL
`UPLOAD`	Media uploaded to Taboola

Related docs

Video campaigns - manage video campaigns