Tutorial

Facebook Marketing API - A Practical Introduction

Learn the basics of the Facebook Marketing API with this practical introduction: Create an app, get campaign data and even make changes to your account.

In this tutorial, you will learn the basics of the Facebook Marketing API: getting performance data via the Insights API and making changes to your adsets via the Graph API.

Feel free to follow along via video (sorry for the slight audio/video mismatch) or go at your own pace with the text-only version below.

We designed this tutorial to make it fun for you to play around with Facebook Marketing API. It consists of 11 different exercises through which you will learn the basics. Then, go through the tutorial step by step. Sometimes we introduce a new topic through a specific use case.

I. Create a Facebook App
II. Get an access token for your Facebook App
III. Working with the Marketing API: Objects, edges
IV. Your first Facebook Marketing API Call
V. Get your Facebook ad accounts
VI. Retrieve Facebook performance data (called "insights")
VII. Retrieve campaigns and adsets of an ad account
VIII. Retrieve and change budgets
IX. Retrieve ads of an adset
X. Get an ad's creative and more
XI. Retrieve information with a browser instead of the Graph API Explorer

Please note that this is not an official Marketing API tutorial. For more details on the Marketing API, refer to the official documentation.

I. Create a Facebook App

First, to access Facebook programmatically via the Marketing API, you need to create a Facebook (or should we call it "Meta") app. This will allow you to generate an access token that is your authentication when calling the API. We'll tackle that right after getting our app. After that, there are just a few simple steps, and all you require is an existing Facebook account.

1. Go to developers.facebook.com

2. Log into your Facebook account

3. Go to My Apps —> Create app. Choose Business as an app type.

Meta%20for%20developers%3A%20header%20screenshot

4. Give it a name and contact email.

create%20a%20facebook%20app%3A%20screnshot%20of%20the%20main%20page

5. Click on Create App

6. In the list of products provided by Facebook, choose Marketing API and click on Set Up. After you click, Marketing API will appear on the left side of your app menu.

facebook%20API%20tools%3A%20screenshot

II. Get an access token to access the Facebook Ads API

An access token identifies the user (like an email and password) used to authenticate your API calls. That way, Facebook knows whether you have access to the ad account for which you are requesting data. A user access token is used for precisely this purpose, to prove that you are authorized to look at any data and make any changes you'd usually be able to do via Ads Manager.

There are two ways to get your user access token.

via Developer Tools (quick and easy):

1. Click on Tools under the Marketing API on the left side. Choose Access Token Tool.

2. Select the permissions that you need:
- ads_management (make changes in selected ad accounts)
- ads_read(readout ads data)
- read_insights(read out performance insights)

facebook%20api%20permissions%3A%20screenshot

2. Click on Get Token

via Graph API Explorer (more granular permission management):

1. Go to Tools —> Graph API Explorer

2. Choose the right app on the right side

3. Choose Get User Token on the section User or Page

4. You will be redirected to do the standard Facebook login flow.

5. Add the permissions that you will need. In our case, we choose ads_management and read_ads.

6. Click on Generate Access Token.

generating%20Facebook%20API%20access%20token%3A%20screenshot

Note: Either of these methods will generate a short-lived access token that expires fairly soon. You can follow the official documentation to get a long-lived access token that lasts up to 60 days, or if you know what you are doing, request a System User access token that doesn't expire.

III. Working with the Marketing API: Objects, edges

You will need to understand a few other core concepts to navigate the Facebook Marketing and Graph API successfully.

The goal of this introduction is not just for you to follow along but to understand how you might retrieve other important information via the API or make changes to existing ad objects.

a) Objects

Every element or item with an ID in Facebook Business Manager is an object.

For example:
- Ad Accounts
- Campaigns
- Adsets
- Ads
- Audiences
- etc

We can request more information about an object by calling its ID and adding any fields or connections (called "edges") we want to learn more about. For example, for an adset, we can ask for: (parent) campaign, (child) ads, targeting, start date, daily budget, etc.

Each ID is unique - so there's no way Facebook would mistake an adset id for something else.

We access each object through its unique identifier by simply calling it with the base URL and a / :

graph.facebook.com/v13.0/{object_id}

