Manage Facebook Campaigns

Warning

The Facebook API will be retired at the end of February 2023.

We must be given advertiser access using the dashboard or via the API by following the Facebook setup guide. See Facebook API Overview for an introduction to the API.

Before creating Facebook ads, please review Facebook Ads and Placements in the Help Center.

Overview

To create a Facebook campaign with ads from scratch you need to:

1. Retrieve existing Audience EIDs or create new Audiences

2. Create a Facebook Campaign

3. Create an AdSet and attach the Audience EIDs from the first step

4. Create Facebook Creative

5. Create Facebook Ads to map FB Creative to the FB AdSet you created

6. Launch a Facebook Campaign

Create a Facebook Campaign

Facebook ads cannot be combined with Web ads, so you’ll need to create a campaign specific to Facebook.

To create a Facebook campaign, call POST /facebook/campaigns/.

Request:

curl -H 'Authorization: Token YOUR_TOKEN' \
-H 'Content-Type: application/json' \
-d '{
      "advertisable_eid": "CEB5CCB477171F02AD0D8E",
      "name": "My First Facebook Campaign",
      "objective": "CONVERSIONS",
    }' \
https://services.adroll.com/facebook/campaigns/?apikey=MYAPIKEY

Response:

{
  "eid": "EC548FCCCEF01779BD622D",
  "created_date": "2018-02-08T23:47:33+00:00",
  "updated_date": "2018-02-08T23:47:33+00:00",
  "name": "Test Facebook Campaign",
  "objective": "CONVERSIONS",
  "external_id": null,
  "status": "draft",
  "bid_strategy": "automatic",
  "performance_target_value": 5,
  "performance_target": null,
  "goal": "retarget",
  "advertiser": {
    "eid": "CEB5CCB477171F02AD0D8E",
    "name": "test",
    "url": "http://test.com"
  },
  "advertisable": {
    "eid": "CEB5CCB477171F02AD0D8E",
    "name": "test",
    "url": "http://test.com"
  },
  "adsets": [
    {
      "ads": [],
      "audiences": [],
      "eid": "3ABA8BD0A95194270D505A",
      "bid_amount": 5,
      "billing_event": "IMPRESSIONS",
      "pricing_model": "dynamic",
      "cpc": null,
      "budget": 300,
      "created_date": "2018-02-08T23:47:33+00:00",
      "is_autobid": true,
      "pacing_type": "standard",
      "name": "AdGroup 1",
      "optimization_goal": "IMPRESSIONS",
      "promoted_object": null,
      "start_date": "2018-02-08T23:47:33+00:00",
      "end_date": null,
      "status": "draft",
      "ui_period": "weekly",
      "updated_date": "2018-02-08T23:47:33+00:00",
      "targeting": {
        "page_types": [
          "desktopfeed",
          "mobilefeed",
          "rightcolumn",
          "mobileexternal",
          "instagramstream"
        ]
      },
      "min_age": null,
      "max_age": null,
      "campaign_eid": "088B7C20524113A93C9961"
    }
  ],
  "source": null
}

Create an AdSet

To create an AdSet for the Facebook campaign, call POST /facebook/adsets/.

If you created ads before your AdGroup, you can place them in the AdGroup at creation time using the ads parameter.

Request:

curl -H 'Authorization: Token YOUR_TOKEN' \
-H 'Content-Type: application/json' \
-d '{
  "campaign_eid": "EC548FCCCEF01779BD622D",
  "name": "Test AdSet",
  "optimization_goal": "LINK_CLICKS",
  "budget": "100.00",
  "audiences": [
    {
      "custom_audience_eid": "X6ACASEG2JE3HC3J6BVBVS",
      "targeted": true
    }
  ]
}' \
https://services.adroll.com/facebook/adsets/?apikey=MYAPIKEY

Response:

{
  "ads": [],
  "audiences": [
    {
      "eid": "OOHRX3IOPNEQBEZSPO8C4G",
      "created_date": "2018-02-10T00:56:29+00:00",
      "custom_audience_eid": "X6ACASEG2JE3HC3J6BVBVS",
      "targeted": true,
      "updated_date": "2018-02-10T00:56:29+00:00"
    }
  ],
  "eid": "PSGD4NUZLVHB5OTGTO8C4G",
  "bid_amount": 5,
  "billing_event": "IMPRESSIONS",
  "pricing_model": "dynamic",
  "cpc": null,
  "budget": 100,
  "created_date": "2018-02-10T00:56:29+00:00",
  "is_autobid": true,
  "pacing_type": "standard",
  "name": "Test AdSet",
  "optimization_goal": "LINK_CLICKS",
  "promoted_object": null,
  "start_date": "2018-02-10T00:56:29+00:00",
  "end_date": null,
  "status": "draft",
  "ui_period": "weekly",
  "updated_date": "2018-02-10T00:56:29+00:00",
  "targeting": {
    "page_types": [
      "desktopfeed",
      "mobilefeed",
      "rightcolumn",
      "mobileexternal",
      "instagramstream"
    ]
  },
  "min_age": null,
  "max_age": null,
  "campaign_eid": "EC548FCCCEF01779BD622D"
}

