Facebook API Tutorial: Graph API, Access Token, and Developer Documentation Explained

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.

image

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.

I. Create a Facebook App

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.

1. Go to the Facebook developers portal - developers.facebook.com

2. Log into your Facebook account

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

Type caption (optional)

4. Give it a name and contact email.

Type caption (optional)

5. Click on Create App

6. 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)

II. Get an access token to access for Facebook Apps

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):

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 and social media accounts)
• ads_read(readout ads data)
• read_insights(read out performance insights)

Type caption (optional)

2. Click on Get Access Token

use Facebook Graph API Explorer (more granular permission management):

1. Go to Tools —> Facebook Graph API Explorer

2. Choose the right app on the right side

3. Choose Get User Access 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 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.

III. Working with the Graph API: Objects, edges

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.

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 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}
      

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 Facebook 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 Graph API Call

Now let's get you to make your first Facebook API call in the Facebook 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 Graph 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

Type caption (optional)

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 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, we can also add limits and fields on fields in a nested structure.

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

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.

Type caption (optional)

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 Facebook Graph API 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 via Graph API

1. To access all campaign objects on your ad account via Graph 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
      

Type caption (optional)

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 :

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.

5. To access the performance data, add the insights edge. You can choose any fields and set the parameters you want. For example, we will retrieve 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 API

a) Get a campaign's adsets

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

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 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)!

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 API should return on its response.

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!

IX. Retrieve ads of an adset

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

Type caption (optional)

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

Type caption (optional)

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

Type caption (optional)

X. Get an ad's creative and more

4. To retrieve the URL or any other user-facing parts of your ad from Facebook API, 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.

Type caption (optional)

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.

Type caption (optional)

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

1. Every GET request we do with a Facebook 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:

Type caption (optional)

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

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.