b) Edges

Edges are "connections" to other related objects. For example, an ad account has a campaigns edge, meaning that we can request the ids of all campaigns located in the ad account. The opposite is true as well - any campaign has an ad account edge as well as adsets and ads edge. In Facebook Marketing API, the edges are called with a / symbol, for example:

graph.facebook.com/v7.0/{object_id}/{edge_that_you_want_to_call}

c) Parameters

Parameters define what data Facebook returns to you (when reading out data) or how and what attributes you are changing (when you create or update an existing object). For our purpose, these are the most important parameters when accessing the Marketing API:

- limit: limits the number of objects pulled when requesting multiple items via an edge

https://graph.facebook.com/v13.0/{adset_id}/ads?limit=5

The above request returns five ads belonging to the specified adset. But since we didn't set any fields, Facebook will only return the ads' ids.

- fields: define what attributes of the specified object are returned

graph.facebook.com/v7.0/{object_id}?fields=id,name,targeting

We can, of course, also combine these with an &.

https://graph.facebook.com/v13.0/{adset_id}/ads?limit=5&fields=id,name

IV. Your first Facebook Marketing API Call

Now let's get you to make your first API call in the Graph API Explorer.

1. Choose GET request. We use a GET request whenever we want to retrieve information from the Facebook Marketing API. If we wanted to change or create something new, we would use a POST request.

2. Then, add the following path:

me?fields=id,name

3. Click Submit. You should see your name and Facebook user id.

Congratulations on your first API call.

On the left side, you can choose additional data fields to get more information about your Facebook id.

V. Get your Facebook ad accounts

Graph%20API%20Explorer%3A%20screenshot

Let's continue:

4. On the left side, choose the adaccounts field or add adaccounts in the URL path and submit. If the run is successful, you will see all of the accounts you have access to.

Note that we have now added an edge as a field to our request. This can be useful when we want to get information about ourselves AND the ad accounts we have access to. In most cases you would simply use me/adaccounts to get the desired ad accounts and add any further information the way we learned above: me/adaccounts?limit=3&fields=name

5. Facebook Marketing API, by default, uses pagination - it will give you only 25 elements back. If you want more, include the following limit parameter.

adaccounts.limit(3)

6. If you want to add the name of the accounts, add the name field:

adaccounts.limit(3){name}

As you can see, where are also able to add limits and fields on fields in a nested structure.

VI. Retrieve Facebook performance data (called "insights")

Let's access one specific ad account

1. Choose an account id, which you know had some ad spend in the last 90 days.

2. All account ids have act_ in front of the actual account id. To fetch your account, make sure to add it.

get%20ad%20account%20request%20via%20Facebook%20Marketing%20API

3. Click on docs, and scroll until Facebook Marketing API. Next, click Reference on the left side. In Reference, you will find all relevant information about possible edges and parameters available for any object.

4. Click on Ad Account on the left side. You will see which type of information is available for which object. You will see all possible calls for that object on the right-hand side.

5. Go back to Graph Explorer. Input the following path:

act_{account_id_of_your_account}/insights

6. In return, you will get the standard information which includes spend, impressions, account id, and dates in the last 30 days.

7. To preset the date range, use the following parameter:

?date_preset={your_date_range}

We can use today, yesterday, last_3d, last_7d, last_28d, last_30d, maximum, and many more.

8. Then, to add another parameter, use the ampersand &. For example, if you want to break down the data by some timeframe, add a time increment using the following structure:

&time_increment={your_time_increment}

Valid values are any numbers from 1 to 90 or monthly. By default, it is set to all_days - so there is no time breakdown.

9. To get more than 25 insight objects, use the limit parameter (max 5000):

&limit=5000

Your entire path should look as follows:

act_123456789/insights?date_preset=last_7d&time_increment=1&limit=5000

VII. Retrieve campaigns and adsets of an ad account

1. To access all campaign objects on your ad account via Facebook Marketing API, input the following path:

act_{your_account_id}/campaigns

2. To add a parameter, add a ? and the names of the desired fields - we'll start with the id and name.

?fields=id,name
get%20campaign%20ids%2C%20names%20via%20Facebook%20Marketing%20API

