Tutorial
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 API: how to get access to the API itself, get performance data via the Insights API, and make changes to your campaigns, adsets, and ads 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 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.
Please note that this is not an official Graph API tutorial. For more details on the Marketing API, refer to the official Facebook developers portal documentation.
First, to use Facebook programmatically via the Facebook 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 Graph 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.
Go to the Facebook developers portal - developers.facebook.com
Log into your Facebook account
Go to My Apps —> Create app. Choose Business as an app type.
Type caption (optional)
Type caption (optional)
Click on Create App
In the Facebook product list, choose Facebook API and click on Set Up. After you click, Marketing API will appear on the left side of your app menu.
Type caption (optional)
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.
Use Facebook developer portal (quick and easy):
Click on Tools under the Marketing API on the left side. Choose Access Token Tool.
Select the permissions that you need:
Type caption (optional)
use Facebook Graph API Explorer (more granular permission management):
Go to Tools —> Facebook Graph API Explorer
Choose the right app on the right side
Choose Get User Access Token on the section User or Page
You will be redirected to do the standard Facebook login flow.
Add the permissions that you will need. In our case, we choose ads_management and read_ads.
Click on Generate Access Token in Graph API.
Type caption (optional)
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.
You will need to understand a few other core concepts to successfully navigate the Facebook Graph API.
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 Facebook API or make changes to existing ad objects.
Every element or item with an ID in Facebook Business Manager is an object.
For example:
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}
Edges are "connections" to other related objects. For example, an ad account has a campaigns edge, meaning we can request the ids of all campaigns in the ad account. The opposite is true as well - any campaign has an ad account edge and 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}
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 Facebook API:
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.
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
Now let's get you to make your first Facebook API call in the Facebook Graph API Explorer.
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.
Then, add the following path:
me?fields=id,name
Congratulations on your first Graph API call.
On the left side, you can choose additional data fields to get more information about your Facebook id.
Type caption (optional)
Let's continue:
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
adaccounts.limit(3)
adaccounts.limit(3){name}
As you can see, we can also add limits and fields on fields in a nested structure.
Choose an account id, which you know had some ad spend in the last 90 days.
All account ids have act_ in front of the actual account id. To fetch your account, make sure to add it.
Type caption (optional)
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.
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.
Go back to Facebook Graph API Explorer. Input the following path:
act_{account_id_of_your_account}/insights
In return, you will get the standard information which includes spend, impressions, account id, and dates in the last 30 days.
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.
&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.
&limit=5000
Your entire path should look as follows:
act_123456789/insights?date_preset=last_7d&time_increment=1&limit=5000
act_{your_account_id}/campaigns
?fields=id,name
Type caption (optional)
After hitting "Submit" you should see a list of campaigns. Per default, Facebook will show the last 25 created campaigns here.
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.
Ask for the campaign id, name, and daily_budget :
Type caption (optional)
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.
/insights?date_preset=maximum&fileds=spend,impressions,cpm,actions
Click on one of the adsets from the previous step or input a new adset id.
To retrieve an adset's daily budget via Facebook API, use ?fields=daily_budget path
Type caption (optional)
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)!
POST requests are used when we want to create a new or make changes to an existing ad object.
Type caption (optional)
If successful, Facebook API will return the newly updated daily budget.
Congrats! This is the first change that you have made via the Graph API!
Type caption (optional)
Type caption (optional)
Type caption (optional)
{ad_id}/adcreatives
Note: You can achieve the same by adding that creative field:
{ad_id}?fields=creative
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.
Type caption (optional)
Add call_to_action_type to read out the CTA type used. Of course, to the end-user, this is always localized.
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.
Type caption (optional)
graph.facebook.com/v13.0/{path_from_graph_api_explorer}
Type caption (optional)
And that concludes the Practical Introduction to the Facebook API.
If you are looking for more video tutorials about Graph API, head to our Youtube page.
If you want to dive right into building cool automations with the Facebook API without worrying about managing your access token and dealing with code yourself, check out the Kitchn.io product demo and get in touch with us. We help D2C brands, and marketing agencies automate their paid social media ad operations and free their time for more important tasks.