Homepage Ads via API

This document illustrates how to create Homepage ads via our Ads API using your Self-serve account.

Please follow the steps given below to create Homepage Ads using the Ads API.

Make sure your Ads account is part of the Homepage Ads beta otherwise you will be unable to complete the following steps.

Fetch rate cards for your currency

A country rate card is its CPM cost in our system, each rate is expressed in cents in that currency.

Request

curl "https://graph.facebook.com/act_XXXXXXX/ratecard?access_token=access_token"

Sample Response (Note: These values are for example only, actual values may be different)

 {
   "data": [{
       "country": "US", 
       "currency": "USD", 
       "rate": 900
     }, 
     {
       "country": "CA", 
       "currency": "CAD", 
       "rate": 750
     }, 
     {
       "country": "GB", 
       "currency": "GBP", 
       "rate": 530
     }, 
     ...  
   ]
 }

---

Creating a Homepage Campaign

The following parameters are mandatory to create a Homepage Campaign:

• lifetime_budget: Defined in cents, minimum 100. If you specify only a lifetime_budget, you should also specify an end_time for the campaign. Note lifetime_budget campaign must have a fixed end_time and cannot be ongoing.
• lifetime_imps: Lifetime impressions for the campaign
• end_time: A unix timestamp. Must always be in the future.

Note The campaign CPM (lifetime_buget / lifetime_imps) should match at least one of the countries currency rate card you’re using. A country rate card is its CPM cost in our system (To find out rate cards for countries please refer to step 1). If the campaign CPM does not match the country rate card, it is likely that the Ad will not run.

Request

 curl -F name="Homepage Campaign Testing" \
      -F lifetime_budget=50000 \
      -F lifetime_imps=5000 \
      -F start_time=1337712317 \
      -F end_time=1337798717 \
      -F campaign_status=2 \
 "https://graph.facebook.com/act_XXXXXXX/adcampaigns?access_token=access_token"

Sample Response

 {"id":"6004467942302"}

Create a Homepage Ad Group

A Homepage campaign should contain one or more Homepage Ad Group(s), it cannot contain a regular ad group.

The following parameters are mandatory to create a Homepage Ad Group:

• bid_type: Use 5 for Homepage.
• Creative Type: Creative types that are available for the Homepage placement are: 2,3, 12, 25 and 27. When creating Homepage ads which would ordinarily be Type 1 you should use Type 12 instead.
• bid_info: In order to create a Homepage Ad Group, you should be using the following bid_info goal: Clicks: 20%, Social impressions: 40%, Reach: 40%: bid_info={'1':20,'38':40,'44':40}" Please refer to https://developers.facebook.com/docs/reference/ads-api/optimizedcpm (Relative Version of Optimized CPM)
• locations: Use 4 for Homepage
• targeting: The Homepage Ad Group’s targeting country should be set to the country matching the rate card chosen when creating the Homepage Campaign. (You can specify "page_types":["home"] in order to have the Homepage Ad only appear in the right-hand column)

Request

 curl -F campaign_id=6004467942302 \
      -F bid_type=5 \
      -F "bid_info={'1':20,'38':40,'44':40}" \
      -F locations=[4] \
      -F "creative={\
           'type':12,\
           'title': 'Homepage Ad Example',\ 
           'body': 'This is the body of a Homepage Ad.'\ 
           'link_url': 'http://example.com/',\ 
           'image_url': 'http://example.com/images/banner.jpg'\
          }" \
      -F "targeting={'countries':['US']}" \
      -F name="Homepage Adgroup Test"\
"https://graph.facebook.com/act_XXXXXXX/adgroups?access_token=access_token"

Sample Response

 {"id":"6004469964102"}