Create Facebook Creative

Facebook Creative are CRUD API Ad objects with additional Facebook metadata. All Facebook Creative is created using the POST /api/v1/ad/create endpoint.

The following are the available types:

• Static Ad Creative

• App Install Ad Creative

• Dynamic Product Ad Creative

• Carousel Ad Creative

Static Ad Creative

Facebook Static Ads are created by calling POST /api/v1/ad/create.

Request:

curl -H 'Authorization: Token YOUR_TOKEN' \
    -F advertisable=CEB5CCB477171F02AD0D8E \
    -F name="Test Facebook web ad 300x250" \
    -F destination_url=https://developers.nextroll.com \
    -F file=@600x315.png \
    -F headline="This is the headline" \
    -F body="This is the body" \
    -F message="This is the message" \
    -F call_to_action="SHOP_NOW" \
    https://services.adroll.com/api/v1/ad/create?apikey=MYAPIKEY

Response:

{
  "results": {
    "ad_format": "600 wide x 315 high",
    "ad_format_id": 24,
    "ad_format_name": "600x315 ",
    "ad_parameters": [],
    "adgroups": [],
    "advertisable": "CEB5CCB477171F02AD0D8E",
    "app_id": null,
    "body": "This is the body",
    "body_dynamic": null,
    "call_to_action": "SHOP_NOW",
    "created_date": "2016-10-26 16:35:37",
    "destination_url": "https://developers.nextroll.com",
    "eid": "C451556324220B455FF2B9",
    "has_edits": false,
    "has_future_campaigns": false,
    "has_pending_edits": false,
    "headline": "This is the headline",
    "headline_dynamic": null,
    "height": 315,
    "inventory_type": "fbx",
    "is_active": true,
    "is_fb_dynamic": false,
    "is_liquid": null,
    "is_outlined": false,
    "lead_gen_form_id": null,
    "message": "This is the message",
    "message_dynamic": null,
    "multi_share_optimized": null,
    "multiple_products": null,
    "name": "Test Facebook web ad 300x250",
    "original_ad": null,
    "original_filename": "600x315.png",
    "outline_color": null,
    "replacement_ad": null,
    "src": "https://s.adroll.com/a/M4O/A6S/C451556324220B455FF2B9.png?v=2016-10-26 16:35:37.917069",
    "status": "admin_review",
    "type": "image",
    "updated_date": "2016-10-26 16:35:37",
    "valid_clicktag": true,
    "width": 600
  }
}

App Install Ad Creative

Facebook App Install Ads drive users to install your mobile applications. To create an App Install ad, call POST /api/v1/ad/create.

Request:

curl -H 'Authorization: Token YOUR_TOKEN' \
    -F advertisable=CEB5CCB477171F02AD0D8E \
    -F name="Test Facebook App Install Ad 1200x627" \
    -F destination_url=https://play.google.com/store/apps/details?id=com.adroll.example \
    -F file=@1200x627.png \
    -F headline="This is the headline" \
    -F message="This is the message" \
    -F app_id="11111111111" \
    https://services.adroll.com/api/v1/ad/create?apikey=MYAPIKEY

Response:

{
  "results": {
    "ad_format": "1200 wide x 627 high",
    "ad_format_id": 25,
    "ad_format_name": "1200x627 ",
    "ad_parameters": [],
    "adgroups": [],
    "advertisable": "CEB5CCB477171F02AD0D8E",
    "app_id": "11111111111",
    "body": null,
    "body_dynamic": null,
    "call_to_action": "",
    "created_date": "2016-10-26 16:50:14",
    "destination_url": "https://play.google.com/store/apps/details?id=com.philips.lighting.hue2",
    "eid": "BE9EAF745772ABC15B802B",
    "has_edits": false,
    "has_future_campaigns": false,
    "has_pending_edits": false,
    "headline": "This is the headline",
    "headline_dynamic": null,
    "height": 627,
    "inventory_type": "fbx",
    "is_active": true,
    "is_fb_dynamic": false,
    "is_liquid": null,
    "is_outlined": false,
    "lead_gen_form_id": null,
    "message": "This is the message",
    "message_dynamic": null,
    "multi_share_optimized": null,
    "multiple_products": null,
    "name": "Test Facebook App Install Ad 1200x627",
    "original_ad": null,
    "original_filename": "1200x627.png",
    "outline_color": null,
    "replacement_ad": null,
    "src": "https://s.adroll.com/a/AH6/EIM/BE9EAF745772ABC15B802B.png?v=2016-10-26 16:50:14.964838",
    "status": "admin_review",
    "type": "image",
    "updated_date": "2016-10-26 16:50:14",
    "valid_clicktag": true,
    "width": 1200
  }
}

Dynamic Product Ad Creative

Dynamic Product Ads feature previously-viewed, recommended, and top products. Product details are populated via product feeds you host on your server. Before you can run Dynamic Product Ads, you must first setup your product feed. Once setup you can call POST /api/v1/ad/create to create a Dynamic Product Ad.

To have the ad display multiple products at a time, set multiple_products to the number of products that should be displayed: 0, 3, 4, or 5.

