Overview & flow

πŸ“

IMPORTANT

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 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 endpoints

The following endpoints support both static ads and motion ads:

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

    Create multiple static ads and motion ads.

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

    Returns both static ads 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}

    Delete either item type.

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

    Delete multiple static ads and motion ads.

Also

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

    Pause/resume multiple static ads and motion ads.

Motion-only endpoints

The following endpoint supports motion ads only:

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

    Update a single motion ad.

Static-only endpoints

The following endpoints support static ads only:

Motion ad fields (for GET operations)

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

A complete flow

  1. Create 1 or more motion ads - see: Bulk create items:
PUT /backstage/api/1.0/{account_id}/items/bulk
{
"campaign_ids": ["campaign_id_1", "campaign_id_2"],
"items": [
{
"title": "Your video ad title",
"url": "https://example.com",
"creative_type": "PERFORMANCE_VIDEO",
"performance_video_data": {
"video_url": "https://example.com/video.mp4",
"fallback_url": "https://example.com/fallback.jpg"
}
}
]
}
  1. Retrieve a single motion ad - see: Get a campaign item
GET /backstage/api/1.0/{account_id}/campaigns/{campaign_id}/items/

To retrieve multiple ads (both static and motion), see: Get all campaign items

  1. Update a single motion ad - see: Update a Motion Ad
PUT /backstage/api/1.0/{account_id}/campaigns/{campaign_id}/performance-video/items/{item_id}

To pause/resume multiple motion ads, see: Bulk update items

  1. Delete a single motion ad - see: Delete a campaign item
DELETE /backstage/api/1.0/{account_id}/campaigns/{campaign_id}/items/{item_id}

To delete multiple motion ads and static ads, see: Bulk delete items

πŸ“˜

Guidelines for motion ads

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