API ReferenceCommunity DiscussionAnnouncements
API ReferenceAnnouncementsCommunity Discussion
API ReferenceCommunity DiscussionAnnouncementsLog In
API Reference
Start typing to search…

Video campaign creatives


📍

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

Overview

The video campaigns creative API allows you to manage creative assets and metadata for existing video campaigns.

📘

GET operations

This page focuses (mainly) on the GET operations for creatives.

Media Types

Video creatives support 2 media types:

Type

Description

VAST

Video Ad Serving Template
Standard format for video advertising

GENERATED_VIDEO

AI-Generated Video Content
Video content created using Taboola's video generation tools

Authentication

All API requests require authentication using OAuth 2.0 client credentials. See Client Credentials Flow for detailed authentication instructions.

Endpoints and examples

List video campaign creatives

Retrieve all video creatives for a specific campaign.

🚧

Endpoint path

Creative endpoints use the general video-campaigns path, not the video-campaigns/managed path.

GET /backstage/api/1.0/{account_id}/video-campaigns/{campaign_id}/creative
Authorization: Bearer {access_token}
Content-Type: application/json
{
  "results": [
    {
      "id": 98765432,
      "advertiser_id": "987654",
      "campaign_id": 12345678,
      "vast_url": "https://vast.taboola.com/vast/v1/creative/98765432",
      "name": "Summer Video Creative 2024",
      "is_active": true,
      "deleted": false,
      "landing_page_url": "https://example.com/summer-sale",
      "brand_name": "ACME Products",
      "title": "Summer Sale - 50% Off Everything",
      "description": "Don't miss our biggest summer sale with up to 50% off all products",
      "pixels": [
        {
          "pixel_type": "IMPRESSION",
          "urls": [
            "https://tracking.example.com/impression?id=12345"
          ]
        }
      ],
      "media_source": {
        "media_type": "VAST",
        "vast_url": "https://vast.taboola.com/vast/v1/creative/98765432",
        "hash_ids": [1001, 1002, 1003]
      }
    },
    {
      "id": 98765433,
      "advertiser_id": "987654", 
      "campaign_id": 12345678,
      "vast_url": "https://vast.taboola.com/vast/v1/creative/98765433",
      "name": "Holiday Video Creative 2024",
      "is_active": false,
      "deleted": false,
      "landing_page_url": "https://example.com/holiday-deals",
      "brand_name": "ACME Products",
      "title": "Holiday Specials - Limited Time",
      "description": "Exclusive holiday deals available for a limited time only",
      "pixels": [
        {
          "pixel_type": "IMPRESSION",
          "urls": [
            "https://tracking.example.com/impression?id=12346"
          ]
        }
      ],
      "media_source": {
        "media_type": "GENERATED_VIDEO",
        "vast_url": "https://vast.taboola.com/vast/v1/creative/98765433",
        "hash_ids": [2001, 2002]
      }
    }
  ]
}

Get a video campaign creative

Retrieve detailed information for a specific video creative.

GET /backstage/api/1.0/{account_id}/video-campaigns/{campaign_id}/creative/{creative_id}
Authorization: Bearer {access_token}
Content-Type: application/json
{
  "id": 98765432,
  "advertiser_id": "987654",
  "campaign_id": 12345678,
  "vast_url": "https://vast.taboola.com/vast/v1/creative/98765432",
  "name": "Summer Video Creative 2024",
  "is_active": true,
  "deleted": false,
  "landing_page_url": "https://example.com/summer-sale",
  "brand_name": "ACME Products",
  "title": "Summer Sale - 50% Off Everything",
  "description": "Don't miss our biggest summer sale with up to 50% off all products",
  "pixels": [
    {
      "pixel_type": "IMPRESSION",
      "urls": [
        "https://tracking.example.com/impression?id=12345"
      ]
    },
    {
      "pixel_type": "COMPLETE",
      "urls": [
        "https://tracking.example.com/complete?id=12345"
      ]
    }
  ],
  "media_source": {
    "media_type": "VAST",
    "vast_url": "https://vast.taboola.com/vast/v1/creative/98765432",
    "hash_ids": [1001, 1002, 1003]
  }
}

Get video creative assets

Retrieve video assets and upload information for a specific video creative.

GET /backstage/api/1.0/{account_id}/video-campaigns/{campaign_id}/creative/{creative_id}/assets
Authorization: Bearer {access_token}
Content-Type: application/json
{
  "video_url": "https://cdn.taboola.com/video/12345678/98765432/video.mp4",
  "logo": {
    "logo_url": "https://cdn.taboola.com/logos/acme-logo.png",
    "position": "top-right"
  },
  "subtitles": {
    "subtitle_url": "https://cdn.taboola.com/subtitles/12345678/98765432/subtitles.vtt",
    "language": "en"
  },
  "video_upload_items": [
    {
      "upload_id": "upload_12345",
      "file_name": "summer_video_creative.mp4",
      "file_size": 25600000,
      "duration": 30,
      "resolution": "1920x1080",
      "status": "PROCESSED",
      "uploaded_at": "2024-06-01T10:30:00Z"
    }
  ]
}

