The Wayback Machine - https://web.archive.org/web/20160617151116/https://dev.twitter.com/ads/creative

Ads Creative

Guides

Revenue Cards

The Ads API supports a number of creatives to be used in your campaigns. The following specs apply to the app_download, image_app_download, image_conversation, lead_gen, website card endpoints.

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

GET accounts/:account_id/cards/image_conversation

Retrieve information about image conversation cards for a given account.

GET accounts/:account_id/cards/image_conversation/:card_id

Retrieve information about a given image conversation card.

POST accounts/:account_id/cards/image_conversation

Creates a new image conversation card associated to a given account.

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

PUT accounts/:account_id/cards/image_conversation/:card_id

Updates an image conversation card associated to a given account.

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

DELETE accounts/:account_id/cards/image_conversation/:card_id

Delete a given image conversation card.

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.

Note: The website_cta parameter has been deprecated and will now be ignored in rendering of this card to users.

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/cards/video_conversation

Retrieve information about video conversation cards for a given account.

GET accounts/:account_id/cards/video_conversation/:card_id

Retrieve information about a given video conversation card.

POST accounts/:account_id/cards/video_conversation

Creates a new video conversation card associated to a given account.

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

PUT accounts/:account_id/cards/video_conversation/:card_id

Updates an video conversation card associated to a given account.

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

DELETE accounts/:account_id/cards/video_conversation/:card_id

Delete a given video conversation card.

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 the specified Twitter user. This user 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.

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/media_creatives/:id

Removes a media creative for the current ads account.

DELETE accounts/:account_id/videos/:id

Delete the specified video belonging to the current ads account.

Related video endpoints:

GET accounts/:account_id/account_media

Retrieve account media for the specified ads account.

GET accounts/:account_id/account_media/:id

Retrieves details for specified account media associated to current ads account.

GET accounts/:account_id/media_creatives

Retrieve details for all the media_creatives associated with the current account.

GET accounts/:account_id/media_creatives/:id

Retrieves details for a specific media creative associated with the current account.

POST accounts/:account_id/account_media

Creates a new account media associated to the current account.

Prerequisite: Use the POST media/upload endpoint to upload the image or video to be used as the media creative. See Uploading Media for help on uploading an image.

POST accounts/:account_id/media_creatives

Creates a new media creative associated to the current account.

Prequisite: Use the POST accounts/:account_id/account_media first to set up the account media with the desired image.

The landing_url is optional when media is video for use in VIDEO_VIEWS_PREROLL campaigns.