After hitting "Submit" you should see a list of campaigns. Per default, Facebook will show the last 25 created campaigns here.

3. Click on one of the campaign ids. This should enter the campaign id into the path. You are on now accessing data on a campaign level.

4. Ask for the campaign id, name, and daily_budget :

get%20campaign%20name%20and%20budget%20via%20Facebook%20Marketing%20API

Note: Facebook will only return any field or attribute when it exists. A daily budget only exists when the budget is set on a campaign level and is a daily, not lifetime budget type.

5. To access the performance data, add the insights edge. You can choose any fields and set the parameters you want to. For example, we will be retrieving spend, impression, CPM, and CPC over the campaign's entire lifetime. To get conversion events data, add the actions field.

/insights?date_preset=maximum&fileds=spend,impressions,cpm,actions

VIII. Retrieve and change budgets via the Facebook Marketing API

a) Get a campaign's adsets

1. First, let's get all adsets belonging to our specified campaign, using the /adsets edge.

get%20adsets%20data%20via%20Facebook%20Marketing%20API
2.

2. Click on one of the adsets from the previous step or input a new adset id.

3. To retrieve an adset's daily budget, use ?fields=daily_budget path

get%20campaign%20budget%20via%20Facebook%20Marketing%20API

Note that budget or bid information always shows as cents (if your account's currency is set to EUR/USD) or pence (for GBP accounts)!

4. Add some of the additional suggested fields you are interested in to retrieve the adset data.

b) Change an adset's daily budget

5. Change GET to POST.

POST requests are used when we want to create a new or make changes to an existing ad object.

6. To change the budget, use the desired value in cents by adding it after the daily_budget parameter. You still have to specify which fields Facebook should return on its response.

get%20ads%20data%20via%20Facebook%20Marketing%20API

If successful, Facebook will return the newly updated daily budget.

Congrats! This is the first change that you have made via the Facebook Ads API!

IX. Retrieve ads of an adset

1. Get ads of your adset by calling the /ads edge.

get%20ads%20data%20via%20Facebook%20Marketing%20API

2. Add name and id fields to understand better which ads you retrieve.

get%20ads%20data%20via%20Facebook%20Marketing%20API

3. Click on an ad id. Ask for insights to get performance data for the specified ad:

get%20facebook%20insights%20via%20Facebook%20Marketing%20API

X. Get an ad's creative and more

4. To retrieve the URL or any other user-facing parts of your ad, retrieve the adcreatives edge. Ad creatives is the edge that allows you to read any creative data inside of the ads.

{ad_id}/adcreatives

Note: You can achieve the same by adding that creative field:

{ad_id}?fields=creative

5. Click on the ad creative id. Each ad has exactly one ad creative. Next, add asset_feed_spec to retrieve data from body texts, titles, and descriptions.

Note that depending on the ad format and whether you're using dynamic elements, the creative's information may be stored in different places. asset_feed_spec may not exist for your particular ad. If so, follow the next steps.

get%20asset%20feed%20specs%20via%20Facebook%20Marketing%20API

6. Add call_to_action_type to read out the CTA type used. Of course, to the end-user, this is always localized.

7. Now add object_story_spec field. This is an important field when retrieving creative information. Inside object_story_spec, you will find the page_id and instagram_actor_id. Depending on your ad format, you may also find link, caption, and image_hash or video_id.

get%20object%20story%20spec%20via%20Graph%20API

XI. Retrieve information with a browser instead of the Graph API Explorer

1. Every GET request we do with a Graph API Explorer can also be made with a simple browser. You have to add the first bit yourself:

graph.facebook.com/v13.0/{path_from_graph_api_explorer}

3. Put your ads_read access token at the end of the link with &access_token={your_access_token} parameter:

get%20Facebook%20data%20through%20your%20browser

4. You will now see the JSON response right in your browser.

And that concludes the Practical Introduction to the Facebook Marketing API.

If you are looking for more video tutorials, head to our Youtube page.

If you want to dive right into building cool automations with the Facebook Marketing API without worrying about managing your access token and dealing with code yourself, check out the Kitchn.io product demo or get in touch at https://www.kitchn.io/start