The Ads API is a restricted platform which may only be accessed by whitelisted Apps. You can learn more about the program and apply online. You need to apply separately for each app.
The following Graph API objects are available:
The following Graph API queries are also available:
The objects and queries are inter-related as depicted in the following diagram.
For information on the overall Graph API architecture, please see:
To get started with the Ads API, complete the following steps.
To get started, you need to configure some basic settings of a Facebook application.
Business account users must have a user account. Although business accounts are useful for billing and other purposes, please note the following:
For an app to do ad management, a user (including an app developer) must give the app permission. This permission is called the
ads_management extended permission.
An Ads API app is like other Facebook apps, although the Ads API is built on the Graph API. Therefore, please review Facebook for websites and the entire authentication guide to become familiar with the Facebook platform. Please also note the following values from your app summary, which are referred to in the examples below:
Prompt the user for extended permission
To enable your app to manage ads for a user, you use the scope parameter to prompt the user for the extended permission of
ads_management. Also prompt the user for the extended permission of
offline_access if your app makes API calls while the user isn’t logged into your app. For token expiration, see the authentication guide.
The following example uses the scope parameter to prompt the user for
offline_access. Access is granted when the user clicks the Allow button:
https://www.facebook.com/dialog/oauth? client_id=YOUR_APP_ID&redirect_uri=YOUR_URL& scope=ads_management,offline_access
Obtain the access token
If the user clicks the Allow button when you prompt for the extended permissions, the user is redirected to a URL that contains the value of the redirect_uri parameter and an authorization code:
Build a URL that includes the endpoint for getting a token, your app ID, your site URL, your app secret, and the authorization code you just received. The URL will be similar to the following:
https://graph.facebook.com/oauth/access_token? client_id=YOUR_APP_ID&redirect_uri=YOUR_URL& client_secret=YOUR_APP_SECRET&code=AUTHORIZATION_CODE
The response should contain the access token for the user. For additional information, see the authentication guide.
Store the access token
The token should be stored in your database for subsequent API calls.
You should regularly check for validity of the token, and if necessary prompt the user for permission. Even a token that works for offline access can become invalid in a few cases including the following:
As the token can be reset anytime, we request that the developers who use persistent tokens always account for an invalidated token. When a user starts your web application, check for the validity of the token. If necessary, prompt the user for permissions. If this is not possible for your application (e.g., API calls are not based on a user-interface flow, or there’s as script failure), a different way to prompt the user may be necessary. For example, your app could email instructions to the user.
Once Facebook has whitelisted your application, you can test the API calls using the Graph API Explorer tool. The Graph API Explorer enables you to test almost any query you would like to make to the Ads API; read the blog post for all the functionality provided. Please be sure to select your whitelisted application from the "Application" drop down as well as the
ads_management permission in the pop-up dialog (under extended permissions) when generating your access token.
The API is live, so Facebook does not provide a sandbox where you can test your code.
You can access a Graph object’s properties with its unique ID, e.g. for the
Similarly, accounts and campaigns have unique IDs and you can access specific
adCampaign objects with URLs like these:
All Graph API objects work in a similar way. After you have an access token, try some calls with the
For paging the response data in the Graph API, see How-To: Paging with the Graph API and FQL.
Keep these best practices in mind as you work with the Ads API.
You shouldn't change the targeting, title, or body for an ad for purposes of using the ad in slightly modified form elsewhere; you should create a new ad.
Facebook recommends storing user IDs, session keys, and the Ads Account ID in a manner that makes it easy to programmatically access them and keep them together. This is important because any calls made with an account ID belonging to one user and the session key for another user will fail with a permissions error.
It's a good idea to run frequent reports on your campaigns, as suggested bids change dynamically in response to bidding by competitors using similar targeting. Bid suggestions get updated within a few hours, depending upon the bidding of competitors.
Batch requests allow you to make multiple requests to the Graph API using a single http call. For more information on Graph API Batch Requests please review the following:
ETags allow you to quickly check if the response to a Graph API request has changed since you last made it. For more information on ETags please review the following
If your company has been whitelisted to use the Ads API you may request access to the Preferred Marketing Developer Program group on Facebook. This group is an excellent source of news and help on using the Ads API.
Using batch requests on the Ads API.
ETags support on the Facebook Platform can help you reduce bandwidth consumption and client-side overhead by suppressing output when making Graph API calls.
How to create offsite pixels.
Cost Per Action Ads
Ads API supports all of the currencies supported by Ad Accounts. Those currencies are are follows:
How to use a custom image thumbnail for link post ads
Homepage Ads via API
Intro to Action Spec
Intro to Sponsored Stories
API documentation for mobile app install ads
Real Time Bidded Exchange protocol
RTB Exchange protocol thrift file
Unpublished Page Posts - Creation & Promotion
Starting with Action Specs
An overview of Conversion Specs for the Ads API.
Description of creative specs.
Overview of Targeting Specs
Overview of tracking specs for Ads API
How to target ad groups at users based on actions taken on the Open Graph.
How to create custom advertising audiences.
Detailing usage of data partner categories with ad targeting.
Using ZIP codes for location based ad targeting
How to use the Action Estimate method to query expected activity of an action spec.
Overview on using the Ads API Preview feature.
Details about Stats in the Ads API.
You can retrieve several types of autocomplete data for ad targeting.
An object representing the broad category targeting for an ad account.
An object representing the Facebook objects the user is connected to.
Keyword stats for an adgroup
An object representing the reach estimate for a specific targeting.
Object representing the human-readable description of a targeting spec
An ad account
An ad account group
An ad campaign
An ad creative
An ad group
Using ad images on the ads API.
Details about users in the Ads API.