Accessing the Ads API

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.

Ads API Overview

The following Graph API objects are available:

• adaccount
• adaccountgroup
• adcampaign
• adcreative
• adgroup
• adimage
• aduser

The following Graph API queries are also available:

• Broad Target Categories
• Connection Objects
• Ad Statistics
• Keyword Stats
• Reach Estimate
• Autocomplete Data

The objects and queries are inter-related as depicted in the following diagram.

For information on the overall Graph API architecture, please see:

• Graph API, an introduction to objects on the social graph, e.g. User, and the connections between the objects, e.g. friend relationships
• Authentication, which describes the available OAuth flows

Getting Started

To get started with the Ads API, complete the following steps.

Configure your Facebook Application

To get started, you need to configure some basic settings of a Facebook application.

• Log in to Facebook using the account you'll use to create the application. This must be a real Facebook account, not a business account which can only be used for managing Ads and Pages.
• Go to the App Dashboard and create a new application.
• Note the Application ID provided. You'll use the API Key to call the Ads API and to grant the application permission for your user account (see below).

Using the Ads API with business accounts

Business account users must have a user account. Although business accounts are useful for billing and other purposes, please note the following:

• You need a user account for Ads API access.
• Add the user account to the business account as a general user.

Provide authentication

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:

• App ID: referred to below as YOUR_APP_ID
• App secret (keep this value secret): referred to below as YOUR_APP_SECRET
• Site URL (a redirect URL): referred to below as YOUR_URL

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 ads_management and 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:

http://YOUR_URL?code=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:

• The user’s password changes
• The user revokes permissions

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.

Testing the Ads API

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.

Working with Ads objects on the Graph API

You can access a Graph object’s properties with its unique ID, e.g. for the User object:

• https://graph.facebook.com/UserID

Similarly, accounts and campaigns have unique IDs and you can access specific adAccount and adCampaign objects with URLs like these:

• https://graph.facebook.com/act_adAccountID
• https://graph.facebook.com/adCampaignID

All Graph API objects work in a similar way. After you have an access token, try some calls with the adCampaign object.

Paging the response data

For paging the response data in the Graph API, see How-To: Paging with the Graph API and FQL.

Ads API Best Practices

Keep these best practices in mind as you work with the Ads API.

Create New Ads, Don't Edit Existing Ones

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.

Storing User Information

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.

Watch for Changes in Suggested Bids

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.

Use Batch Requests for improved throughput

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:

• Batch requests blog post.
• Batch requests documentation.
• Batch requests section in Ad Creative documentation.

Check if data has changed between calls using ETags.

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

• ETags blog post.
• ETags documentation.

Use the Power Editor source code

The Power Editor is a HTML 5 based application which uses the Ads API to manage Ads. The source code for the Power Editor is available on GitHub here. Reviewing the source code of the Power is a great way of getting to grips with the Ads API and seeing how an existing application calls the API.

Join the Preferred Marketing Developer Program Facebook Group

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.

References