Facebook Ads API (Beta)

Documentation
October 2009


 Ads API Documentation (Beta) | 2


Introduction
At Facebook, we’re constantly working to match advertisers with users who are interested in
their products and services. We know that you see a better response from your customers
when you tailor ad creative and targeting criteria to specific sets of users, so we’ve created the
Advertising Application Programming Interface ((Ads API) to help you manage your large and
often complex ad campaigns

The Facebook Ads API (currently in beta testing) enables you to build applications that interact
directly with the Facebook Ads platform. You can build an application that uses the Facebook
Ads API to automatically create, mmonitor,
onitor, and update your advertising campaigns, enabling you
to update your
our campaigns based on their performance without relying on manual updates.
We’re excited to invite you to beta test these tools.

The Ads API is part of the Facebook Developer Platform. For general information about the
developer platform, please visit the Facebook Developer
Developers Website at
http://developers.facebook.com..

This document describes the

he advertising
advertising-specific functionality that has been added to the
Developer Platform which you can use to programmatically create, edit, manage, and get
reporting on your Facebook Ads..

Follow these steps to set up a Facebook application, which you need in order to use the
Facebook Ads API.

1. Log in to the account you’ll use to develop the application

application. This must be a real
Facebook account, not an n advertising
advertising-only “gray account.”
2. Go to http://www.facebook.com/developers/
3. Click “Set Up New Application”
pplication”
4. Enter an application name
name,, agree to the Terms of Service, then click “Save Changes.”
5. Send the resulting “API Key” value to ads-api-bugs@lists.facebook.com,, through which
a support team member will activate the key for use with the Ads API. The key looks
something like this: f43418a3fc929e2bfa3d8dcc549351d2. We do not need your
application secret.
6. Add any other users who need to access this application in the “Developers” list.
7. Click “Save Changes” to finish configuring the application.


The API Test Console (http://developers.facebook.com/tools.php
http://developers.facebook.com/tools.php)) allows you to test
t all the
methods listed in this document when called with an application / account ID that has access to
the Ads API.

Please note that many API calls use JSON

JSON-encoded
encoded parameters and the Developer Test
Console will also require the parameters to be JJSON-encoded.
encoded. Please check the example
JSON requests and results section under Documentation Nomenclature below and individual
API calls for specific details.

Document Nomenclature
 
 Ads API Documentation (Beta) | 3


All bolded variables under a method are required to be passed with some non-null value.

Example:
ads.getCampaigns
ads.getCampaigns(int64 account_id,
list<ads_campaign> ads.getCampaigns( , list<int64>
campaign_ids, bool include_deleted)

For the ads.get Campaigns method above, account_id has to be passed with some value but
campaign_ids and include_deleted can be passed as null.

In addition, you will

ill see parameters defined as: parent.child. This translates into a nested array
keyed on the parent name.. For example
example, targeting.country and targeting.keywords are
elements of the targeting array in PHP
PHP:

$ad['targeting'] = array ("country" => "US", "keywords" => array("chocolate"));

Furthermore, if the API call requires the parameter in JSON format, then you should encode the
entire array into a JSON string
tring and pass the string as the parameter.



JSON targeting string
{"countries":["US"],"genders":[1],"relationship_statuses":[2,
{"countries":["US"],"genders":[1],"relationship_statuses":[2,3,4],"age_min":"18","age_max":"43","
4],"age_min":"18","age_max":"43","
cities":[{"name":"atlanta, ga"}],"radius":"12","keywords":["movies"]}

Plain English translation:

18-43
43 year old males within a 12 mile radius of Atlanta, GA, USA that are either in a relationship
or married and have the keyword “movies”
“movies”.

JSON adspec string

Add ad info to the targeting JSON
{"campaign_id":"6002276788163","name":"testing","bid_type":"1"
{"campaign_id":"6002276788163","name":"testing","bid_type":"1","max_bid":30,"targeting":{"cou
,"max_bid":30,"targeting":{"cou
ntries":["US"],"genders":[1],"relationship_statuses":[2,4],"age_min":"18","age_max":"43","cities":[
{"name":"atlanta, ga"}],”radius”:”12”,
”radius”:”12”,"keywords":["movies"]},"creative":{"title":"atl","body":"ftl",
"keywords":["movies"]},"creative":{"title":"atl","body":"ftl",
"link_url":"http://www.YourUrl.com/"}}
urUrl.com/"}}

This string will create one adgroup within campaign ID 6002276788163.. It is a CPC ad with a
bid of $0.30 and the ad name “testing,” but that is not the title of the ad. This ad will target
Males in a 12 mile radius of Atlanta, GA who are in a relationship or married and have the
keyword “movies” in their profile. Please note the addition of the creative JSON string which
specifies the ad title, body and the link.

JSON ads.estimateTargetingStats response

If you pass the targeting string
ng abov
above
e into the ads.estimateTargetingStats method, the return will
look something like this:

18380":[{"location":3,"cpc_min":60,"cpc_median":62,"cpc_max":71,"c
":[{"location":3,"cpc_min":60,"cpc_median":62,"cpc_max":71,"c
pm_min":27,"cpm_median":29,"cpm_max":32}
pm_min":27,"cpm_median":29,"cpm_max":32}

 
 Ads API Documentation (Beta) | 4



To upload images, add the additional “image_file” parameter to the creative JSON (for example,
‘image_file’ : ‘somefilename.jpg’).
). T
Then change your createAdGroups API request to a
multipart/form-data request and append the following to the raw API request
request:

Content-Disposition: form-data;
data; filename="
filename="yourimagefile.jpg"
Content-Type: image/jpg
[Raw file data here]

Third-party
party sample code libraries for Facebook Platform have methods that you can extend for
this purpose -- take a look at how the library you are using makes the photos.upload
hotos.upload call. You
can see the available client libraries for Facebook Platform at
http://wiki.developers.facebook.com/index.php/Client_Libraries

If you’re using PHP

HP with our facebookapi_restlib file included, you can just add the image file
name to your ad’s creative JSON array. The example snippet below assumes you’ve already
put your creative into your ad_group spec
spec. Adding the image file is the last step:

$adgroup_spec['creative']['image_file']
group_spec['creative']['image_file'] = $image_file_name;
ads_createAdGroups($account_id, $adgroup_spec, imagedata)

Data Types
int
32-bit integer
int64
64-bit integer
bool
boolean
string
string
json_string
JSON-encoded object
list<x>
array of values of type x

Ads Structs
ads_account
struct ads_account {
int64 account_id,
string name,
int daily_spend_limit,
list<ads_account_user> users,

 
 Ads API Documentation (Beta) | 5


string currency
}
Notes:
• Calls to ads.getAccounts return an array with these elements
• name is the name of the account. The name can have at most 30 characters
• daily_spend_limit is defined in US cents
cents, with 100 cents USD as the minimum value
• currency is a 3 character ISO code for currency of account (e.g. USD)
USD).. Supported
currencies currently include:

Australian Dollars (AUD) British Pound (GBP) Canadian Dollars (CAD)

Chilean Peso (CLP) Colombian Peso (COP) Euro (EUR)
Danish Krone (DKK) Hong Kong Dollar (HKD) Japanese Yen (JPY)
Norwegian Krone (NOK) Swedish Krona (SEK) Swiss Fanc (CHF)
Turkish Lira (TRY) US Dollars (USD) Venezuelan Bolivar (VEF)

ads_account_user
struct ads_account_user {
int64 uid,
}
Notes:
• uid is the Facebook user id for the application user

ads_campaign
struct ads_campaign {
int64 account_id,
int64 campaign_id,
string name,
int time_start,
int time_stop,
int daily_budget,
y_budget,
ads_run_status campaign_status,
int lifetime_budget
}
Notes:
• account_id is the Ads account ID
• campaign_id is the ID of the campaign you are editing or getting stats for, not used in
create_campaigns
• name is at most 30 characters
• time_start and time_stop are unix timestamps
• time_stop can’t be more than one year in the future
• daily_budget defined in cents USD
USD. 100 cents USD is the minimum value
• lifetime_budget defined in cents USD
• lifetime_budget and daily_budget cannot be zero

ads_update_campaigns_result
s_result
struct ads_update_campaigns_result {
list<int64> updated_campaigns;
map<int64, list<string>> failed_campaigns;

 
 Ads API Documentation (Beta) | 6


}
Notes:
• When ads.createCampaigns is called,
ads_update_campaigns_result.updated_campaigns contains the IDs ID of the
campaigns that were created. failed_campaigns contains the list of campaigns that
could not be created. The index is the same as the index specified in campaign_specs
when ads.createCamp
ads.createCampaigns is called. The value is a list of error messages for that
particular campaign.

• When ads.updateCampaigns is called,

ads_update_campaigns_result.updated_campaigns contains the IDs ID of the
campaigns that were updated. failed_campaigns contains the list of campaigns that
could not be updated and the reasons why.

ads_adgroup
struct ads_ad {
int64 ad
adgroup_id,
int64 campaign_id,
string name,
ads_run_status ad
adgroup_status,
ads_ad_bid_type bid_type,
int max_bid,
ads_targeting targeting,
ads_creative creative,
}
Notes:
• name is at most 30 characters
• max_bid defined in cents
• targeting and creative are JSON-encodedencoded strings representing the targeting and
creative elements of the AdGroup you are creating or querying
• Paused ads can return either ADGROUP_PAUSED or CAMPAIGN_PAUSED.. In the case of
CAMPAIGN_PAUSED,, unpausing the campaign will also unpause the ad group. If the ad
group returns ADGROUP_PAUSED
ADGROUP_PAUSED,, however, you will have to unpause that specific ad group.

ads_update_adgroups_result
_result
struct ads_update_adgroupsgroups_result {
list<int64> update_ad adgroups,
map<int64, list<string>> failed_adgroups,
}
Notes:
• When ads.createAdGroups is called,
ads_update_adgroups_result.updated_adgroups contains the IDs ID of the ad
groups that were created. The failed_adgroups element contains the list of ad
groups that could not be created. The index is the same as the index specified in
adgroup_specs when ads.createAdGroups is called. The value is a list of error
messages for that particular ad group.

• When ads.updateAdGroups is called,

ads_update_adgroups_result.updated_adgroups contains the IDs
ID of the ad
 
 Ads API Documentation (Beta) | 7


groups that were updated. failed_adgroups contains the list of ad groups that could
not be updated and the reasons why.

ads_creative
struct ads_creative {
int64 creative_id,
int64 account_id,
string title,
string body,
string link_url,
}
Notes:
• ads_creative is subject to several constraints, including:
o title must be at least 1 character and at most 25 characters
o body must be at least 1 character and at most 135 characters
o creative_id is only used if you want to reuse a creative from a different ad

ads_targeting
struct ads_targeting {
list<string> > countries
countries,
list<ads_id_name_map> cities,
list<ads_id_name_map> regions,
list<ads_targeting_gender> genders,
list<ads_id_name_map> college_networks,
list<ads_id_name_map> work_networks,
int age_min,
int age_max,
list<ads_targeting_education> education_statuses,
list<int> college_years,
list<string> college_majors,
list<ads_targeting_political> political_views,
list<ads_targeting_relationship> relationship_statuses,
list<string> keywords,
list<ads_targeting_gender> interested_in,
int radius,
}
Notes:
• for countries, regions, cities cities, work_networks you
, college_networks, work_networks,
can use the ads.getAutoCompleteData method documented under “AdGroup AdGroup Service
Methods” to get targetable
able options
options.
• min_age must be 13 years or higher
• college_years is defined as the graduating year of a user and is in calendar years, e.g.,
[2008, 2009]
• keywords are matched to user profile data to better target ads
• attribute lists can contain at most 50 elements
• for cities in the US or Canada
Canada, include the two letter state or province code.
code For cities
outside the US and Canada, include the whole country name. For example,, use “New York,
NY” or “Paris, France”.

 
 Ads API Documentation (Beta) | 8


time_ranges
This is a JSON string of time_ranges used in the reporting functions
functions.. There are two options for
sending time ranges, one using UNIX time stamps and other using MM-DD-YYYY YYYY notation.
Each stats call allows you to pull stats for multiple campaigns or ad groups at once, so the
time_ranges are expected to be an array of these strings. Examples of each option are below:

'{"time_range":{"day_start":{"month":9,"day":11,"year":2009},"day_stop
":{"month":9,"day":13,"year":2009}}}'
'{"time_start":1252537200,"time_s
2537200,"time_stop":1252623600}'

To get lifetime stats use:

'{"time_start":0,"time_stop":0
{"time_start":0,"time_stop":0}'

To get stats ending as recently as possible use:

'{"time_start":1252537200,"time_stop":0
{"time_start":1252537200,"time_stop":0}'

ads_stats
struct ads_stats {
int64 id,
int time_start,
int time_stop,
int impressions,
int clicks,
int spent,
}
Notes:
• this is the structure returned when you call getCampaignStats or getAdGroupStats
• id contains the ID of some system entity, e.g., campaign or ad
• spent defined in cents USD
• clicks and impressions are the aggregate number of clicks and impressions for the
AdGroup or campaign ID
• time_start and time_stop will always be returned in UNIX time

Ads Enums
campaign_status
enum campaign_status {
ACTIVE = 1,
PAUSED = 2,
DELETED = 3,


ads_run_status
enum ads_run_status {
ACTIVE = 1,
PAUSED = 2,
 
 Ads API Documentation (Beta) | 9


DELETED = 3,
PENDING_REVIEW = 4,
DISAPPROVED = 5,
CAMPAIGN_PAUSED = 8,
ADGROUP_PAUSED = 9,
}
Notes:
• PAUSED is deprecated. Use CAMPAIGN_PAUSED to pause campaigns and the ad
groups
roups within that campaign.
• When you unpause a campaign, however, the ad groups
roups whose status was previously
CAMPAIGN_PAUSED will also become unpaused.
• ADGROUP_PAUSED indicates the adgroup is paused independently of the campaign’s
status. Use ADGROUP_PAUSED to pause individual ad groups.

ads_ad_bid_type
enum ads_ad_bid_type {
CPC = 1,
CPM = 2,
}

ads_targeting_gender
enum ads_targeting_gender {
MALE = 1,
FEMALE = 2,
}

ads_targeting_relationship
enum ads_targeting_relationship {
SINGLE = 1,
IN_RELATIONSHIP = 2,
MARRIED = 3,
ENGAGED = 4,
}

ads_targeting_political
enum ads_targeting_political {
LIBERAL = 1,
MODERATE = 2,
CONSERVATIVE = 3,
}

ads_targeting_education
enum ads_targeting_education {
HIGH_SCHOOL = 1,
UNDERGRAD = 2,
ALUM = 3,
}

 
 Ads API Documentation (Beta) | 10


Account Service Methods

ads.getAccounts
list<ads_account> ads.getAccounts()

Returns an array of all accounts associated with the currently logged in user.

Campaign Service Methods

ads.getCampaigns
ads.getCampaigns(int64 account_id,
list<ads_campaign> ads.getCampaigns( , list<int64>
campaign_ids, bool include_deleted)

Gets all campaigns from the account. If include_deleted is false, only non-deleted
deleted
campaigns are returned. If campaign_ids is specified, only campaigns with specified
pecified IDs
ID are
returned.

ads.createCampaigns
ads.createCampaigns(int64 account_id, list
ads_campaign_result ads.createCampaign
campaign_specs)

Creates a campaign. The parameter campaign_specs is an array of JSON-encoded

encoded
ads_campaign structs with the following required attributes defined:
account_id
name
daily_budget

The following optional attributes can be defined:

time_start
time_stop

All other attributes are ignored.

ads.updateCampaigns
ads.updateCampaigns(int64 account_id, list
ads_campaign_result ads.updateCampaign lis
campaign_specs)

Updates a campaign. The parameter campaign_specs is an array of JSON-encoded

encoded
ads_campaign structs with the following required attributes defined:

campaign_id

The following optional attributes are the only ones that can be updated:
name
 
 Ads API Documentation (Beta) | 11


daily_budget
time_start
time_stop
campaign_status

The campaign_status enum is defined in the “Ads Enums” section above. Only pass the
attributes that you wish to update. All other attributes are ignored and attributes that aren’t
passed will remain unchanged.

ads.getCampaignStats
list<ads_stats> ads.getCampaignStats(int64 account_id, list<int64>
ads.getCampaignStats(int64
campaign_ids,
, bool include_deleted, json_string time_ranges)
time_ranges

Gets basic stats for the campaigns in the account over different time ranges. If
include_deleted is false, only non non-deleted campaigns are returned. If campaign_ids is
specified, only campaigns with specified ids are returned. time_ranges is a JSON-encoded
JSON
array defined in the “Ad Structs” section.

AdGroup Service Methods

ads.getAutoCompleteData
getAutoCompleteData
utoCompleteData(int64 account_id)
list<> ads.getAutoCompleteData

This API call returns all possible colleges, college_majors, workplaces, locales,
countries, regions and cities cities. Each category is an array nested within the return array
like the example below:

array (
'colleges' =>
array (
0 =>
array (
'value' => 'Harvard',
…

ads.getAdGroups
ads.getAdGroups(int64 account_id,
list<ads_adgroup> ads.getAdGroups( , list<int64>
campaign_ids, list<int64> adgroup_ids, bool include_deleted)

Gets a set of ad groups in the account. campaign_ids, adgroup_ids, and

include_deleted filter the list of ad groups to be returned.

ads.createAdGroups
ads_update_adgroups_result ads.createAdGroups(int64 account_id, list
ads.createAdGroups(int64
adgroup_specs)
 
 Ads API Documentation (Beta) | 12


Creates ad groups. The parameter ad_specs is an array of JSON-encoded

encoded array of
ads_adgroup structs with the following required attributes defined:

• campaign_id
• name
• bid_type
• max_bid
• targeting
o At minimum, you must specify country targeting (a list of two letter ISO country
codes)

And EITHER:

• creative.title
• creative.body
• creative.link_url
• creative.link_type

OR:

• creative.creative_id (provide existing creative_id to recycle a

creative)

The following optional attributes can also be defined:

• targeting.cities
• targeting.regions
• targeting.genders
• targeting.college_networks
• targeting.work_networks
• targeting.age_min
• targeting.age_max
• targeting.education_statuses
• targeting.college_years
• targeting.college_majors
• targeting.political_views
• targeting.relationship_statuses
• targeting.keywords
• creative.image *** see notes on image upload

All other attributes are ignored.

For image uploads, you’ll need to use a multi-part MIME type,, as in the “Images” section above.
above
You can also take a look at the sample app for more detail.

 
 Ads API Documentation (Beta) | 13


ads.updateAdGroups
ads.updateAdGroups(int64 account_id, list adgroup_specs)
ads_ad_result ads.updateAdGroups( adgroup_specs

Updates an adgroup. The parameter adgroup_specs is a an array of JSON encoded ads_adgroup

structs with the following required attributes defined:

• adgroup_id

The following optional attributes can be defined:

• name
• max_bid
• ad_status

The API will update whatever parameters you specify in each adgroup
roup struct. For example,
example if
you only want to change the name of AdGroup 123456, pass only the name within the JSON
string for that ad group.
roup. Example: [{‘”adgroup_id” : 123456, “name”
ame” : “new name”}]

ads.getAdGroupStats
ads.getAdGroupStats(int64 account_id,
list<ads_stats> ads.getAdGroupStats( , list<int64>
campaign_ids, list<int64> adgroup_ids
adgroup_ids,
, bool include_deleted,
list<ads_time_range> time_ranges
time_ranges)

Gets stats for a list of ad groups in the account. campaign_ids, adgroup_ids,

adgroup_ids and
include_deleted are used to filter the list of ad groups. The time_ranges structure is
defined in the “Ads Structs” section above.

ads.getAdGroupTargeting
Targeting
map<int64, ads_targeting> ads.getAdTargeting(int64 account_id,
ads.getAdTargeting(int64 account_id
list<int64> campaign_ids, list<int64> adgroup_ids, bool
include_deleted)

Gets targeting (a map of adgroup

group IDs to ads_targeting)) for a list of ad groups in the account.
adgroup_ids, and include_deleted are used to filter the list of ad
campaign_ids, adgroup_ids
groups.

ads.getAdGroupCreatives
Creatives
map<int64,
64, ads_creatives> ads. int64 account_id,
ads.getAdCreatives(int64 account_id
list<int64> campaign_ids, list<int64> adgroup_ids, bool
include_deleted)

Gets creatives (a map of adgroup

group IDs to ads_creative)) for a list of ad groups in the account.
adgroup_ids, and include_deleted are used to filter the list of ad
campaign_ids, adgroup_ids
groups.

 
 Ads API Documentation (Beta) | 14


ads.estimateTargetingStats
ads_targeting_stats ads.estimateTargetingStats(int64 account_id,
ads.estimateTargetingStats(int64 account_id
ads_targeting targeting_spec
targeting_spec, string currency)

Returns statistics based on the targeting criteria specified. CPC/CPM values are based on the
currency specified.

 