📍

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 (for 1 or more campaigns).

• 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 (for 1 or more campaigns).

Also

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

  Pause/resume multiple static ads and motion ads (for 1 or more campaigns).

• Mass create items for a given campaign: POST /backstage/api/1.0/{account_id}/campaigns/{campaign_id}/items/mass

  Create multiple static ads and motion ads (for a single campaign).

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:

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

  Create a single static ad.

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

  Update a single static ad.

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

2. Retrieve a single motion ad - see: Get a campaign item

GET /backstage/api/1.0/{account_id}/campaigns/{campaign_id}/items/{item_id}

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

3. 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

4. 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.