Request:

curl -H 'Authorization: Token YOUR_TOKEN' \
    -F advertisable=CEB5CCB477171F02AD0D8E \
    -F name="Facebook Dynamic Product Ad" \
    -F is_fb_dynamic="true" \
    -F headline_dynamic="This is the headline" \
    -F body_dynamic="This is the body" \
    -F message_dynamic="This is the message" \
    -F call_to_action="SHOP_NOW" \
    -F file=@600x315.png \
    https://services.adroll.com/api/v1/ad/create?apikey=MYAPIKEY

Response:

{
  "results": {
    "ad_format": "600 wide x 315 high",
    "ad_format_id": 24,
    "ad_format_name": "600x315 ",
    "ad_parameters": [],
    "adgroups": [],
    "advertisable": "M7B2HEGCWBCSZG45EX6Q3K",
    "app_id": null,
    "body": null,
    "body_dynamic": "This is the body",
    "call_to_action": "SHOP_NOW",
    "created_date": "2016-10-28 21:44:21",
    "destination_url": "",
    "eid": "74A0F09220C278C9AF3600",
    "has_edits": false,
    "has_future_campaigns": false,
    "has_pending_edits": false,
    "headline": null,
    "headline_dynamic": "This is the headline",
    "height": 315,
    "inventory_type": "fbx",
    "is_active": false,
    "is_fb_dynamic": true,
    "is_liquid": null,
    "is_outlined": false,
    "lead_gen_form_id": null,
    "message": null,
    "message_dynamic": "This is the message",
    "multi_share_optimized": null,
    "multiple_products": 3,
    "name": "Facebook Dynamic Product Ad",
    "original_ad": null,
    "original_filename": "600x315.png",
    "outline_color": null,
    "replacement_ad": null,
    "src": "https://s.adroll.com/a/IA3/GWC/74A0F09220C278C9AF3600.png?v=2016-10-28 21:44:21.951907",
    "status": "admin_review",
    "type": "image",
    "updated_date": "2016-10-28 21:44:21",
    "valid_clicktag": true,
    "width": 600
  }
}

Carousel Ad Creative

Facebook and Instagram Carousel Ads allow you to showcase multiple images with links within a single ad unit.

Create Child Ads

The first step is to create child ads that will be included in the carousel.

To create a child ad for Instagram use instagram_carousel_child as the type parameter, for Facebook use carousel_child.

Call POST /api/v1/ad/create

Request:

curl -H 'Authorization: Token YOUR_TOKEN' \
    -F advertisable=CEB5CCB477171F02AD0D8E \
    -F type="carousel_child" \
    -F name="Test Child Ad 1" \
    -F destination_url=https://developers.nextroll.com \
    -F file=@300x250.png \
    https://services.adroll.com/api/v1/ad/create?apikey=MYAPIKEY

Create the Carousel Ad

Once you’ve created your child ads, you can create the parent Carousel Ad.

Set multi_share_optimized to true if Facebook should optimize the order of the images or false if you want to keep the order in which you uploaded them.

Use child_ads to attach the child ads to the partner ad.

To create a carousel ad for Instagram use instagram_carousel as the type parameter, for Facebook use carousel.

Call POST /api/v1/ad/create

Request:

curl -H 'Authorization: Token YOUR_TOKEN' \
    -F advertisable=CEB5CCB477171F02AD0D8E \
    -F type="carousel" \
    -F name="Test Carousel Ad" \
    -F destination_url=https://developers.nextroll.com \
    -F child_ads="3Z3LNHZIHVHJDN65ENQU57,XN6HRJ7NXVGVDGPJRTK7VY,LZV4RRTOMZAQ3MAKNCVTD2" \
    https://services.adroll.com/api/v1/ad/create?apikey=MYAPIKEY

Create Facebook Ads

Facebook Ads join together Facebook Creative (aka CRUD API Ad objects) to Facebook AdSets. This is done by calling POST /facebook/ads/.

Request:

curl -H 'Authorization: Token YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Test Ad",
    "creative_eid": "894F79057F902F2BF2D39B",
    "adset_eid": "40074E9F7C06CB0AD3F510",
    "status": "active"
  }' \
  https://app.adroll.com/facebook/ads/

Response:

{
  "eid": "63CC2A54974EED301078D1",
  "created_date": "2018-02-13T21:41:32+00:00",
  "updated_date": "2018-02-13T21:41:32+00:00",
  "name": "Test AdSet",
  "creative_eid": "81DC94F69B5E80BEADB386",
  "adset_eid": "F7AD3BC25F596310861725",
  "status": "active",
  "is_active": true,
  "remote_status": null,
  "disapproval_reason": null
}

Launch a Facebook Campaign

When you’re ready to launch your campaign, you can call PUT /facebook/campaigns/(eid)

Request:

curl -H 'Authorization: Token YOUR_TOKEN' \
  -X PUT
  -H 'Content-Type: application/json' \
  -d '{
    "should_launch": true
  }' \
  https://app.adroll.com/facebook/campaigns/7EE38320ABAD83CDEA1858