Mass create items for a given campaign

Overview

Mass create items for a given campaign. All items will be created for the specified campaign in a single API request.

🚧

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 for a campaign:

POST /backstage/api/1.0/demo-advertiser/campaigns/1234/items/mass
{
    "collection": [{
            "url": "https://www.demo-advertiser.com/wedding-rings",
            "thumbnail_url": "https://cdn.demo-advertiser.com/thumbnails/thumbnail-1.jpg",
            "title": "The perfect wedding ring"
        },
        {
            "url": "https://www.demo-advertiser.com/proposal-rings",
            "thumbnail_url": "https://cdn.demo-advertiser.com/thumbnails/thumbnail-2.jpg",
            "title": "Amazing proposal rings"
        },
        {
            "url": "https://www.demo-advertiser.com/medalions",
            "thumbnail_url": "https://cdn.demo-advertiser.com/thumbnails/thumbnail-3.jpg",
            "title": "Beautiful medallions"
        }
    ]
}
{
    "results": [
        {
            "id": "875",
            "campaign_id": "1234",
            "type": "ITEM",
            "url": "https://www.demo-advertiser.com/wedding-rings",
            "thumbnail_url": "https://cdn.demo-advertiser.com/thumbnails/thumbnail-1.jpg",
            "title": "The perfect wedding ring",
            "description": null,
            "approval_state": "PENDING",
            "is_active": true,
            "status": "PENDING_APPROVAL",
            "policy_review": {
                "reject_reason": null,
                "reject_reason_description": null,
                "status_reason": null,
                "reviewer_notes": null
            },
            "cta": null,
            "creative_focus": {
                "type": "AUTOMATIC",
                "coordinates": null
            },
            "verification_pixel": null,
            "viewability_tag": null,
            "app_install": null,
            "rating": null,
            "logo": null,
            "disclaimer": null,
            "creative_crop": null,
            "external_metadata": null
        },
        {
            "id": "876",
            "campaign_id": "1234",
            "type": "ITEM",
            "url": "https://www.demo-advertiser.com/proposal-rings",
            "thumbnail_url": "https://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,
                "reject_reason_description": null,
                "status_reason": null,
                "reviewer_notes": null
            },
            "cta": null,
            "creative_focus": {
                "type": "AUTOMATIC",
                "coordinates": null
            },
            "verification_pixel": null,
            "viewability_tag": null,
            "app_install": null,
            "rating": null,
            "logo": null,
            "disclaimer": null,
            "creative_crop": null,
            "external_metadata": null
        },
        {
            "id": "877",
            "campaign_id": "1234",
            "type": "ITEM",
            "url": "https://www.demo-advertiser.com/medalions",
            "thumbnail_url": "https://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,
                "reject_reason_description": null,
                "status_reason": null,
                "reviewer_notes": null
            },
            "cta": null,
            "creative_focus": {
                "type": "AUTOMATIC",
                "coordinates": null
            },
            "verification_pixel": null,
            "viewability_tag": null,
            "app_install": null,
            "rating": null,
            "logo": null,
            "disclaimer": null,
            "creative_crop": null,
            "external_metadata": null
        }
    ],
    "metadata": {
        "total": 0,
        "count": 0,
        "static_fields": [],
        "static_total_fields": [],
        "dynamic_fields": null,
        "start_date": null,
        "end_date": null
    }
}
πŸ“˜

Required fields (for static items)

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

Optional fields (for static items)

  1. description
  2. cta
  3. creative_focus

    This field has been deprecated.

🚧

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 for a campaign:

POST /backstage/api/1.0/demo-advertiser/campaigns/1234/items/mass
{
    "collection": [
        {
            "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"
            }
        },
        {
            "title": "Another video ad",
            "url": "https://example.com",
            "creative_type": "PERFORMANCE_VIDEO",
            "performance_video_data": {
                "video_url": "https://example.com/video2.mp4",
                "fallback_url": "https://example.com/fallback2.jpg"
            }
        }
    ]
}
{
    "results": [
        {
            "id": "555",
            "campaign_id": "1234",
            "type": "ITEM",
            "url": "https://example.com",
            "thumbnail_url": "https://example.com/fallback.jpg",
            "title": "Amazing video ad",
            "description": null,
            "approval_state": "PENDING",
            "is_active": true,
            "status": "PENDING_APPROVAL",
            "policy_review": {
                "reject_reason": null,
                "reject_reason_description": null,
                "status_reason": null,
                "reviewer_notes": null
            },
            "cta": null,
            "creative_focus": null,
            "verification_pixel": null,
            "viewability_tag": null,
            "app_install": null,
            "rating": null,
            "logo": null,
            "disclaimer": null,
            "creative_crop": null,
            "external_metadata": null,
            "branding_text": null,
            "creative_type": "PERFORMANCE_VIDEO",
            "performance_video_data": {
                "video_url": "https://example.com/video.mp4",
                "fallback_url": "https://example.com/fallback.jpg",
                "gif_url": "https://example.com/gif.gif",
                "recommended_fallback_image": null,
                "media_upload_source": "URL",
                "motion_ads_studio": {
                    "vendor_template_type": null,
                    "vendor_video_id": null
                }
            },
            "display_data": null,
            "hierarchy_rep_item_id": null,
            "hierarchy_data": null,
            "custom_data": null,
            "start_date": null,
            "end_date": null,
            "activity_schedule": null,
            "orientation": "HORIZONTAL"
        },
        {
            "id": "556",
            "campaign_id": "1234",
            "type": "ITEM",
            "url": "https://example.com",
            "thumbnail_url": "https://example.com/fallback2.jpg",
            "title": "Another video ad",
            "description": null,
            "approval_state": "PENDING",
            "is_active": true,
            "status": "PENDING_APPROVAL",
            "policy_review": {
                "reject_reason": null,
                "reject_reason_description": null,
                "status_reason": null,
                "reviewer_notes": null
            },
            "cta": null,
            "creative_focus": null,
            "verification_pixel": null,
            "viewability_tag": null,
            "app_install": null,
            "rating": null,
            "logo": null,
            "disclaimer": null,
            "creative_crop": null,
            "external_metadata": null,
            "branding_text": null,
            "creative_type": "PERFORMANCE_VIDEO",
            "performance_video_data": {
                "video_url": "https://example.com/video2.mp4",
                "fallback_url": "https://example.com/fallback2.jpg",
                "gif_url": "https://example.com/gif2.gif",
                "recommended_fallback_image": null,
                "media_upload_source": "URL",
                "motion_ads_studio": {
                    "vendor_template_type": null,
                    "vendor_video_id": null
                }
            },
            "display_data": null,
            "hierarchy_rep_item_id": null,
            "hierarchy_data": null,
            "custom_data": null,
            "start_date": null,
            "end_date": null,
            "activity_schedule": null,
            "orientation": "HORIZONTAL"
        }
    ],
    "metadata": {
        "total": 0,
        "count": 0,
        "static_fields": [],
        "static_total_fields": [],
        "dynamic_fields": null,
        "start_date": null,
        "end_date": null
    }
}
πŸ“˜

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

🚧

Guidelines

  1. Use the items/mass endpoint, with a Campaign ID path param.
  2. Mass create supports both regular items and motion ads. You can mix both ad types in the same request.
  3. The new Items are created with a status of PENDING. Once approved, their status is updated to APPROVED.
  4. The endpoint saves the above values without crawling the URL. Make sure that the values passed are acceptable to Taboola.
πŸ“˜

See also

Language
Credentials
OAuth2