Today, we introduce Version 8 of the Twitter Ads API, designed to introduce new Tailored Audiences functionality, increase feature parity with ads.twitter.com, and improve your developer experience.
As with previous versions, there will be a 6 month transition period to migrate to v8. On 2021-03-02 version 7 of the Ads API will no longer be available. We encourage all developers to migrate to the latest version of the API as soon as possible to avoid any service disruptions.
New
Tailored Audiences PUT endpoint
Engineering effort: Minimal
The Tailored Audiences PUT endpoint allows a partner to edit both the name and description of their Tailored Audiences. Note that duplicated names for Tailored Audiences are not allowed. See ‘Tailored Audiences create behavior’ below for further details.
Targeted Audiences
Engineering effort: Medium
The targeted audiences endpoint adds functionality to retrieve a list of active or inactive line items that target a given Tailored Audience.
Changed
Updated product naming
Engineering effort: Minimal
Due to an update to the objective naming convention on ads.twitter.com we have renamed a few objective enums to bring these in line with the Ads UI. The following table provides details on which values have been renamed as well as the old and new values:
| Old |
New |
TWEET_ENGAGEMENTS |
ENGAGEMENTS |
VIDEO_VIEWS_PREROLL |
PREROLL_VIEWS |
AWARENESS |
REACH |
Targeting Criteria consistency
Engineering effort: Minimal
In order to provide a better developer experience, we’ve aligned the targeting criteria to the create and update endpoints for the targeting_type=TAILORED_AUDIENCE to enforce an operator_type as a required parameter.
Frequency Cap validation
Engineering effort: Minimal
As of v8 we will be enforcing the account feature check at campaign creation for the REACH_FREQUENCY_CAP when the duration_in_days or frequency_cap parameters are set on the campaign. Previously, this account feature check would happen when the line item is created.
Tailored Audiences owner_account_id
Engineering effort: Minimal
The Tailored Audiences endpoint will replace the is_owner field with an owner_account_id which will be set to the Ads account ID of the account which owns the audience for shared audiences. This value will be set to the current account ID if the current account owns the given Tailored Audience.
Tailored Audiences create behavior
Engineering effort: Minimal
Previously, when creating a Tailored Audience with a name of an existing Tailored Audience, the Ads API would return the id of the existing audience. In this version of the Ads API,a new validation rule will prevent duplicated Tailored Audiences name from being created and will result in an error.
{
"errors": [
{
"code": "DUPLICATE_DETECTED",
"message": "An audience with this name already exists. Please use a different name."
}
],
"request": {
"params": {}
}
}
Removed
Analytics Fields
Engineering effort: Minimal
As part of an effort to clean up unused fields, the following fields from the analytics API response have been removed:
-
video_mrc_views: This field is always set to the value of video_total_views
Twitter Ads API team