Ads API Version 2

announcements

#1

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,
2018
January 10, 2018, v1 of the Ads API will be turned off.

Scheduled Tweets

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.

Draft Campaigns

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 campaigns and line_items which takes three possible values: ACTIVE, DRAFT, and PAUSED. To simplify logic around the various states these entities can exist in, we’ve removed the paused parameter.

### 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.

Other changes

In addition to these new features, we’re including a number of minor changes, listed below.

New

  • The new with_total_count parameter will be available for all index endpoints (e.g., GET accounts/:account_id/campaigns).
  • The new entity_status parameter (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_uri parameter 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_url when 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 card_uri.

Changed

Removed

  • The paused parameter is no longer accepted nor returned in the response. To pause campaigns or line items, use the entity_status parameter.
  • We have removed the line_item_id parameter from the GET accounts/:account_id/promoted_tweets endpoint, which we previously marked as deprecated. (Note: the line_item_ids parameter is not affected.)
  • Creating website cards with 5:2 images is no longer supported.
  • We have removed the display_properties parameter 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.
  • The data_type response attribute is no longer be returned.

Docs

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 /1/ between 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


2017年9月:AdsAPI関連アップデートまとめ
Card_URI Response attribute showing as an invalid url format
Ads API Version 3
Error when trying to get data from API
What is different between Scheduled Promoted Tweets and Promoted Tweets?
Multiple age_buckets set via API will show warning in twitter UI
キャンペーン画面にある「ステータス」フィルターについて
Announcement: Versioning strategy
#2

#3

#4

The card_uri parameter has now added to the POST accounts/:account_id/scheduled_tweets and PUT accounts/:account_id/scheduled_tweets/:scheduled_tweet_id endpoints.


#5

We’ve taken the first step in migrating website cards to support card_uri. We now return both preview_url and card_uri for newly created cards*.

$ twurl -X POST -H ads-api.twitter.com "/2/accounts/18ce54d4x5t/cards/website?image_media_id=915245686660018178&name=card URI&website_title=DTC&website_url=https://developer.twitter.com"
{
  "data": {
    "name": "card URI",
    "image_display_height": "100",
    "image": "https://pbs.twimg.com/ad_img/915245686660018178/J6O9qp4P?format=jpg&name=orig",
    "preview_url": "https://cards.twitter.com/cards/18ce54d4x5t/4v9fc",
    "website_display_url": "developer.twitter.com",
    "id": "4v9fc",
    "account_id": "18ce54d4x5t",
    "website_dest_url": "https://developer.twitter.com",
    "created_at": "2017-10-03T16:03:16Z",
    "image_display_width": "191",
    "website_title": "DTC",
    "card_uri": "card://915245880013234177",
    "website_url": "https://developer.twitter.com",
    "updated_at": "2017-10-03T16:03:16Z",
    "deleted": false,
    "card_type": "WEBSITE"
  },
  "request": {
    "params": {
      "name": "card URI",
      "image_display_height": "100",
      "image": "https://pbs.twimg.com/ad_img/915245686660018178/J6O9qp4P?format=jpg&name=orig",
      "website_display_url": "developer.twitter.com",
      "account_id": "18ce54d4x5t",
      "website_dest_url": "https://developer.twitter.com",
      "image_display_width": "191",
      "website_title": "DTC",
      "website_url": "https://developer.twitter.com",
      "card_type": "WEBSITE"
    }
  }
}

As a reminder, to use the card URI value, use the card_uri parameter with either the POST accounts/:account_id/tweet or the POST statuses/update endpoint. It is still possible to use preview_url by appending the URL to the Tweet text.

* Even if the website card is created using v1. However, the card_uri attribute is only rendered when using v2.


Card_URI Response attribute showing as an invalid url format
Card_URI Response attribute showing as an invalid url format
#6

Cross-posting here for visibility


#7

Version 1 of the Ads API will be retired—no longer available—on January 16, 2018. Please ensure that you have migrated before this end-of-life date.


#8

Version 1 of the Ads API has now been retired.

$ twurl -H ads-api.twitter.com "/1/accounts/18ce54d4x5t"
{
  "errors": [
    {
      "code": "INVALID",
      "message": "Version 1.0 is not available."
    }
  ],
  "request": {
    "params": {}
  }
}