API ReferenceCommunity DiscussionAnnouncementsSubscribe
API ReferenceAnnouncementsCommunity Discussion
API ReferenceCommunity DiscussionAnnouncementsSubscribeLog In
API Reference

Create a Performance Video Item (Motion Ad)

post https://backstage.taboola.com/backstage/api/1.0//campaigns//performance-video/items/

Create a performance video item (motion ad).

Creating a Performance Video Item (Motion Ad)

When creating a motion ad, you must include 4 required fields:*

  1. url
  2. title
  3. video_url
  4. fallback_url

*Alternatively, you can combine JSON content with multipart/form-data (file uploads). cURL examples are provided below.

📘

Guidelines for Motion Ads

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

JSON example

Example 1 - JSON request with URL Params: 

POST /backstage/api/1.0/taboola-demo/campaigns/1234/performance-video/items/

{
   "url": "http://news.example.com/demo_article.html",
   "title": "Demo Article",
   "video_url": "https://cdn.example.com/demo_video.mp4",
   "fallback_url": "https://cdn.example.com/demo_image.png"
}

{
   "id": "123",
   "campaign_id": "1234",
   "url": "http://news.example.com/demo_article.html",
   "title": "Demo Article",
   "approval_state": "PENDING",
   "is_active": true,
   "status": "PENDING_APPROVAL",
   "policy_review": {
      "reject_reason": null
   },
   "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",
   "video_url": "http://c3.taboola.com/libtrc/static/video/t_PERFORMANCE_VIDEO_DEFAULT/v1602508826/ax3qanrabayqre4lw3gg.mp4!-#@800x448"
}

📘

The Taboola solution generates 3 new assets:

  1. An optimized video file, in MP4 format (video_url, in the response).
  2. A GIF, based on the above MP4 (gif_url, in the response).
  3. An optimized fallback image (fallback_url, in the response).

These are saved in the Taboola CDN.

🚧

Creation of the above assets takes time. A typical response may take 15 seconds or longer (depending on the video file size, server load, network latency, etc.)

File upload examples

Example 1 - upload video file (using cURL):

curl --location --request POST 'https://backstage.taboola.com/backstage/api/1.0/demo-advertiser/campaigns/1234/performance-video/items/' \
--header 'Authorization: Bearer CZ0OAAAAAAAAEdt7AgAAAAAAGAEgAClLv6MHdQEAADooNjQ0NWZjNGQ2ZWRlNWJkNWFjZDQ2MDM5NjRiZWRhMmRjZjZhOThjMEAC::644420::78997c' \
--form 'new_item={
   "url": "http://news.example.com/demo_article.html",
   "title": "Demo Article",
   "fallback_url": "https://cdn.example.com/demo_image.png"
};type=application/json' \
--form 'video_file=@/Users/john.doe/Downloads/demo_video.mp4'

{
   "id": "123",
   "campaign_id": "1234",
   "url": "http://news.example.com/demo_article.html",
   "title": "Demo Article",
   "approval_state": "PENDING",
   "is_active": true,
   "status": "PENDING_APPROVAL",
   "policy_review": {
      "reject_reason": null
   },
   "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",
   "video_url": "http://c3.taboola.com/libtrc/static/video/t_PERFORMANCE_VIDEO_DEFAULT/v1602508826/ax3qanrabayqre4lw3gg.mp4!-#@800x448"
}

Example 2 - upload 2 files (using cURL):

curl --location --request POST 'https://backstage.taboola.com/backstage/api/1.0/demo-advertiser/campaigns/1234/performance-video/items/' \
--header 'Authorization: Bearer CZ0OAAAAAAAAEdt7AgAAAAAAGAEgAClLv6MHdQEAADooNjQ0NWZjNGQ2ZWRlNWJkNWFjZDQ2MDM5NjRiZWRhMmRjZjZhOThjMEAC::644420::78997c' \
--form 'new_item={
   "url": "http://news.example.com/demo_article.html",
   "title": "Demo Article"
};type=application/json' \
--form 'video_file=@/Users/john.doe/Downloads/demo_video.mp4'
--form 'fallback_file=@/Users/john.doe/Downloads/demo_image.png'

{
   "id": "123",
   "campaign_id": "1234",
   "url": "http://news.example.com/demo_article.html",
   "title": "Demo Article",
   "approval_state": "PENDING",
   "is_active": true,
   "status": "PENDING_APPROVAL",
   "policy_review": {
      "reject_reason": null
   },
   "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",
   "video_url": "http://c3.taboola.com/libtrc/static/video/t_PERFORMANCE_VIDEO_DEFAULT/v1602508826/ax3qanrabayqre4lw3gg.mp4!-#@800x448"
}

🚧

Uploading files

  1. Upload files as multipart/form-data.
  2. Pass all other params within the new_item JSON object param.
  3. Specify a content type of application\json for the new_item param only. (In the above example, this is the ;type=application/json snippet just after new_item JSON object.)

🚧

If the request is missing a param - or the content type is incorrectly specified - the server may return Error 500.

Language
Credentials
OAuth2