Ads API Version 2
Today we are releasing version 2 of the Ads API.
This release includes the ability to create and manage Scheduled Tweets, a new ad format—the video website card—for clickable video, [and] additional draft campaign functionality
, and an endpoint for retrieving summary information for asynchronous analytics jobs. Version 2 of the Ads API also includes performance improvements to our promoted_tweets endpoint as well as minor updates to parameter names and response attributes.
While we encourage all partners and developers to migrate to v2 of the Ads API as soon as possible, we will provide a 6-month transition period. This means that, on January 16,
January 10, 2018, v1 of the Ads API will be turned off.
With v2, it is possible to create Scheduled Tweets using the Ads API, edit or delete them while they’re still in a
SCHEDULED state, and associate them with line items. Scheduled Tweets do not become actual Tweets until the specified
scheduled_at time. This means that no other Twitter user can see them until that time; Scheduled Tweets will never appear in the Gnip Firehose. This feature is in a beta state and we’ll continue making improvements based on user feedback. Also note that this feature is not available in the sandbox environment.
Video Website Cards
Our new ad format, the video website card, allows advertisers to promote their websites using videos. The video renders and autoplays (muted) in the Twitter timeline and, on click, drives the user to the specified website. On mobile, the video continues to play at the top of the screen while the website loads below it. On desktop, clicking takes the user directly to the site. This feature is in a beta state and we’ll continue making improvements based on user feedback.
We previously added the ability to view and edit existing draft campaigns. In v2, it will be possible to activate these campaigns as well as create new campaigns in draft mode. This is controlled by the new
entity_status parameter on
line_items which takes three possible values:
PAUSED. To simplify logic around the various states these entities can exist in, we’ve removed the
### Asynchronous Analytics Summaries
The new asynchronous analytics endpoint will provide summary information on every job created in the past 15 days by the client app ID, across all ads accounts.
In addition to these new features, we’re including a number of minor changes, listed below.
- The new
with_total_countparameter will be available for all index endpoints (e.g., GET accounts/:account_id/campaigns).
- The new
entity_statusparameter (already included as a response attribute) will be writable on campaigns and line items. This controls whether a campaign or line item is active, in draft mode, or is paused.
- The new
card_uriparameter is accepted in the POST accounts/:account_id/tweet and POST statuses/update endpoints. (We plan to support this for Scheduled Tweets and Tweet preview as well.) This should be used in favor of
preview_urlwhen associating cards with Tweets. Not all cards currently support
card_uri; i.e., the response attribute value may be
null. In these cases, use the
preview_url. We are working toward migrating all cards to use
- We have renamed the
textfor both the POST accounts/:account_id/tweet and GET accounts/:account_id/tweet/preview endpoints.
- The GET targeting_criteria/locations endpoint’s
location_typeenums are now plural.
REGIONS, and so on. The one exception is that, in v2,
METROS, to correctly reflect the fact that the location type refers to Designated Marker Areas (DMAs) or “metros.”
pausedparameter is no longer accepted nor returned in the response. To pause campaigns or line items, use the
- We have removed the
line_item_idparameter from the GET accounts/:account_id/promoted_tweets endpoint, which we previously marked as deprecated. (Note: the
line_item_idsparameter is not affected.)
- Creating website cards with 5:2 images is no longer supported.
- We have removed the
display_propertiesparameter from the PUT accounts/:account_id/promoted_tweets endpoint.
- As a result of the previous point, it is no longer possible to update (PUT) promoted_tweets entities.
data_typeresponse attribute is no longer be returned.
For additional details, please see our versions page.
The existing documentation has been updated to reflect the v2 changes.
To see v1-specific documentation, add a
reference/ and the method name. For example, to see the v1 campaign create documentation, visit https://dev.twitter.com/ads/reference/1/post/accounts/account_id/campaigns.
Twitter Ads API Team