Back to News for Developers

Announcing Ads API v2.2

October 30, 2014ByChristine Lu

Today, we're delighted to announce the first official version of the Ads API : version 2.2. We're also releasing updated PHP and Python SDKs which work with v2.2.

Ads API Versioning

For Ads API developers, versioning means increased control over how you opt into new Ads API features. Rather than changing a migration setting in your app dashboard, you can now control the behavior by specifying the version number in your client codebase.

Our advertising products continue to evolve at fast pace. To ensure developers continue to take advantage of this progress, the Ads API will continue to offer a 90-day breaking change policy. To make this behavior clear, Ads API methods will be removed from a version 90 days after the next version is released.

As v2.2 is the first versioned release for the Ads API, Ads API methods will be removed from v1.0, v2.0 and v2.1 in 90 days time. Developers using the Ads API should update their apps to call v2.2 before January 28, 2015. After that date, all calls to Ads API methods which do not specify v2.2 (including calls which do not specify any version) will result in an error.

Version Path Date Introduced Available Until



October 30th, 2014

At least until January 28th, 2015



October 1st, 2014

January 28th, 2015



October 1st, 2014

January 28th, 2015



October 1st, 2014

January 28th, 2015

non-versioned path


January 28th, 2015

API v2.2 feature highlights

In v2.2, we'll begin:

  • enforcing targeting and bidding on the ad set level
  • deprecating action spec targeting
  • requiring a new field, promoted_object, on the ad set when the objective is website conversions, page likes, offer claims, mobile app install/engagement or canvas app install/engagement.
  • renaming the target_specs field of Reach and Frequency APIs to target_spec to better illustrate what value it accepts. Also adding a new field story_event_type, will be used to specify when an ad set may or may not have video ads and is required when targeting all mobile devices.
  • requiring an app ID when creating a Custom Audience out of FBIDs
  • introducing stability and various improvements to the API by migrating additional endpoints to the Graph API framework

For the full list of changes in this version, see the Ads API v2.2 Changelog and the Ads API v2.2 Upgrade Guide.

For the broader list of changes affecting the rest of the Graph API, see the Graph API v2.2 Changelog.

How to Upgrade to v2.2

To upgrade to v2.2, SDK developers should download our latest PHP and Python Ads API SDKs. Web developers should specify /v2.2/ in your URLs when calling the Graph API.