Version 5.0

Released October 29, 2019 | Available until February 3rd, 2022


This change applies to v5.0+.

The following endpoints are deprecated:

Marketing API

Released October 29, 2019 | Available Until Indefinitely

Marketing API v5.0. was originally set to deprecate on 5/19/20; however, because of the COVID-19 impact, we have extended the migration end date from 5/19/2020 to indefinitely, until further notice.

New Features

Ads Volume

We added /{ad-account-ID}/ads_volume so you can determine the volume of ads for your ad accounts. These ads will count against the ads limit per Page that we will enact in mid 2020. Query the number of ads running or in review for a given ad account. For more details see Ad Account, Reference.

Ads Library, Filters

Search all ads stored in the Ads Library. Search data for all active and inactive ads related to politics or issues of importance. We now offer filters so it is easier for you to find certain types of ads by bylines, impression_condition and publisher_platforms. For details see Ads Library API.

Breaking Changes

Special Ad Category

As announced earlier this year, advertisers running ads in Marketing API will be required to identify new ad campaigns that offer housing, employment, or credit opportunities. Marketing API v5.0 includes a Special Ad Category field, special_ad_category, for advertisers to indicate during campaign creation calls if their ads offer housing employment, or credit opportunities. If using Marketing API v5.0 or above, the Special Ad Category field is required for all ads, whether offering housing, employment or credit opportunities or not. See Special Ad Category.

Ads Management

  • Changed requirements to create an ad campaign. You must specify special_ad_category. For details, see Marketing API, Special Ad Category. Affected endpoints: POST {ad-account-ID}/campaign.

  • Deprecated the {ad-account-ID}/user_role field on the ad account node. Instead you should use the user_tasks field. See Business Manager API, Add People to Accounts. This impacts: GET {ad-account-ID}.

  • Deprecated the 10-Second video views optimization option for ads. If you try to create or copy and ad set with this setting, it fails as of v5.0. This impacts: POST {ad-account-ID}/ad-sets, POST {campaign-ID}/copies, POST {ad-set-ID}/copies.

  • Changed operation_status for audiences. If you have not used an audience in an ad's targeting for at least 30 days or you created the audience over 90 days ago and never used it, we consider it out of date instead of normal. We will only start updating this audience once you publish your ad. See Custom Audience, Reference.

  • Deprecated legacy APIs for creating sponsored messages in Messenger. This impacts POST {ad-account-ID}/sponsored_message_ads.

Lead Ads

  • Deprecated the endpoint leadgen_forms to query lead forms for a given ad account. Affected endpoints: GET {ad-account-ID}/leadgen_forms, GET {ad-account-ID}/?fields=leadgen_forms.

  • Deprecated fields to read information on the person who created a lead form. This includes /creator, creator_ID. Affected endpoints: GET {lead-form-ID}, GET {page-ID}/leadgen_forms.

  • Deprecated the post field in the lead endpoint. Affected endpoints: GET {lead-ID}, GET {form-ID}/leads, and GET {ad-ID}/leads.

  • Deprecate several legacy fields in the lead form node including cusomized_tcpa_content, tcpa_compliance, extra_details, messenger_welcome_message, and qualifiers. Affected endpoints include: GET {lead-form-ID}, GET {page-ID}/leadgen_forms.

  • Deprecated several legacy Lead Ads fields and edges in page node. This includes leadgen_has_crm_integration, leadgen_has_fat_ping_crm_integration, leadgen_context_cards, leadgen_legal_content, leadgen_conditional_questions_group, leadgen_whitelisted_users. This impacts: GET {page-ID}.

  • Deprecated the field leadgen_export_csv_url that you use to get a URL to download leads in a .csv file. Affected endpoints include: GET {lead-form-ID} and GET {page-ID}/leadgen_forms.

Ads Insights and Reporting

  • Deprecated 10-second video view metrics. In 4.0 we replaced these with 15-second video view metrics, which are also known as ThruPlay metrics. We also deprecated Lead Ads-related metrics. For more information, see Ads Help Center, About Metrics being Removed. This impacts the following endpoints:

    • GET {ad-account-ID}/insights

    • GET {ad-campaign-ID}/insights

    • GET {ad-set-ID}/insights

    • GET {ad-ID}/insights

    • GET {ad-action-stats-ID}

    Note all deprecated metrics and replacement metrics, if available:

    Deprecated Replacement


    ThruPlays, or video_thruplay_watched_actions:video_view




    Cost per ThruPlay, or cost_per_thruplay:video_view


    On-Facebook Leads, or onsite_conversion.lead_grouped


    Cost per Lead, or cost_per_action_type:lead


    quality_ranking, engagement_rate_ranking, and conversion_rate_ranking

  • If you are using Ads Rules Engine with any of these deprecated metrics, the rules will no longer work.

  • Deprecated the Ads Keywords Stats API as of v5.0. Earlier public versions such as v4.0 still have this available. This impacts: GET {ad_ID}/keywordstats.

Upgrading to Marketing API v5.0

A few reminders for our developer community:


New Features

These changes apply to all versions.


These changes apply to various versions.

The following endpoints are deprecated for versions v5.0+. They supported plain text only private replies. Use the New Private Replies instead.

The following endpoints wil be deprecated for all versions on March 4th, 2020.


Error Messages

This change applies to all versions.

Endpoints that require manage_pages or Page Public Content Access and return an error code 10 when both permissions are missing will now return a new error message:

This endpoint requires the 'manage_pages' permission or the 'Page Public Content Access' feature. Refer to and for details.

Page Public Content Access

This change applies to v5.0+

Requests made to endpoints that require the Page Public Content Access feature must be made with either an App Access Token or include the app's App Secret. If the calling app has been granted the manage_pages permission however, an app access token or app secret is not required.