Version 2.11

Marketing API

Released November 7, 2017 | Available Until Aug 7, 2018 | Blog Post

• New Features
• Breaking Changes
• Deprecations
• Immediate Deprecations

---

New Features

Business Manager API Redesign

We now have a new relationship which represents clients and agencies. In the past we also had no user; we handled all access and invitations to a business and it's assets through bid/userpermissions which caused performance issues. Highlights of the new API include:

• Business-scoped Users - The new user is tied to a particular business and has permissions scoped to this business. Users can manage their profile, permissions, and asset access that is associated with that business.
• Invitations - Invite people to access a business through new endpoints. Check and update the status of user invitations at these endpoints.
• Asset Categories - Split different types of assets into categories and provide separate endpoints for each category. This makes it easier to paginate results when you read assets. It also reduce performance issues if you manage thousands of assets for a business. For the redesign we added several new endpoints.

To access users on business:

• BUSINESS_ID/business_users
• BUSINESS_ID/system_users
• BUSINESS_ID/pending_users

To access assets assigned to users:

• BUSINESS_USER_ID/assigned_pages
• BUSINESS_USER_ID/assigned_ad_accounts
• BUSINESS_USER_ID/assigned_product_catalogs
• SYSTEM_USER_ID/assigned_pages
• SYSTEM_USER_ID/assigned_ad_accounts
• SYSTEM_USER_ID/assigned_product_catalogs
• PENDING_USER_ID/assigned_pages
• PENDING_USER_ID/assigned_ad_accounts
• PENDING_USER_ID/assigned_product_catalogs

To access business pages:

• BUSINESS_ID/owned_pages - To get a list of Pages the business owns
• BUSINESS_ID/client_pages - To get a list of Pages of the clients of the business
• BUSINESS_ID/pending_owned_pages - To get a list of Pages the business owns that are pending approval
• BUSINESS_ID/pending_client_pages - To get a list of Pages belonging to clients of a business that are pending approval

To access business ad accounts:

• BUSINESS_ID/owned_ad_accounts - To get a list of ad accounts the business owns
• BUSINESS_ID/client_ad_accounts - To get a list of ad accounts of the clients of the business
• BUSINESS_ID/pending_owned_ad_accounts - To get a list of ad accounts the business owns that are pending approval
• BUSINESS_ID/pending_client_ad_accounts - To get a list of ad accounts of the clients of the business that are pending approval

To access business product catalogs

• BUSINESS_ID/owned_product_catalogs - To get a list of product catalogs the business owns
• BUSINESS_ID/client_product_catalogs - To get a list of product catalogs belonging to clients of the business

To access business apps:

• BUSINESS_ID/owned_apps - To get a list of apps the business owns
• BUSINESS_ID/client_apps - To get a list of apps of the clients of the business
• BUSINESS_ID/pending_client_apps - To get a list of apps belonging to clients of a business that are pending approval

For more information, see Business Manager, API, Business Manager, System User, Business Asset Management API, and Business Manager API, Best Practices.

Carousel Ads, Real-time Location

You can now create a carousel ad with an attachment that shows a real-time location. Added the options type=REALTIME and location_source_id = PAGE_ID in place_data for AD_CREATIVE_ID/object_story_spec. This is available at object_story_spec field in:

• POST /AD_ACCOUNT_ID/adcreatives
• GET CREATIVE_ID

Store Visits, Target Geographical Locations

You can now target geographic areas beyond a radius around a store location. We added geo_locations parameter in the targeting_specs field when you create an ad set with store visits as your objective. Under limited availability, see your Facebook Representative to access. See Store Visits Objective

• POST AD_ACCOUNT_ID/adsets has the new option.
• Supports all geographical areas in Targeting Specs, Locations except targeting by country_groups and targeting the travel_in location type.
• Creating ads with STORE_VISITS objective available on a limited basis, see Store Visits

Ad Set, Destination Types

This reflects the type of destination an ad links to; in other words, where someone goes when they click on an ad or call-to-action in an ad. This provides a consistent destination type for all ads in an ad set, so that ads only contain different types of ad creative. See Ad Set, Destination Type.

• Added destination_type for ad sets
• Available at /ADSET_ID

Key Performance Indicator

Added the new field kpi_type to AD_ACCOUNT_ID/CAMPAIGN_ID which describes the type of key performance indicator you want to track for the campaign or ad objects in the campaign. For see insights data by kpi_type in kpi_results make these calls:

• GET CAMPAIGN_ID/insights
• GET ADSET_ID/insights
• GET AD_ID/insights

For more information, see Ad Campaign, Reference.

---

Breaking Changes

Ads Management

