Using the API

General information on the Marketing APIs, access, versioning and more. The main use cases for the Marketing API are ads insights, audience management, and ads management:

Learn the basic structure and usage of the Marketing API.

  • Access and Authentication - Marketing API has two access tiers: Dev Mode and Standard Access. Each level of access has certain restrictions, described in this article. Set up your dev environment and obtain an access token.
  • Testing - Learn how to test the Marketing API.
  • Graph API - REST-based foundation for Marketing API, how to make all CRUD operations, error handling, and debugging tips.
  • Object Structure - Campaigns, ad sets, ads and ad creatives.

App Review

To use the Marketing API, your app must undergo App Review and, in most cases, include the manage_pages login permission in your submission. Based on how you will use the API, you may have to complete additional steps, described in the following scenarios.

Businesses Building Tools for Other Businesses

If you are a business building tools for other businesses, you will need to agree to supplemental terms and a Technology Provider amendment, unless you are only building ads-related tools with Marketing API. If you are creating solutions for advertising on Facebook, see Building Tools with Marketing API.

In addition, if you are using Facebook's tools or data to provide service to other businesses, we will require you to share with Facebook who your customers are. We will announce a solution to help you do this by Aug 1st, 2018. If your customers access large scale user data through your tool, we may have additional requirements for them as well.

Building Tools with Marketing API

If your app uses any of the following functionality in Marketing API, your app must be reviewed by Facebook, you must go through business verification, and you must agree to our supplemental terms. Use of this API does not require signing Tech Provider Amendment or extended platform product terms.

Versioning

Learn more about upcoming changes and deprecations using our versioning and migration systems.

  • Versioning Overview - Facebook's Marketing API supports versioning cycles for app development stability. Learn more here.
  • Migrations - Future and past Facebook Platform Migrations. Migrations are used to apply changes across all existing versions.
  • Changelog - This changelog covers what's changed in Facebook's Marketing API. These changes include Facebook's server-side APIs and SDKs.

Post-Processing for Ad Creation and Edits

Prior to v4.0, ads buying could cause system timeout, out of memory errors or delays. To scale the system, we decoupled logic that requires significant computation and that causes transient errors to an separate workflow called post-processing. Now when you create or edits ads, it is more resilient to transient errors. The process looks like this:

To represent a post processing phase after a request is received, we introduce the ads run status IN-PROCESS in v4.0. This new status applies to:

  • {campaign_ID},
  • {ad_set_ID},
  • {ad_ID} and
  • {ad_creative_ID}.

For campaigns, ad sets and ads, this impacts:

Field v4.0 and above Below v4.0

effective_status (enum {ACTIVE, PAUSED, DELETED, PENDING_REVIEW, DISAPPROVED, PREAPPROVED, PENDING_BILLING_INFO, CAMPAIGN_PAUSED, ARCHIVED, ADSET_PAUSED, WITH_ISSUES, IN_PROCESS})

IN_PROCESS

For campaigns or ad sets: configured_status or status. for ads: pending_review.

configured_status enum {ACTIVE, PAUSED, DELETED, ARCHIVED}

No change

No change

status (enum {ACTIVE, PAUSED, DELETED, ARCHIVED})

No change

No change

The post-processing phase appears in effective_status for campaigns, ad sets and ada, and in the status field for ad creatives. For example, you can query the status of your object at /creative_id?fields=status. If it is in the post-processing phase, you see:

{
 "status": "IN-PROCESS", 
 "id": "<creative_id>"
}   

If your ad creative successfully passes post-processing, you see:

{ 
"status": "ACTIVE", 
"id": "<creative_id>"
}  

If post-processing fails, we set your object to WITH_ISSUES and provide an error in issues_info. For example, at creative_ID?fields=status, issues_info:

{ 
"status": "WITH_ISSUES", 
"issues_info": [ 
{ 
"level": "CREATIVE", 
"error_code": 1815869, 
"error_summary": "Ad post is not available", 
"error_message": "The Facebook post associated with your ad is not available. It may have been removed, or you may not have permission to view it." } 
], 
"id": "<creative_id>"
}

When ad object is IN_PROCESS, you can still make regular updates to the object and its children.