Using the API

The Marketing API is an HTTP-based API that you can use to programmatically query data, create and manage ads, and perform a wide variety of other tasks. This section covers general information on the Marketing APIs, access, versioning, and more.

Since the API is HTTP-based, it works with any language or software that supports HTTP, including cURL and almost all modern web browsers. The Marketing API is build on top of Facebook's Graph API, so almost all requests should be passed to the graph.facebook.com host URL.

Before You Start

You should get familiar with the Graph API and Facebook's Ad Campaign Structure. Once you are ready to start making calls, you need:

After that, you can get started. Don't forget to check general best practices for using the Marketing API.

Basic Concepts

Concepts you should understand to better use the Marketing API:

Access

There are two access tiers to the API: Dev Mode and Standard Access. Each level of access has certain restrictions.

Authentication

Learn how to get and store the access token you need for your API calls.

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 specific instructions for Businesses Building Tools for Other Businesses and Building Tools with Marketing API. We provide a Sample App Review Submission to guide through the process.

Permissions

There are two main ads permissions: ads_management and ads_read. Permissions should be grated to the app you are using to make your calls. Permissions can be requested during the app review process.

Async and Batch Requests

Use asynchronous requests to create ads and send numerous ads requests without having to block. The most efficient way to manage ads is via batched requests.

Storing Objects

Learn to read and manage the status for ad campaigns, ad sets, and ads.

Error Codes

You may see error codes while using the API. Use this as a reference to learn more about each error code.

Post-Processing

Understand the post processing phase after a request is received by Facebook.

Advanced Use Cases

Webhooks

Get real-time notifications when your ads change by creating a webhook for your ad account.