Video Views Pre-roll Objective
The following guide outlines the steps required to set up a PREROLL_VIEWS campaign on the Ads API. Broadly speaking these campaigns are split into two types, Curated Categories and Content Categories (referred to as Standard Categories on the Ads UI).
Endpoints Required
- Chunked media upload (for video upload)
- POST accounts/:account_id/media_library (for video association to ads account)
- POST accounts/:account_id/campaigns (create campaign)
- GET content_categories (to get the mapping of content categories to IAB categories)
- GET accounts/:account_id/curated_categories
- GET publishers
- POST accounts/:account_id/line_item_curated_categories
- POST accounts/:account_id/line_items (create ad group)
- POST accounts/:account_id/media_creatives (to associate video with ad group)
- POST accounts/:account_id/preroll_call_to_action (set CTA and redirect URL)
- POST batch/accounts/:account_id/targeting_criteria (targeting)
Steps
Upload the video
Uploading the video involves 2 steps:
Upload the video media
First, using the Chunked media upload endpoint, you will upload the video to Twitter for processing. You must pass the media_category=amplify_video on the initial INIT using this endpoint. You’ll upload the video in chunks. Once the STATUS returns a state of succeeded you may continue with the next steps. More on the uploading of media using the chunked endpoint can be found in our Promoted Video Overview.
Add the video to the ads account
Once the state returned using the STATUS command is succeeded, you’ll use the media_key returned from that endpoint to add the video to the advertiser’s media library, using the POST accounts/:account_id/media_library endpoint.
POST https://ads-api.x.com/8/55w3kv/media_library?media_key=3_931236738554519552
{
"request": {
"params": {
"account_id": "55w3kv",
"media_key": "3_931236738554519552"
}
},
"data": {
"tweeted": false,
"name": null,
"file_name": null,
"media_url": "https://video.twimg.com/amplify_video/1059840836186165250/vid/568x320/Gr2l1fB1X7xotKwC.mp4?tag=8",
"media_category": "AMPLIFY_VIDEO",
"media_key": "3_931236738554519552",
"created_at": "2017-11-16T19:05:14Z",
"media_status": "TRANSCODE_COMPLETED",
"media_id": 931236738554519552,
"media_type": "VIDEO",
"updated_at": "2017-11-16T19:05:23Z",
"deleted": false
}
}
Setup the campaign
Campaign Creation
Create the campaign and line item/ad group. Line items should be created with an objective of VIDEO_VIEWS_PREROLL, and a product_type of MEDIA. The categories parameter must also be set to the appropriate advertiser business categories.
POST https://ads-api.x.com/8/accounts/55w3kv/campaigns?name=test-curated-categories-api&funding_instrument_id=103hp9&start_time=2021-02-10&entity_status=PAUSED&daily_budget_amount_local_micro=55000000
{
"request": {
"params": {
"name": "test-curated-categories-api",
"start_time": "2021-02-10T00:00:00Z",
"daily_budget_amount_local_micro": 55000000,
"funding_instrument_id": "103hp9",
"entity_status": "PAUSED",
"account_id": "55w3kv"
}
},
"data": {
"name": "test-curated-categories-api",
"start_time": "2021-02-10T00:00:00Z",
"reasons_not_servable": [
"EXPIRED",
"PAUSED_BY_ADVERTISER",
"FUNDING_PROBLEM"
],
"servable": false,
"purchase_order_number": null,
"effective_status": "PAUSED",
"daily_budget_amount_local_micro": 55000000,
"end_time": null,
"funding_instrument_id": "103hp9",
"duration_in_days": null,
"standard_delivery": true,
"total_budget_amount_local_micro": null,
"id": "f2rp3",
"entity_status": "PAUSED",
"frequency_cap": null,
"currency": "USD",
"created_at": "2021-02-08T23:55:38Z",
"updated_at": "2021-02-08T23:55:38Z",
"deleted": false
}
}
Line Item Creation
Line items must have the categories parameter set to the appropriate set of IAB categories, retrieved via the GET content_categories endpoint. These content categories each correspond to one or more IAB categories.
In order to use these values, partners must select an appropriate content category and use the entire set of iab_categories returned in the response, to set the categories parameter on the line items endpoint. Any partial application of the iab_categories will result in the entire group being set on the line item. For example,
GET https://ads-api.x.com/8/advertiser_business_categories
{
"request": {
"params": {}
},
"next_cursor": null,
"data": [
{
"id": "1jl",
"name": "Consumer Packaged Goods",
"iab_categories": [
"IAB9-26",
"IAB9-18",
"IAB9-29",
"IAB9-1",
"IAB9-8",
"IAB9-22",
"IAB6",
"IAB9-5",
"IAB9-12",
"IAB9-11",
"IAB9-23",
"IAB9-14",
"IAB4",
"IAB9-25",
"IAB9-17",
"IAB23",
"IAB9-24",
"IAB9-13",
"IAB16",
"IAB9-4",
"IAB9-9",
"IAB9-20",
"IAB22",
"IAB9-28",
"IAB9-27",
"IAB9-16",
"IAB9-31",
"IAB9-3",
"IAB9-19",
"IAB10",
"IAB9-2",
"IAB9-6",
"IAB9-21",
"IAB9-10",
"IAB9-15"
]
},
{
"id": "1jm",
"name": "Health & Pharma",
"iab_categories": [
"IAB7"
]
},
{
"id": "1jn",
"name": "Alcohol",
"iab_categories": [
"IAB8-5",
"IAB8-18"
]
},
{
"id": "1jo",
"name": "Dining",
"iab_categories": [
"IAB8-10",
"IAB8-8",
"IAB8-7",
"IAB8-15",
"IAB8-3",
"IAB8-4",
"IAB8-1",
"IAB8-16",
"IAB8-12",
"IAB8-13",
"IAB8-17",
"IAB8-11",
"IAB8-6",
"IAB8-9",
"IAB8-2",
"IAB8-14"
]
},
{
"id": "1jp",
"name": "Financial Services",
"iab_categories": [
"IAB3",
"IAB13",
"IAB21"
]
},
{
"id": "1jq",
"name": "Retail",
"iab_categories": [
"IAB18"
]
},
{
"id": "1jr",
"name": "Travel",
"iab_categories": [
"IAB20"
]
},
{
"id": "1js",
"name": "Gaming",
"iab_categories": [
"IAB9-30"
]
},
{
"id": "1jt",
"name": "Technology",
"iab_categories": [
"IAB19-22",
"IAB19-13",
"IAB19-4",
"IAB19-33",
"IAB19-26",
"IAB19-3",
"IAB19-16",
"IAB19-9",
"IAB19-32",
"IAB19-25",
"IAB19-30",
"IAB19-36",
"IAB19-21",
"IAB5",
"IAB19-12",
"IAB19-28",
"IAB19-17",
"IAB19-8",
"IAB19-7",
"IAB19-24",
"IAB15",
"IAB19-11",
"IAB19-31",
"IAB19-20",
"IAB19-15",
"IAB19-1",
"IAB19-35",
"IAB19-29",
"IAB19-34",
"IAB19-23",
"IAB19-2",
"IAB19-5",
"IAB19-14",
"IAB19-27",
"IAB19-10",
"IAB19-19"
]
},
{
"id": "1ju",
"name": "Telecommunication",
"iab_categories": [
"IAB19-6",
"IAB19-18"
]
},
{
"id": "1jv",
"name": "Auto",
"iab_categories": [
"IAB2"
]
},
{
"id": "1jw",
"name": "Media & Entertainment",
"iab_categories": [
"IAB14-8",
"IAB14-4",
"IAB1-5",
"IAB14-7",
"IAB1-7",
"IAB17",
"IAB14-3",
"IAB1-1",
"IAB12",
"IAB1-6",
"IAB25-1",
"IAB1-2",
"IAB14-2",
"IAB14-6",
"IAB1-3",
"IAB1-4",
"IAB14-5"
]
},
{
"id": "1jx",
"name": "Politics",
"iab_categories": [
"IAB11-4"
]
},
{
"id": "1jy",
"name": "Gambling",
"iab_categories": [
"IAB9-7"
]
},
{
"id": "1jz",
"name": "Dating",
"iab_categories": [
"IAB14-1"
]
},
{
"id": "1k0",
"name": "Non-Profit",
"iab_categories": [
"IAB11-1",
"IAB11-2",
"IAB11-3",
"IAB11-5"
]
}
]
}
Now, in order to set the categories parameter to "Science & Education", the entire set of iab_categories i.e., "IAB5", "IAB15" must be set for the line item, like so:
POST https://ads-api.x.com/8/accounts/55w3kv/line_items?campaign_id=f2rp3&bid_amount_local_micro=5500000&name=curated-category-line-item&product_type=MEDIA&placements=ALL_ON_TWITTER&objective=PREROLL_VIEWS&categories=IAB3,IAB13,IAB21
{
"request": {
"params": {
"name": "curated-category-line-item",
"placements": [
"ALL_ON_TWITTER"
],
"bid_amount_local_micro": 5500000,
"product_type": "MEDIA",
"objective": "PREROLL_VIEWS",
"account_id": "55w3kv",
"categories": [
"IAB3",
"IAB13",
"IAB21"
],
"campaign_id": "f2rp3"
}
},
"data": {
"bid_type": "MAX",
"advertiser_user_id": 312226591,
"name": "curated-category-line-item",
"placements": [
"ALL_ON_TWITTER"
],
"start_time": null,
"bid_amount_local_micro": 5500000,
"automatically_select_bid": false,
"advertiser_domain": null,
"target_cpa_local_micro": null,
"raw_categories": [
"x",
"5l",
"9z"
],
"primary_web_event_tag": null,
"charge_by": "VIEW_3S_100PCT",
"product_type": "PROMOTED_TWEETS",
"end_time": null,
"duration_in_days": null,
"bid_unit": "VIEW_3S_100PCT",
"total_budget_amount_local_micro": null,
"objective": "PREROLL_VIEWS",
"id": "iqwka",
"entity_status": "ACTIVE",
"automatic_tweet_promotion": null,
"optimization": "DEFAULT",
"frequency_cap": null,
"android_app_store_identifier": null,
"categories": [
"IAB3",
"IAB13",
"IAB21"
],
"currency": "USD",
"created_at": "2021-02-09T00:00:46Z",
"tracking_tags": [],
"ios_app_store_identifier": null,
"amplify_config": {
"auto_promote": true,
"is_open": true
},
"updated_at": "2021-02-09T00:00:46Z",
"campaign_id": "f2rp3",
"creative_source": "MANUAL",
"deleted": false
}
}
Publisher Selection
An advertiser may choose to target either a Content Category or a Curated Category, with additional details described below.
Note: Line items may target either Curated or Content Categories but not both.
Curated Categories
Curated Categories allow advertisers to target a preset group of publishers and can be retrieved using the GET curated_categories endpoint. These categories are country specific, and therefore require that the line item target the appropriate country based on the country_code of the category.
In order to use one of these categories, the following steps are required in the specific order listed:
- The line item needs to target the appropriate country based on the country_code of the Curated Category
- The POST line_item_curated_categories endpoint must be used to associate the line item with a specific curated_category_id.
Note: Associating a line item with a curated category will also limit the number of publishers that can be denylisted to 5. The full list of user_id used to denylist specific publishers can be retrieved from the GET publishers endpoint. Additionally, a given line item may target no more than one Curated Category at a time.
The following example illustrates how to associate a curated category id: b0xt which is only available in the US, with the line item created in the previous step.
First, the line item’s targeting criteria is set to the the value 96683cc9126741d
GET https://ads-api.x.com/8/targeting_criteria/locations?country_code=US&location_type=COUNTRIES
{
"data": [
{
"name": "United States",
"country_code": "US",
"location_type": "COUNTRIES",
"targeting_value": "96683cc9126741d1",
"targeting_type": "LOCATION"
}
],
"request": {
"params": {
"location_type": "COUNTRIES",
"country_code": "US"
}
},
"next_cursor": null
}
POST https://ads-api.x.com/8/batch/accounts/55w3kv/targeting_criteria
[
{
"operation_type": "Create",
"params": {
"line_item_id": "iqwka",
"targeting_type": "LOCATION",
"targeting_value": "96683cc9126741d1",
"operator_type": "EQ"
}
}
]
{
"data": [
{
"line_item_id": "iqwka",
"name": "United States",
"raw_negated": false,
"raw_targeting_value": "2",
"id": "rv9hmc",
"raw_targeting_type": "GEO",
"raw_operator_type": "EQUAL_TO",
"location_type": "COUNTRIES",
"operator_type": "EQ",
"created_at": "2021-02-09T00:06:28Z",
"targeting_value": "96683cc9126741d1",
"updated_at": "2021-02-09T00:06:28Z",
"deleted": false,
"targeting_type": "LOCATION"
}
],
"request": [
{
"params": {
"line_item_id": "iqwka",
"account_id": "55w3kv",
"operator_type": "EQ",
"targeting_value": "96683cc9126741d1",
"targeting_type": "LOCATION"
},
"operation_type": "Create"
}
]
}
POST https://ads-api.x.com/8/accounts/55w3kv/line_item_curated_categories?line_item_id=iqwka&curated_category_id=9ddrgesiap6o
{
"request": {
"params": {
"curated_category_id": "9ddrgesiap6o",
"line_item_id": "iqwka",
"account_id": "55w3kv"
}
},
"data": {
"line_item_id": "iqwka",
"curated_category_id": "9ddrgesiap6o",
"id": "xq",
"created_at": "2021-03-30T17:26:42Z",
"updated_at": "2021-03-30T17:26:42Z",
"deleted": false
}
}
Content Categories
Content categories, also referred to as Standard Categories can be retrieved from the GET curated_categories endpoint. These categories can then be targeted by the line item using the batch targeting criteria endpoints. The following example illustrates how to select a particular content category, id: sr which maps to “News & Current Events” and apply it to the line item.
Note: The entire set of iab_categories in the GET curated_categories response must be targeted via the targeting criteria endpoint. Failing to do so will result in a validation error.
GET https://ads-api.x.com/8/content_categories
{
"name": "News & Current Events",
"id": "sr",
"iab_categories": [
"IAB12",
"IAB14"
],
"publishers_in_last_thirty_days": 124,
"videos_monetized_in_last_thirty_days": 5429
}
}
POST https://ads-api.x.com/8/batch/accounts/55w3kv/targeting_criteria
[
{
"operation_type": "Create",
"params": {
"line_item_id": "iqwls",
"targeting_type": "IAB_CATEGORY",
"targeting_value": "IAB12",
"operator_type": "EQ"
}
},
{
"operation_type": "Create",
"params": {
"line_item_id": "iqwls",
"targeting_type": "IAB_CATEGORY",
"targeting_value": "IAB14",
"operator_type": "EQ"
}
}
]
{
"data": [
{
"line_item_id": "iqwls",
"name": "News",
"raw_negated": false,
"raw_targeting_value": "5h",
"id": "saib9p",
"raw_targeting_type": "IAB_CATEGORY",
"raw_operator_type": "EQUAL_TO",
"operator_type": "EQ",
"created_at": "2021-03-30T17:35:50Z",
"targeting_value": "IAB12",
"updated_at": "2021-03-30T17:35:50Z",
"deleted": false,
"targeting_type": "IAB_CATEGORY"
},
{
"line_item_id": "iqwls",
"name": "Society",
"raw_negated": false,
"raw_targeting_value": "5y",
"id": "saib9q",
"raw_targeting_type": "IAB_CATEGORY",
"raw_operator_type": "EQUAL_TO",
"operator_type": "EQ",
"created_at": "2021-03-30T17:35:50Z",
"targeting_value": "IAB14",
"updated_at": "2021-03-30T17:35:50Z",
"deleted": false,
"targeting_type": "IAB_CATEGORY"
}
],
"request": [
{
"params": {
"line_item_id": "iqwls",
"account_id": "55w3kv",
"operator_type": "EQ",
"targeting_value": "IAB12",
"targeting_type": "IAB_CATEGORY"
},
"operation_type": "Create"
},
{
"params": {
"line_item_id": "iqwls",
"account_id": "55w3kv",
"operator_type": "EQ",
"targeting_value": "IAB14",
"targeting_type": "IAB_CATEGORY"
},
"operation_type": "Create"
}
]
}
Associate the account media (video) with the line item
Use the POST accounts/:account_id/media_creatives endpoint to associate the video with an ad group.
POST https://ads-api.x.com/8/accounts/55w3kv/media_creatives line_item_id=4bii5&account_media_id=knb
{
"data":{
"account_media_id":"74g",
"approval_status":"ACCEPTED",
"created_at":"2016-02-11T22:23:23Z",
"deleted":false,
"id":"qeq",
"landing_url":null,
"line_item_id":"4bii5",
"serving_status":"ACTIVE",
"updated_at":"2016-02-11T22:23:23Z"
},
"request":{
"params":{
"line_item_id":"4bii5",
"account_media_id":"knb"
}
}
}
Set the CTA and destination URL
It is important to note that unlike most other campaigns on Twitter, the VIDEO_VIEWS_PREROLL objective does not utilize Promoted Tweets or Cards. Instead, the video creative is associated with your ad group (line item) and the CTA information is associated with a preroll_call_to_action entity. The POST accounts/:account_id/preroll_call_to_action endpoint allows you to control the button CTA and the destination URL.
POST https://ads-api.x.com/8/accounts/55w3kv/preroll_call_to_action line_item_id=4bii5&call_to_action=VISIT_SITE&call_to_action_url=https%3A%2F%2Ftwitter.com%2FAdsAPI
{
"data":{
"id":"aaa111",
"line_item_id":"4bii5",
"call_to_action":"WATCH_NOW",
"call_to_action_url":"https://twitter.com/AdsAPI",
"created_at":"2016-02-11T22:23:23Z",
"updated_at":"2016-02-11T22:23:23Z",
"deleted":false
},
"request":{
"params":{
"line_item_id":"4bii5",
"call_to_action":"VISIT_SITE",
"call_to_action_url":"https://twitter.com/AdsAPI"
}
}
}
Set targeting criteria
The targetting criterion utilized for pre-roll video ads is only avaialble using our batch targeting criteria endpoint POST batch/accounts/:account_id/targeting_criteria.
Use CONTENT_PUBLISHER_USER as negated targeting to exclude the ad from being paired with a set of users. Provide the Twitter user_id or publisher_user_id for the handles to exclude.
The GET publishers endpoint can be used to retrieve the list of user_id to exclude for Content Categories. The publisher_user_id returned in the GET curated_categories response can be used to retrieve a similar exclusion list for Curated Categories.
Note: A maximum of 5 publisher_user_id can be excluded for Curated Categories and 50 user_id for Content Categories.
POST https://ads-api.x.com/8/batch/accounts/55w3kv/targeting_criteria
[
{
"operation_type": "Create",
"params": {
"line_item_id": "iqwls",
"targeting_type": "CONTENT_PUBLISHER_ID",
"targeting_value": "1917731",
"operator_type": "NE"
}
}
]
{
"data": [
{
"line_item_id": "iqwka",
"name": "realsaltlake",
"raw_negated": true,
"raw_targeting_value": "aajwo",
"id": "sajk32",
"raw_targeting_type": "CONTENT_PUBLISHER",
"raw_operator_type": "EQUAL_TO",
"operator_type": "NE",
"created_at": "2021-03-30T18:02:32Z",
"targeting_value": 17288520,
"updated_at": "2021-03-30T18:02:32Z",
"deleted": false,
"targeting_type": "CONTENT_PUBLISHER_USER"
}
],
"request": [
{
"params": {
"line_item_id": "iqwka",
"account_id": "55w3kv",
"operator_type": "NE",
"targeting_value": "17288520",
"targeting_type": "CONTENT_PUBLISHER_USER"
},
"operation_type": "Create"
}
]
}
Launch campaign
When you’re ready to launch your campaign, simply un-pause using PUT accounts/:account_id/campaigns/:id.
PUT https://ads-api.x.com/8/accounts/55w3kv/campaigns/f2rp3? entity_status=ACTIVE
{
"request": {
"params": {
"campaign_id": "f2rp3",
"account_id": "55w3kv"
}
},
"data": {
"name": "test-curated-categories-api",
"start_time": "2021-02-10T00:00:00Z",
"reasons_not_servable": [
],
"servable": false,
"purchase_order_number": null,
"effective_status": "ACTIVE",
"daily_budget_amount_local_micro": 55000000,
"end_time": null,
"funding_instrument_id": "103hp9",
"duration_in_days": null,
"standard_delivery": true,
"total_budget_amount_local_micro": null,
"id": "f2rp3",
"entity_status": "ACTIVE",
"frequency_cap": null,
"currency": "USD",
"created_at": "2021-02-08T23:55:38Z",
"updated_at": "2021-02-08T23:55:38Z",
"deleted": false
}
}
Analytics
Analytics for VIDEO_VIEWS_PREROLL campaigns are available using our stats endpoints.