Ads Creative

Guides

Promoted Video Overview

Currently, the Ads API supports Promoted Video through the Tweet creation endpoint and through the Video App Download Card. Additional video support will continue to be added as it’s available. This document gives a brief overview of the process for uploading video and promoting it through the Ads API today.

For detailed guidance on video uploading through the API, please see the Video Upload Guide

API Reference Documents

Tweets

GET accounts/:account_id/cards/app_download

Retrieve card information about app download cards for a given account. This card is part of our Mobile App Promotion suite of endpoints.

GET accounts/:account_id/cards/app_download/:card_id

Retrieve card information about a given app download card. This card is part of our Mobile App Promotion suite of endpoints.

POST accounts/:account_id/cards/app_download

Creates a new app download card associated to a given account. This card is part of our Mobile App Promotion suite of endpoints.

PUT accounts/:account_id/cards/app_download/:card_id

Updates an app download card associated to a given account.

DELETE accounts/:account_id/cards/app_download/:card_id

Delete a given app download card. This card is part of our Mobile App Promotion suite of endpoints.

GET accounts/:account_id/cards/image_app_download

Retrieve card information about image app download cards for a given account. This card is part of our Mobile App Promotion suite of endpoints.

GET accounts/:account_id/cards/image_app_download/:card_id

Retrieve card information about a given image app download card. This card is part of our Mobile App Promotion suite of endpoints.

POST accounts/:account_id/cards/image_app_download

Creates a new image app download card associated to a given account. This card is part of our Mobile App Promotion suite of endpoints.

PUT accounts/:account_id/cards/image_app_download/:card_id

Updates an image app download card associated to a given account.

DELETE accounts/:account_id/cards/image_app_download/:card_id

Delete a given image app download card. This card is part of our Mobile App Promotion suite of endpoints.

GET accounts/:account_id/cards/lead_gen

Retrieve card information about given lead generation card.

GET accounts/:account_id/cards/lead_gen/:card_id

Retrieve card information about a given lead generation card

POST accounts/:account_id/cards/lead_gen

Creates a new lead generation card associated to a given account.

DELETE accounts/:account_id/cards/lead_gen/:card_id

Delete a given lead generation card

PUT accounts/:account_id/cards/website/:card_id

Updates a new website card associated to a given account.

POST accounts/:account_id/promoted_accounts

Associate a Promoted Account to the specified line item.

If the specified line item is not configured to be associated with Promoted Accounts, a HTTP 400 INCOMPATIBLE_LINE_ITEM error will be returned. If the specified user is ineligible for promotion, a HTTP 400 will be returned and no users will be promoted. If the provided user is already promoted, the request will be ignored.

GET accounts/:account_id/promoted_tweets

Retrieve references to the Promoted Tweets associated with one or more line items.

Use GET statuses/show/:id to obtain tweet data for the tweets identified by tweet_id in the response.

Note: An HTTP 400 will be returned if none of the specified line items are configured to contain Promoted Tweets.

POST accounts/:account_id/promoted_tweets

Associate one or more Promoted Tweets to the specified line item.

Note that for PROMOTED_ACCOUNT campaigns, associating a Promoted Tweet to the line_item will add timeline placements on mobile in addition to the standard PROMOTED_ACCOUNT placement.

Also note that not all tweets are appropriate for tweet promotion, depending on the campaign objective. Please see Objective-based Campaigns for more information.

DELETE accounts/:account_id/promoted_tweets/:id

Disassociate a Promoted Tweet from a line item by specifying its instance id.

Other

PUT accounts/:account_id/cards/lead_gen/:card_id

Updates a lead generation card associated to a given account.

GET accounts/:account_id/cards/website

Retrieve card information about website cards for a given account.

GET accounts/:account_id/cards/website/:card_id

Retrieve card information about a given website card.

POST accounts/:account_id/cards/website

Creates a new website card associated to a given account. Our advertiser help center has details on website card set- up in the ads.twitter.com UI.

See Uploading Media for useful information on uploading images to our endpoints.

DELETE accounts/:account_id/cards/website/:card_id

Delete a given website card.

GET accounts/:account_id/cards/video_app_download

Retrieve card information about all Video App Download Cards for the specified account. This card is part of our Mobile App Promotion suite of endpoints.

Related endpoints:

GET accounts/:account_id/cards/video_app_download/:id

Retrieve card information about a given Video App Download Card. This card is part of our Mobile App Promotion suite of endpoints.

Related endpoints:

POST accounts/:account_id/cards/video_app_download

Creates a new Video App Download Card associated to the specified account. This card is part of our Mobile App Promotion suite of endpoints.

Related endpoints:

PUT accounts/:account_id/cards/video_app_download/:id

Updates a specific Video App Download Card associated to the account. This card is part of our Mobile App Promotion suite of endpoints.

Related endpoints:

DELETE accounts/:account_id/cards/video_app_download/:id

Delete a given Video App Download Card. This card is part of our Mobile App Promotion suite of endpoints.

Related endpoints:

GET accounts/:account_id/promoted_accounts

Retrieve references to the Promoted Accounts associated with one or more line items.

Use GET users/lookup to obtain user data for the user accounts identified by user_id in the response.

Note: An HTTP 400 will be returned if none of the specified line items are configured to contain Promoted Accounts.

PUT accounts/:account_id/promoted_tweets/:id

Update the specified promoted tweet belonging to the current account.

GET accounts/:account_id/tweet/preview

Preview a Tweet that does not already exist as it would appear across a variety of different platforms; iPhone, Android and Web. You can preview a Tweet both for how it will look like on Twitter or on the Twitter Audience Platform (TAP).

The returned JSON response will contain the preview HTML; this is a fully functional HTML document that is ready to be used to render a preview Tweet in a browser. The relevant CSS and images will be served directly via Twitter.

Note that previews are approximate.

GET accounts/:account_id/tweet/preview/:tweet_id

Preview an existing Tweet as it would appear across a variety of different platforms; iPhone, Android and Web. You can preview a Tweet both for how it will look like on Twitter or on the Twitter Audience Platform (TAP).

The returned JSON response will contain the preview HTML; this is a fully functional HTML document that is ready to be used to render a preview Tweet in a browser. The relevant CSS and images will be served directly via Twitter.

Note that previews are approximate.

GET accounts/:account_id/scoped_timeline

Retrieve up to 200 of the most recent promotable Tweets created by one or more specified Twitter users. These users may be any account for which the current account has account access. This endpoint works for any user with access to an Ads Account, not only the Twitter @handle which authors the promotable Tweets.

Note: When filtering by objective, we will fetch the first set of promotable Tweets and then filter those appropriate for the objective. This results in inconsistent page sizes in the results. If you see a next_cursor returned, there are additional Tweets available for this filter.

GET accounts/:account_id/videos

Retrieve all video objects associated belonging to the current account.

Related video endpoints:

GET accounts/:account_id/videos/:id

Retrieve a specific video object belonging to the current account.

Related video endpoints:

POST accounts/:account_id/videos

Create a video associated with the current account.

Related video endpoints:

PUT accounts/:account_id/videos/:id

Update the specified video object belonging to the current account.

Related video endpoints:

DELETE accounts/:account_id/videos/:id

Delete the specified video belonging to the current ads account.

Related video endpoints: