Ads API Version 4

announcements

#1

Ads API Version 4

Version 4 of the Ads API is launching today, August 28, 2018.

This release includes improvements to our Audiences product, including a new API interface powered by a more robust audience processing backend. Version 4 also includes a set of endpoints for managing user, account, and tax settings. In addition, the accounts/:account_id/videos endpoints are being deprecated. This release also includes a few minor parameter and and response name changes.

As with version 3, we are providing a 6 month transition period. On 2019-02-28, version 3 of the Ads API will no longer be available. We encourage all partners to migrate to the latest version of the API as soon as possible to avoid any service disruptions. See our Versions page for details on our versioning strategy.

New

Audience API

The new Audiences API is built on our new audience processing backend that provides enhanced robustness and reliability. This new endpoint will allow partners to provide multiple user identifier types for a single user, which means that we are able to use additional signals for matching. Reference documentation for the new Audience endpoint can be found here. We plan to continue to release updates and improvements to this product throughout the rest of year.

The following endpoints will no longer be available in v4 due to redundant functionality (they will still work in v3 and will be fully sunset when v3 is no longer available):

  • TON Upload:
    • GET accounts/:account_id/tailored_audience_changes
    • GET accounts/:account_id/tailored_audience_changes/:tailored_audience_change_id
    • POST accounts/:account_id/tailored_audience_changes
    • PUT accounts/:account_id/tailored_audiences/global_opt_out
  • Real Time Audiences:
    • POST tailored_audience_memberships

Finally, the list_type parameter will be removed from the request and response on all Tailored Audiences endpoints in version 4.

Settings Endpoints

We now provide the ability for account administrators to set and update user, account, and tax settings. User settings correspond to the user-specific contact preferences for a given ads account. Using the PUT accounts/:account_id endpoint, advertisers can now update their account name and industry type. Finally, the tax settings endpoints allow advertisers in countries where a value added tax (VAT) is charged to update information such as the company name, address, VAT ID, and whether the account is owned by the advertiser or by an agency advertising on behalf of an advertiser.

Changed

Universal Lookalike Renames

We’re updating the enum values for the lookalike_expansion parameter on the POST accounts/:account_id/line_items and PUT accounts/:account_it/line_items/:line_item_id endpoints.

v3 v4
NARROW DEFINED
BALANCED EXPANDED

Using country_code everywhere

As part of a larger effort around consistency on the Ads API, we’re renaming the parameters on the following endpoints from app_country_code to country_code.

This does not impact the behavior or accepted values for these parameters and is purely a naming change.

preview_url always null

As promised in the v3 announcement, all existing cards now have a card_uri. As a result, the preview_url value will always be null.

As a reminder, associate a card with a Tweet using its card_uri value. See the following example request.

$ twurl -X POST -H ads-api.twitter.com "/4/accounts/18ce54d4x5t/tweet?text=Version 4&card_uri=card://958225772740714496"

Removed

Video endpoints

The accounts/:account_id/videos endpoints will no longer be available in v4. This endpoint has been made obsolete by the introduction of the Media Library endpoints. See the following usage comparison.

# v3 videos endpoint
$ twurl -H ads-api.twitter.com "/3/accounts/18ce54d4x5t/videos"
# v4 media library endpoint for videos
$ twurl -H ads-api.twitter.com "/4/accounts/18ce54d4x5t/media_library?media_type=VIDEO"

The Media Library endpoints are in full parity with the videos endpoints and also support additional functionality such as the ability to handle images and GIFs. Partners are requested to use the Media Library exclusively for any media management.

as_user_id in Tweet View

The as_user_id parameter available on the GET accounts/:account_id/tweet/preview/:tweet_id endpoint will no longer be accepted. The preview will always be rendered as the Tweet’s author.

Twitter Ads API team


Error while updating tailored audience using tailored_audience_changes api
#2

#3