• Invalidate ads targeting right_hand_column - Ads targeting this position with invalid creatives for right_hand_column on AD_ACCOUNT_ID/adsets returns an error. We do not allow right_hand_column-only placement with video, collection, or canvas ads format. For right_hand_column-only placement, you can only use single-image and carousel formats.

• Changed GET VERSION/RF_PREDICTION_ID/pause_periods - To return Array now, not String to enable easier handling.

Business Manager API

• Renamed fields — The admin_system_user field has been renamed to admin, and the system_user field has been renamed to employee. This affects the following edges:

  • /{business-id}/userpermissions
  • /{business-id}/system_users

---

Deprecations

Ads Management

Deprecated optimizations for VIDEO_VIEWS - Campaigns with the VIDEO_VIEWS objective can no longer use CLICKS, IMPRESSIONS, PAGE_ENGAGEMENT, POST_ENGAGEMENT, or REACH as optimization goals:

• Creating ad sets with these optimization goals returns an error.
• Duplicating ad sets with the REACH optimization goal, automatically converts to the VIDEO_VIEWS optimization goal.
• Duplicating ad sets with CLICKS, IMPRESSIONS, PAGE_ENGAGEMENT, or POST_ENGAGEMENT as the optimization goal returns an error. This is because creating or duplicating an ad in an existing ad set tries to reuse any of these optimization goals.

Edges impacted by this change:

• POST ACCOUNT_ID/adsets
• POST AD_ACCOUNT_ID/ads
• POST CAMPAIGN_ID/copies
• POST ADSET_ID/copies
• POST AD_ID/copies

Deprecated reach - As a optimization_goal for the brand awareness objective. Removed for or /adset; it is available for ad recall optimization only. This avoids confusion for anyone using reach as a dedicated objective.

Deprecated the optimization BRAND_AWARENESS - Replaced by AD_RECALL_LIFT. This reflects a new, more efficient, ads delivery model. The new optimization goal supports mixed creative, such as static and video ads in the same ad set and manual bidding. BRAND_AWARENESS is no longer available at:

• POST /ADSET_ID
• GET /ADSET_ID
• POST /AD_ACCOUNT_ID/adsets

Deprecated frequency_cap - Including lifetime_frequency_cap and frequency_cap_reset_period fields on:

• POST AD_ACCOUNT_ID/adsets
• GET /ADSET_ID
• POST /ADSET_ID

Use frequency_control_specs instead.

Deprecated cost-per-action POST_ENGAGEMENT - You can no longer use POST_ENGAGEMENT as a billing_event for this objective. This better aligns ads delivery and measurement. This impacts the endpoint: /AD_SET_ID.

Ads Insights and Measurement

Deprecated video_15_sec_watched_actions on:

• GET AD_ACCOUNT_ID/insights
• GET CAMPAIGN_ID/insights
• GET ADSET_ID/insights
• GET AD_ID/insights
• POST AD_ACCOUNT_ID/insights
• POST CAMPAIGN_ID/insights
• POST ADSET_ID/insights
• POST AD_ID/insights

Deprecated recurrence_value - From Advanced Measurement API. The field was also known under Atlas API as report schedule. We replaced it with recurrence_values. See Advanced Measurement, Report Schedules.

Business Management

Deprecated endpoints for the redesign of Business Manager API:

• BUSINESS_ID/userpermissions
• BUSINESS_ID/business_persona
• business_persona_id

Deprecated endpoints for managing your assets:

• BUSINESS_ID/pages
• BUSINESS_ID/adaccounts
• BUSINESS_ID/product_catalogs
• BUSINESS_ID/apps

To access assets, use BUSINESS_ID/owned_ASSET or BUSINESS_ID/client_ASSET

Deprecated endpoints for managing assets belonging to another business:

• BUSINESS_ID/assigned_ad_accounts
• BUSINESS_ID/assigned_pages
• BUSINESS_ID/assigned_product_catalogs

Instead, use BUSINESS_USER_ID/assigned_ASSET

Immediate Deprecations

These deprecations affect all API versions and will take effect on November 14, 2017.

Event Ads and Link Ads

Deprecated creating and editing Event Ads or Link Ads that are not connected to a valid page. The following format is no longer valid and returns an error.

Signatures that are being deprecated:

• Event Ads
  • Objective: EVENT_RESPONSES
  • Creative fields: body, object_id
• Link Ads
  • Objective: LINK_CLICKS
  • Creative fields: title, body, object_url (image_file or image_hash)

Supported signatures

• Event Ads
  • Objective: EVENT_RESPONSES
  • Creative fields: object_story_id or object_story_spec
• Link Ads
  • Objective: LINK_CLICKS
  • Creative fields: object_story_id or object_story_spec

Existing Event and Link Ads that you created earlier continue to run, but you can't modify the ad's creative or create new ads once this change goes in effect otherwise you receive errors. See Event and Local Ads and Ad, Reference.