📍

UPDATE

A number of API endpoints now support both static ads and motion ads. Accordingly, the corresponding motion-specific endpoints have been deprecated. Please read the guidelines below carefully.

Introduction

In addition to static ads (aka items), Backstage API also supports motion ads (aka performance video items).

A number of API endpoints now support both static ads and motion ads. You can use these endpoints for both ad types, and the system will automatically handle each type appropriately.

📘

General guidelines

1. You can include static ads and motion ads in a single campaign.
2. To create 1 or more motion ads, use items/bulk .

   You can mix static ads and motion ads in the same bulk create request.

3. Most items endpoints now return both static ads and motion ads with their respective fields.
4. The Top Campaign Content Report returns stats for both static ads and motion ads.

Unified support

The following endpoints support both static ads and motion ads:

Bulk operations

• Bulk Create Items : PUT /backstage/api/1.0/{account_id}/items/bulk

  Create multiple static ads and/or motion ads.

• Bulk Delete Items : DELETE /backstage/api/1.0/{account_id}/items/bulk

  Delete multiple static ads and/or motion ads.

Standard operations

• Get All Campaign Items: GET /backstage/api/1.0/{account_id}/campaigns/{campaign_id}/items/

  Returns both static and motion ads with their respective fields.

• Get a Campaign Item : GET /backstage/api/1.0/{account_id}/campaigns/{campaign_id}/items/{item_id}

  Returns the requested item with its respective fields.

• Delete a Campaign Item: DELETE /backstage/api/1.0/{account_id}/campaigns/{campaign_id}/items/{item_id}

  Deletes either item type.

Motion ad fields

When a given item in the response is a motion ad, the following additional fields are present:

{
   "creative_type": "PERFORMANCE_VIDEO",
   "performance_video_data": {
      "video_url": "http://c3.taboola.com/libtrc/static/video/t_PERFORMANCE_VIDEO_DEFAULT/v1602508826/ax3qanrabayqre4lw3gg.mp4!-#@800x448",
      "fallback_url": "http://cdn.taboola.com/libtrc/static/thumbnails/1cc96d86c676d195c1d3cb426ddc9745.png",
      "gif_url": "http://c3.taboola.com/libtrc/static/gif/t_PERFORMANCE_VIDEO_DEFAULT/e_loop/so_0/f_gif/v1602508826/ax3qanrabayqre4lw3gg.gif"
   }
}

Static-specific endpoints

The following endpoints support static ads only:

• Create a campaign item: POST /backstage/api/1.0/{account_id}/campaigns/{campaign_id}/items/

  Creates static ads only (URL crawling).

• Update a campaign item: PUT /backstage/api/1.0/{account_id}/campaigns/{campaign_id}/items/{item_id}

  Updates static ads only.

• Bulk update items across campaigns: POST /backstage/api/1.0/{account_id}/items/bulk

  Update multiple static ads.

Motion-specific endpoints

The following endpoint supports motion ads only:

• Update a video item: PUT /backstage/api/1.0/{account_id}/campaigns/{campaign_id}/performance-video/items/{item_id}

  Updates motion ads only.

📍

DEPRECATION NOTICE

The following motion-specific endpoints have been deprecated:

• Create a video item:
  POST /backstage/api/1.0/{account_id}/campaigns/{campaign_id}/performance-video/items/
• Get all video items:
  GET /backstage/api/1.0/{account_id}/campaigns/{campaign_id}/performance-video/items/
• Get a video item:
  GET /backstage/api/1.0/{account_id}/campaigns/{campaign_id}/performance-video/items/{item_id}
• Delete a video item:
  DELETE /backstage/api/1.0/{account_id}/campaigns/{campaign_id}/performance-video/items/{item_id}

Please use the unified endpoints instead: Bulk Create Items, Get All Campaign Items, Get a Campaign Item, and Delete a Campaign Item.

Creating motion ads

When creating a motion ad, you must provide 2 URLs:

1. A URL for the video.
2. A URL for the static fallback image.

🚧

Providing assets via a file upload has been deprecated. Instead, submit a URL for each asset.

In return, the Taboola solution generates 3 new assets:

1. An optimized video file, in MP4 format.
2. A GIF, based on the above MP4.
3. An optimized fallback image.

📘

Asset URLs

• The above 3 assets are saved in the Taboola CDN.
• The response object contains URL paths to the newly created files.

Serving motion ads

When serving your motion ad, Taboola will serve the appropriate asset, based on the publisher account settings:

Recommended workflow

For the best developer experience, we recommend:

1. For creating items: Use the unified bulk create endpoint - it supports both types and allows mixing them in the same request
2. For updating items: Use the unified bulk update endpoint for multiple items, or the specific motion ad endpoint for single items
3. For fetching items: Use the unified endpoints - they return all item types with their complete field sets
4. For deleting items: Use the unified delete endpoint

📘

Guidelines for motion ads

For guidelines and best practices, refer to the Help Center, or sync with your Taboola Account Manager.