Pause a video creative

Temporarily pause a video creative to stop it from serving.

PUT /backstage/api/1.0/{account_id}/video-campaigns/{campaign_id}/creative/{creative_id}
Authorization: Bearer {access_token}
Content-Type: application/json
{
  "is_active": false
}
{
  "id": 98765432,
  "advertiser_id": "987654",
  "campaign_id": 12345678,
  "vast_url": "https://vast.taboola.com/vast/v1/creative/98765432",
  "name": "Summer Video Creative 2024",
  "is_active": false,
  "deleted": false,
  "landing_page_url": "https://example.com/summer-sale",
  "brand_name": "ACME Products",
  "title": "Summer Sale - 50% Off Everything",
  "description": "Don't miss our biggest summer sale with up to 50% off all products",
  "pixels": [
    {
      "pixel_type": "IMPRESSION",
      "urls": [
        "https://tracking.example.com/impression?id=12345"
      ]
    }
  ],
  "media_source": {
    "media_type": "VAST",
    "vast_url": "https://vast.taboola.com/vast/v1/creative/98765432",
    "hash_ids": [1001, 1002, 1003]
  }
}

Resume a video creative

Resume a paused video creative to resume serving.

PUT /backstage/api/1.0/{account_id}/video-campaigns/{campaign_id}/creative/{creative_id}
Authorization: Bearer {access_token}
Content-Type: application/json
{
  "is_active": true
}
{
  "id": 98765432,
  "advertiser_id": "987654",
  "campaign_id": 12345678,
  "vast_url": "https://vast.taboola.com/vast/v1/creative/98765432",
  "name": "Summer Video Creative 2024",
  "is_active": true,
  "deleted": false,
  "landing_page_url": "https://example.com/summer-sale",
  "brand_name": "ACME Products",
  "title": "Summer Sale - 50% Off Everything",
  "description": "Don't miss our biggest summer sale with up to 50% off all products",
  "pixels": [
    {
      "pixel_type": "IMPRESSION",
      "urls": [
        "https://tracking.example.com/impression?id=12345"
      ]
    }
  ],
  "media_source": {
    "media_type": "VAST",
    "vast_url": "https://vast.taboola.com/vast/v1/creative/98765432",
    "hash_ids": [1001, 1002, 1003]
  }
}

Field Definitions

📘

Modifier Column

  • Required - field must be included when creating a new resource
  • Read-only - should never be sent to the server. Appears only when fetching a resource.
  • Final - set once when creating the resource. Thereafter, is read-only.

Creative fields

FieldTypeModifiers and DefaultsDescription
namestringRequiredCreative name
vast_urlstringVAST tag URL for video creative
landing_page_urlstringDestination URL when creative is clicked
brand_namestringBrand name displayed in creative
titlestringCreative title text
descriptionstringCreative description text
is_activebooleanDefault: trueWhether creative is active
pixelsarrayTracking pixels configuration
media_sourceobjectMedia source configuration
idnumberRead-onlyCreative ID (auto-generated)
advertiser_idstringRead-onlyAdvertiser ID (auto-assigned)
campaign_idnumberRead-onlyCampaign ID (auto-assigned)
deletedbooleanRead-onlyWhether creative has been deleted

Pixel fields

FieldTypeDescription
pixel_typestringType of tracking pixel (see Pixel Types)
urlsarrayList of tracking URLs for this pixel type

Pixel types

TypeDescription
IMPRESSIONFires when video is displayed
STARTFires when video playback starts
FIRST_QUARTILEFires at 25% video completion
MID_POINTFires at 50% video completion
THIRD_QUARTILEFires at 75% video completion
COMPLETEFires when video playback completes
CLICK_TRACKINGFires when creative is clicked

Media source fields

FieldTypeDescription
media_typestringType of media source (VAST, GENERATED_VIDEO)
vast_urlstringVAST tag URL
hash_idsarrayInternal hash identifiers for media assets

Media types

TypeDescription
VASTVideo Ad Serving Template format
GENERATED_VIDEOAI-generated video content

Assets fields

FieldTypeDescription
video_urlstringDirect URL to video file
logoobjectLogo configuration and URL
subtitlesobjectSubtitles configuration and URL
video_upload_itemsarrayUpload metadata and processing status

Error Responses

400 Bad Request

{
  "error": "Bad Request",
  "message": "Invalid creative parameters provided",
  "details": [
    {
      "field": "creative_id",
      "message": "Creative ID must be a valid number"
    }
  ]
}

401 Unauthorized

{
  "error": "Unauthorized",
  "message": "Invalid or expired access token"
}

404 Not Found

{
  "error": "Not Found",
  "message": "Creative not found",
  "creative_id": "98765432"
}

422 Unprocessable Entity

{
  "error": "Unprocessable Entity",
  "message": "Creative belongs to a different campaign",
  "details": [
    {
      "field": "campaign_id",
      "message": "Creative does not belong to the specified campaign"
    }
  ]
}