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

Update a Performance Video Item (Motion Ad)

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

Update the specified performance video item (motion ad).

📘

Update operation

To submit JSON data only without uploading files:

  • Submit a PUT request with a Content_Type of application/json.
  • The request body must contain a JSON object with the fields to update.

    Fields that are omitted or null, will remain unchanged.

To upload 1 or more files:

  • Using the POST method, upload the file(s) as multipart/form-data.
  • Include an update_item field with a JSON object as its value.
  • The JSON object can contain any fields to update.
    • Fields that are omitted or null, will remain unchanged.
    • If there are no fields to update, submit an empty object.
    • Failure to include the update_item field will result in Error 500.
  • Specify a content type of application\json for the update_item field only.

📘

Guidelines for Motion Ads

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

Examples - Submit JSON data only

Example 1 - update the title and video_url

PUT /backstage/api/1.0/demo-advertiser/campaigns/1234/performance-video/items/123

{
   "title": "New Title",
   "video_url": "https://cdn.example.com/new_video.mp4"
}

{
   "id": "123",
   "campaign_id": "1234",
   "url": "http://news.example.com/demo-article-1",
   "title": "New Title",
   "approval_state": "APPROVED",
   "is_active": true,
   "status": "RUNNING",
   "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/v1601995708/h1s7azgctpfhzajgcs2y.mp4!-#@800x448"
}

A comparison of the performance video item (motion ad) 'before' and 'after' the update:

{
   "id": "123",
   "campaign_id": "1234",
   "url": "http://news.example.com/demo-article-1",
   "title": "Demo Article 1",
   "approval_state": "APPROVED",
   "is_active": true,
   "status": "RUNNING",
   "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"
}

{
   "id": "123",
   "campaign_id": "1234",
   "url": "http://news.example.com/demo-article-1",
   "title": "New Title",
   "approval_state": "APPROVED",
   "is_active": true,
   "status": "RUNNING",
   "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/v1604505100/mtgarmu8q18db5qdbnuq.gif",
   "video_url": "http://c3.taboola.com/libtrc/static/video/t_PERFORMANCE_VIDEO_DEFAULT/v1604505100/mtgarmu8q18db5qdbnuq.mp4!-#@800x448"
}

📘

Note that aside fom title, both video_url and gif_url have changed.

Example 2 - pause a performance video item (motion ad)

To pause (or unpause) a performance video Item, update it and set is_active to false (or true).

For an illustration of this flow (using an image-based item), see: Pausing/unpausing Campaign Items.

🚧

A paused video performance item (motion ad) is not served by Taboola.

Examples - Upload files

Example 1 - upload a new video file and rename the title (using cURL):

curl --location --request POST 'https://backstage.taboola.com/backstage/api/1.0/demo-advertiser/campaigns/1234/performance-video/items/123' \
--header 'Authorization: Bearer CZ0OAAAAAAAAEdt7AgAAAAAAGAEgAClLv6MHdQEAADooNjQ0NWZjNGQ2ZWRlNWJkNWFjZDQ2MDM5NjRiZWRhMmRjZjZhOThjMEAC::644420::78997c' \
--form 'update_item={
   "title": "New Title",
};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": "APPROVED",
   "is_active": true,
   "status": "RUNNING",
   "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 new files and rename the title (using cURL):

curl --location --request POST 'https://backstage.taboola.com/backstage/api/1.0/demo-advertiser/campaigns/1234/performance-video/items/123' \
--header 'Authorization: Bearer CZ0OAAAAAAAAEdt7AgAAAAAAGAEgAClLv6MHdQEAADooNjQ0NWZjNGQ2ZWRlNWJkNWFjZDQ2MDM5NjRiZWRhMmRjZjZhOThjMEAC::644420::78997c' \
--form 'update_item={
   "title": "New Title"
};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": "APPROVED",
   "is_active": true,
   "status": "RUNNING",
   "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 3 - file upload only (using cURL):

curl --location --request POST 'https://backstage.taboola.com/backstage/api/1.0/demo-advertiser/campaigns/1234/performance-video/items/123' \
--header 'Authorization: Bearer CZ0OAAAAAAAAEdt7AgAAAAAAGAEgAClLv6MHdQEAADooNjQ0NWZjNGQ2ZWRlNWJkNWFjZDQ2MDM5NjRiZWRhMmRjZjZhOThjMEAC::644420::78997c' \
--form 'update_item={};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": "APPROVED",
   "is_active": true,
   "status": "RUNNING",
   "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 update_item JSON object param.
  3. Specify a content type of application\json for the update_item param only. (In the above example, this is the ;type=application/json snippet just after new_item JSON object.)
  4. The update_item field is required (even if no data will be submitted).

🚧

Troubleshooting (Error 500 and Error 415)

Some common causes for errors include:

  • Using the wrong verb - e.g. POST instead of PUT (or vice versa).
  • An incorrect content_type.
  • Leaving out the update_item field (or mis-spelling it).
Language
Credentials
OAuth2