Best Practices

General

Recommended procedures and tips to use our API.

Rate Limiting

The Marketing API has it is own rate limiting logic. Learn about rate limits and how to deal with them. See Throttling Errors.

API Errors

List of common error codes returned by the API.

Testing

How to test our API. Learn about Sandbox mode and Graph API Explorer.

Async Requests

How to use asynchronous requests to create ads.

Batch Requests

Batch your API calls for greater efficiency.

Storing and retrieving objects

Campaign, ad set, and ad objects limit the number of each object allowed in an ad account. Manage objects around those limits.

eTags

Optimize your calls to only fetch data when it changed.

Validation

Validation that occurs amongst the ad objects and parameters.

Facebook Policies

Understand the API policies; Facebook has the right to audit your activity anytime.


General

Ad Changes Triggering Ad Reviews

If you make any changes to the following scenarios, your ad will be triggered for review:

  • Any changes to your creative (image, text, link, video, and so on)
  • Any changes to targeting
  • Any changes of optimization goals and billing events may also trigger review

Note: Changes to bid amount, budget, and ad set schedule will not have any effect on the review status.

Additionally, if an ad enters Ad Review with the run status of "Paused", then it will remain Paused upon exiting Ad Review. Otherwise, the ad will be considered Active and ready to deliver.

Pagination

For paging response data, see the Graph API Pagination.

User Information

You should store user IDs, session keys, and the ads account ID so it is 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.

Suggested Bids

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

Make multiple requests to the API with a single call, see:

You can also query for multiple objects by ID as follows:

https://graph.facebook.com/<API_VERSION>?ids=[id1,id2]

To query for a specific field:

https://graph.facebook.com/<API_VERSION>?ids=[id1,id2]&amp;fields=field1,field2

Check Data Changes using ETags

Quickly check if the response to a request has changed since you last made it, see:

Object Archive and Delete Status

Ad objects have two types of delete states: archived and deleted. You can query both archived and delted objects with the object id. However, we do not return deleted objects if you request it from another object's edge.

You can have up to 5000 archived objects at any time. You should move ad objects from archived states to deleted states if you no longer need to retrieve them via edges. To learn how states work and for sample calls see Storing Ad Objects.

Viewing Errors

People make mistakes and try to create ads that are not accepted, Error Codes provide reasons an API call failed. You should share some form of the error to users so they can fix their ads.

Facebook Marketing Developer Community Group

Join Facebook Marketing Developer Community group on Facebook for news and update on for Marketing API. We post items from the Marketing API blog to the group.

Testing

Sandbox mode is a testing environment to read and write Marketing API calls without delivering actual ads. See Sandbox Mode for Developers

Try API calls with Graph API Explorer. You can try any API call you would like to make to the Marketing API, see blog post. Select your app in App, and grant your app ads_management or ads_read permission in extended permissions when you create an access token. Use ads_read if you only need Ads Insights API access for reporting. Use ads_management to read and update ads in an account.

For development and basic access, configure a list of ad accounts your app is able to make API calls for, see account list.

You can use sandbox mode to demonstrate your app for app review. However in sandbox mode you cannot create ads or ad creative. Therefore you should use hard coded ad IDs and ad creative IDs to demonstrate your use of our API for app review.

Basic Criteria

  • Demonstrate value beyond Facebook's core solutions, such as Facebook Ads Manager.

  • Focus on business objectives, such as increase in sales. Facebook business objectives can be found here.

Facebook Policies

Understand the API policies; Facebook has the right to audit your activity anytime:

Be ready to adapt quickly to changes. Most changes are versioned and change windows are 90 days, ongoing.

In Statement of Rights and Responsibilities, you are financially and operationally responsible for your application, its contents, and your use of Facebook Platform and the Ads API. You should manage your app's stability and potential bugs.