Using the API

This section includes general information on the Marketing APIs, access, versioning, and more. The main use cases for the Marketing API are:

Marketing API Basics

Access and Authentication

Marketing API has two access tiers: Dev Mode and Standard Access. Each level of access has certain restrictions. Learn how to set up your dev environment and obtain an access token.

Ad Campaign Structure

Facebook's campaign structure has 3 levels: campaign, ad set and ad. Learn more about each one, and understand campaign objectives.

Quickstart

Learn basics steps to manage ad campaigns with the Facebook Marketing API: from Create campaign to Book Ad.

Best Practices

General best practices for API use. Includes: Rate Limiting, Async Requests, Batch Requests, Storing and retrieving objects, Error codes, and eTags.

Validation

Validation on the Marketing API occurs on a variety of objects, and between different objects.

Versioning

Facebook's Platform has a core and extended versioning model. Learn more about upcoming changes and deprecations using our versioning and migration systems. See Version Schedules, Migrations, and Changelog.

App Review

To use the Marketing API, your app must undergo App Review. See Businesses Building Tools for Other Businesses, Building Tools with Marketing API, and Sample App Review Submission.

Graph API

Graph API is the REST-based foundation for Marketing API. Learn how to make CRUD operations, handle errors, and debug your code.


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.

Webhooks for Ad Accounts

You can get real-time notifications when your ads change. To do this, subscribe at the ad account level and get notifications for all the ads in the account.

To set up Webhooks for Ad Accounts:

  1. Set up your endpoint and configure the Webhooks. These are the same steps that you use to set up Webhooks for Facebook Pages.
  2. Subscribe your app under your ad account.

Set up Endpoint and Webhooks

Follow our Webhooks Getting Started guide to create your endpoint and configure your Webhooks. When you configure your webhooks, make sure to choose Ad Account and subscribe to one or more ad account fields below:

Field Description

with_issues_ad_objects

Notifies you when a campaign, ad set or ad under the ad account receives the WITH_ISSUES status.

in_process_ad_objects

Notifies you when a campaign, ad set, or ad exits the IN_PROCESS status.

Subscribe your App

At this point you need to subscribe your app to webhook notifications for the ad account. We only send notifications when your webhooks configured-app is subscribed under the ad account, and when the app has permission to edit the ad account. To subscribe your app, have your app send a POST request subscribed_apps for the ad account:

curl -i -X POST \
  -d "access_token=<ACCESS_TOKEN>" \
  "https://graph.facebook.com/<VERSION>/act_<AD_ACCOUNT_ID>/subscribed_apps?app_id=<APP_ID>"

On success, you see this response:

{"success": "true"}

To see which app's are subscribed for your ad account has subscribed, send a GET:

curl -i -X GET \
  -d "access_token=<ACCESS_TOKEN>" \
  "https://graph.facebook.com/<VERSION>/act_<AD_ACCOUNT_ID>/subscribed_apps"

On success you see information on the subscribed app:

{
 "data": [
 { 
"name": "<APP_NAME>", 
"id": "<APP_ID>" } ]
}

To delete a subscription for an app, send a DELETE request:

On success, you see this response:

{"success": "true"}

Subscribe with Graph API Explorer

If you don't want to subscribe your app with the API, you can easily do it with Graph API Explorer.

Replace the me?fields=id,name query with act_AD_ACCOUNT_ID/subscribed_apps. It will subscribe the app you use to send the POST request in Graph Explorer. Or you can subscribe another app by adding subscribed_apps as an input parameter and the app id. Note that your app must have permission to edit the ad account in order to successfully subscribe.

[
  {
    "object": "ad_account",
    "entry": [
      {
        "id": "0",
        "time": 1568132516,
        "changes": [
          {
            "field": "with_issues_ad_objects",
            "value": {
              "id": "111111111111",
              "level": "AD",
              "error_code": "567",
              "error_summary": "error summary",
              "error_message": "error message"
            }
          }
        ]
      }
    ]
  }
]