Create your first ad with the Marketing API by following these steps.
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.
Start the process creating a new campaign object from the class Campaign
. At this stage, you need to set an objective for your ads, which is the overall goal of your campaign. We recommend that you create a PAUSED
campaign initially, so you do not get billed while testing.
curl -X POST \
-F 'name="My campaign"' \
-F 'objective="OUTCOME_TRAFFIC"' \
-F 'status="PAUSED"' \
-F 'special_ad_categories=[]' \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v21.0/act_<AD_ACCOUNT_ID>/campaigns
On success, we return an ID for your newly created ad campaign. Remember to save this ID. You can also verify your campaign has been created in ads manager.
Before moving to create your ad sets, you need to define your target audience. In the next step, you create an ad set and specify your audience's attributes.
You have many targeting options. In this example, we use targeting search to find predefined values that can be used to set up an audience.
First, let's look for available countries including the word "united":
curl -G \ -d 'location_types=["country"]' \ -d 'type=adgeolocation' \ -d 'q=united' \ -d 'access_token=<ACCESS_TOKEN>' \ https://graph.facebook.com/v<API_VERSION>/search Open In Graph API ExplorerOpen In Postman
Then, we can look for interests including the word "movie":
curl -G \ -d 'type=adinterest' \ -d 'q=movie' \ -d 'access_token=<ACCESS_TOKEN>' \ https://graph.facebook.com/v<API_VERSION>/search
Based on the values returned from the calls above, we know that we can create an audience of people in the United States that are interested in movies. The targeting spec looks like this:
targeting={ "geo_locations": {"countries":["US"]}, "interests": [{id: 6003139266461, 'name': 'Movies'}] }
An ad set is a group of ads that share the same daily or lifetime budget, schedule, billing, optimization, and targeting data. In this step, you need to create a new object from the class AdSet
and specify:
start_time
and end_time
.daily_budget
or lifetime_budget
.optimization_goal
.billing_event
.bid_amount
field.To create your ad set, you also need the ad campaign ID you saved from Step 1:
curl -X POST \
-F 'name="My Reach Ad Set"' \
-F 'optimization_goal="REACH"' \
-F 'billing_event="IMPRESSIONS"' \
-F 'bid_amount=2' \
-F 'daily_budget=1000' \
-F 'campaign_id="<AD_CAMPAIGN_ID>"' \
-F 'targeting={
"geo_locations": {
"countries": [
"US"
]
},
"facebook_positions": [
"feed"
]
}' \
-F 'status="PAUSED"' \
-F 'promoted_object={
"page_id": "<PAGE_ID>"
}' \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v21.0/act_<AD_ACCOUNT_ID>/adsets
We recommend the creation of an ad set with the PAUSED
status to avoid charges during your test.
In this step, you will use the AdCreative
object to provide the visual elements of your ad. The information you need to provide depends on your objective, but common attributes are:
Depending on your objective you may have to provide advanced fields. For example, ads for an iOS app require an app store URL.
You can define creative as part of an ad set or standalone. In either case, we store your ad creative in your ad account's creative library to use in ads.
This example shows how to provide an image and create the AdCreative
object.
First, create an AdImage
object from an image file:
curl \ -F 'filename=@<IMAGE_PATH>' \ -F 'access_token=<ACCESS_TOKEN>' \ https://graph.facebook.com/v<API_VERSION>/act_<AD_ACCOUNT_ID>/adimages
Then, use the image hash to create the AdCreative
:
curl -X POST \ -F 'name="Sample Creative"' \ -F 'object_story_spec={ "page_id": "<PAGE_ID>", "link_data": { "image_hash": "<IMAGE_HASH>", "link": "https://facebook.com/<PAGE_ID>", "message": "try it out" } }' \ -F 'degrees_of_freedom_spec={ "creative_features_spec": { "standard_enhancements": { "enroll_status": "OPT_IN" } } }' \ -F 'access_token=<ACCESS_TOKEN>' \ https://graph.facebook.com/v<API_VERSION>/act_<AD_ACCOUNT_ID>/adcreatives Open In Graph API ExplorerOpen In Postman
Verify your image upload by going to your Media Library inside ads manager.
At this point, the AdCreative
with your link is not yet visible in Ads Manager. You see this data once you book your ad. You can debug your ad creative with Graph API Explorer and specify any fields you want to read:
GET /{my-creative-id} HTTP/1.1
Host: graph.facebook.com/?fields=object_story_spec
Finally, create your Ad object to link your AdCreative
and AdSet
. Set the status
of your Ad
to paused
to avoid placing an order instantly.
curl -X POST \
-F 'name="My Ad"' \
-F 'adset_id="<AD_SET_ID>"' \
-F 'creative={
"creative_id": "<CREATIVE_ID>"
}' \
-F 'status="PAUSED"' \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v21.0/act_<AD_ACCOUNT_ID>/ads
Verify that your ad exists in the ads manager. Click on the campaign you just created, then on the ad set, and on the ad.
Once you're comfortable booking ads with the API, set the status to active
. First, the ad goes through ad review, and has the status PENDING_REVIEW
. Once the review is done, it goes back to the status of ACTIVE
.
Alternatively, you can copy an existing ad, asset or campaign. It helps you quickly duplicate a campaign to change configurations or create test groups to extract performance knowledge. For more details, see: