Bulk create items across campaigns

Overview

Bulk create items across multiple campaigns. The same items will be created for each campaign. You can also use a network account to bulk create new items across the network.

๐Ÿšง

Unified endpoint

This endpoint supports both regular items and motion ads. You can also mix both ad types in the same request.

Static items

Example - create regular items across multiple campaigns:

PUT /backstage/api/1.0/demo-advertiser/items/bulk
{
   "campaign_ids": [
      33,
      270,
      163
   ],
   "items": [
      {
         "url": "http://www.demo-advertiser.com/wedding-rings",
         "thumbnail_url": "http://cdn.demo-advertiser.com/thumbnails/thmbnail-1.jpg",
         "title": "The perfect wedding ring"
      },
      {
         "url": "http://www.demo-advertiser.com/proposal-rings",
         "thumbnail_url": "http://cdn.demo-advertiser.com/thumbnails/thumbnail-2.jpg",
         "title": "Amazing proposal rings"
      },
      {
         "url": "http://www.demo-advertiser.com/medalions",
         "thumbnail_url": "http://cdn.demo-advertiser.com/thumbnails/thumbnail-3.jpg",
         "title": "Beautiful medallions"
      }
   ]
}
{
    "results": [{
            "id": "444",
            "campaign_id": "33",
            "type": "ITEM",
            "url": "http://www.demo-advertiser.com/wedding-rings",
            "thumbnail_url": "http://cdn.demo-advertiser.com/thumbnails/thmbnail-1.jpg",
            "title": "The perfect wedding ring",
            "description": null,
            "approval_state": "PENDING",
            "is_active": true,
            "status": "PENDING_APPROVAL",
            "policy_review": {
                "reject_reason": null,
                "status_reason": null
            },
            "cta": null,
            "creative_focus": {
                "type": "AUTOMATIC",
                "coordinates": null
            }
        },
        {
            "id": "445",
            "campaign_id": "33",
            "type": "ITEM",
            "url": "http://www.demo-advertiser.com/proposal-rings",
            "thumbnail_url": "http://cdn.demo-advertiser.com/thumbnails/thumbnail-2.jpg",
            "title": "Amazing proposal rings",
            "description": null,
            "approval_state": "PENDING",
            "is_active": true,
            "status": "PENDING_APPROVAL",
            "policy_review": {
                "reject_reason": null,
                "status_reason": null
            },
            "cta": null,
            "creative_focus": {
                "type": "AUTOMATIC",
                "coordinates": null
            }
        },
        {
            "id": "446",
            "campaign_id": "33",
            "type": "ITEM",
            "url": "http://www.demo-advertiser.com/medalions",
            "thumbnail_url": "http://cdn.demo-advertiser.com/thumbnails/thumbnail-3.jpg",
            "title": "Beautiful medallions",
            "description": null,
            "approval_state": "PENDING",
            "is_active": true,
            "status": "PENDING_APPROVAL",
            "policy_review": {
                "reject_reason": null,
                "status_reason": null
            },
            "cta": null,
            "creative_focus": {
                "type": "AUTOMATIC",
                "coordinates": null
            }
        }
    ],
    "metadata": {
        ...
    }
}
๐Ÿ“˜

Required fields (for static items)

  1. url
  2. thumbnail_url
  3. title
๐Ÿ“˜

Optional fields (for static items)

  1. description
  2. creative_focus

    This field has been deprecated.


The cta field is not supported. If passed, the endpoint will return 400.

๐Ÿšง

URL is not crawled

The endpoint saves the above values without crawling the URL. Make sure that the values passed are acceptable to Taboola.

Motion ads

Example - Create motion ads across multiple campaigns:

PUT /backstage/api/1.0/demo-advertiser/items/bulk
{
   "campaign_ids": [
      33,
      270
   ],
   "items": [
      {
         "title": "Amazing video ad",
         "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"
         }
      }
   ]
}
{
    "results": [{
            "id": "555",
            "campaign_id": "33",
            "type": "ITEM",
            "url": "https://example.com",
            "title": "Amazing video ad",
            "description": null,
            "approval_state": "PENDING",
            "is_active": true,
            "status": "PENDING_APPROVAL",
            "policy_review": {
                "reject_reason": null,
                "status_reason": null
            },
            "cta": null,
            "creative_focus": {
                "type": "AUTOMATIC",
                "coordinates": null
            },
            "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"
            }
        },
        {
            "id": "556",
            "campaign_id": "270",
            "type": "ITEM",
            "url": "https://example.com",
            "title": "Amazing video ad",
            "description": null,
            "approval_state": "PENDING",
            "is_active": true,
            "status": "PENDING_APPROVAL",
            "policy_review": {
                "reject_reason": null,
                "status_reason": null
            },
            "cta": null,
            "creative_focus": {
                "type": "AUTOMATIC",
                "coordinates": null
            },
            "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"
            }
        }
    ],
    "metadata": {
        ...
    }
}
๐Ÿ“˜

Required fields (for motion ads)

  1. title - The ad title
  2. url - The landing page URL
  3. creative_type - Must be "PERFORMANCE_VIDEO"
  4. performance_video_data - Object containing:
    • video_url - URL to the video file (MP4 format)
    • fallback_url - URL to the fallback image (JPG/PNG format)
๐Ÿ“˜

Optional fields (for motion ads)

  1. description - Ad description
๐Ÿšง

Video requirements

  • Video files must be in MP4 format
  • Fallback images must be in JPG or PNG format
  • Both video and fallback image URLs must be publicly accessible

General guidelines

๐Ÿ“˜

Request Object

  1. campaign_ids: a collection of Campaign IDs (each ID passed as a Number).
  2. items: a collection of items to create. (These items will be created for each of the above campaigns.)
๐Ÿšง

Guidelines

  1. To bulk create items, use the PUT verb.
  2. Limit each request to a maximum of 200 items.
  3. Bulk create is always atomic: if the operation fails for 1 item, then no items will be created.
  4. Bulk create supports both regular items and motion ads. You can mix both ad types in the same request.
  5. The new Items are created with a status of PENDING. Once approved, their status is updated to APPROVED.
๐Ÿšง

The network account

You can use a network account to create items across the network: PUT backstage/api/1.0/{network-account}/items/bulk

For more information about the network account see: Network Accounts.

๐Ÿ“˜

See also

Language
Credentials
OAuth2