Ads API Version 3
Today we are releasing version 3 of the Ads API.
This release includes our new Audience Intelligence product, access to the Media Library, and improved card workflows. We are also announcing the deprecation of the PUT accounts/:account_id/targeting_criteria endpoint. Finally, version 3 includes a few minor parameter and response changes and a lower batch size limit.
As with version 2, we are giving partners 6 months to transition. On 2018-08-01, v2 of the Ads API will be shut off. We encourage all partners and developers to migrate to v3 as soon as possible. See our Versions page for details on our versioning strategy.
Audience Intelligence
Audience Intelligence delivers real-time insights into the top hashtags, @handles, and events most relevant to a given Twitter audience. For example, enter Male 18-34 in the US and you’ll see #nintendoswitch, #cardinal, and @ricegum trending amongst this audience.
The Audience Intelligence endpoints will provide the following functionality:
- Given an input audience, retrieve the top relevant hashtags, @handles and events.
- Given an input audience, retrieve key demographic information (such as age, gender, and household income).
- Given a keyword, retrieve the Tweet volume time series
Media Library
The Media Library provides the ability to manage images, GIFs, and videos for ads accounts. These media objects can be used in Tweets and to create cards. They can also be reused in multiple creatives, eliminating the need to upload the same asset multiple times.
Objects in the library are identified by a media_key. Media keys are string values in the following format: 13_875943225764098048, for example. In the Ads API, we are moving toward using media keys for all media.
Improved card workflow
All of our cards endpoints now support media keys. This enables objects in the Media Library to be used to create or update cards.
In addition, we’re introducing two new endpoints for retrieving card details. These endpoints can be used to look up cards used in Tweets or Scheduled Tweets, for example, by specifying either the card_uri or id. Previously, this was not possible.
Other changes
In addition to these new features, we’re including the following changes to version 3.
New
Changed
- The maximum targeting criteria batch size is now 500.
- The
card_uri and preview_url response attributes are now mutually exclusive. When a card has a card_uri the preview_url will be null. When a card does not have a card_uri, only the preview_url will be returned.
- We are continuing to migrate all cards to use
card_uri:
- All cards created as of 2018-01-29 will have a
card_uri.
- By version 4, all existing cards will have a
card_uri.
- It is no longer possible to create cards with 5:2 images. While existing 5:2 image-based cards will still work, we encourage partners to switch to using the higher-performing 1.91:1 or 1:1 aspect ratios (where supported).
Removed
- The PUT accounts/:account_id/targeting_criteria endpoint is no longer available. We’ve decided to make this change because the replace behavior with this endpoint caused advertiser confusion and it was not consistent with our other PUT endpoints that update a single resource at a time. Instead, partners should use the POST batch/accounts/:account_id/targeting_criteria endpoint, which provides greater flexibility including the ability to both add and remove targeting in a single request.
- The
paused response attribute is no longer returned for funding instruments. Instead, look to the entity_status response attribute to determine whether or not a funding instrument is paused. In addition, because paused and cancelled correspond to the same value, cancelled is no longer returned in the response, either.
- We have removed the
card_id parameter from the GET accounts/:account_id/tweet/preview endpoint.
- Because it is not possible to retrieve deleted Scheduled Tweets, the
with_deleted parameter is no longer supported.
- The
draft_only parameter has been removed from the following endpoints as these entities can never be in a draft state:
Docs
The existing reference documentation has been updated to reflect the v3 changes.
We are excited to see how partners innovate as we continue to deliver new products and features. Please reach out to us with any questions or feedback.
Twitter Ads API Team
V2 notes
Both Video Website Cards and Scheduled Tweets are now out of beta. See this thread for the changes we’ve made to Scheduled Tweets since launch. This includes the ability to generate HTML previews for Scheduled Tweets.
