Automated App Ads API

Automated App Ads use machine learning and automated systems to drive more results for your app install ads. This solution helps you scale campaigns and, ultimately, it makes your work more efficient.

To use Automated App Ads, your ad campaigns need to be set up in a 1:1:1 structure: 1 ad campaign, 1 ad set, and 1 ad. See the comparison between regular App Ads and Automated App Ads:

Manual App AdsAutomated App Ads
1 Campaign
Multiple ad sets
Multiple ads
1 campaign
1 ad set
1 ad

Reliance on manual adjustments.

Reliance on machine learning adjustments.

Manually test up to 50 creative combinations.

Dynamically test up to 50x5x5 creative combinations.

Automated App Ads SKAdNetwork Campaigns targeting iOS 14 users are now available.

Before You Start

To use Automated App Ads, you need:

  • A Facebook developer account
  • A Facebook app
  • The following permissions: ads_management and ads_read

You must be authorized to make GET and POST calls to the ad account used to fund your ads.

Step 1: Create Campaign

Send a POST request to /act_{ad_account_id}/campaigns with the following required, and optional, parameters:

ParameterDescription
adlabels
list of objects

Ad Labels associated with the Automated App Ads campaign. Optional.

buying_type
string

Currently, Automated App Ads only supports the buying_type AUCTION. Required.

execution_options
list of enums

Default value: set. Other options are:

  • validate_only: when this option is specified, the API call will not perform the mutation but will run through the validation rules against values of each field.
  • include_recommendations: this option cannot be used by itself. When this option is used, recommendations for ad object's configuration will be included. A separate section recommendations will be included in the response, but only if recommendations for this specification exist.

If the call passes validation or review, the response will be {"success": true}. If the call does not pass, an error is returned with more details. Optional.

is_skadnetwork_attribution
string

Identifies a SKAdsNetwork Campaign. Optional

name
string

Name for the Automated App Ads campaign.

objective
enum

This is the campaign goal. Specify APP_INSTALLS for this type of ads. Required.

promoted_object
object

The object this ad set is promoting across all its ads. For Automated App Ads, provide:

  • application_id and object_store_url, or
  • application_id, object_store_url, and custom_event_type (if your optimization goal is not APP_INSTALLS).

Required if is_skadnetwork_attribution is set to true.

smart_promotion_type
list of objects

To specify this is an Automated App Ads campaign, smart promotion type should be set to SMART_APP_PROMOTION. Optional.

special_ad_categories
list of objects

Automated App Ads currently does not support special ad categories. Please specify this as an empty list, like so []. Required.

status
enum

Valid options are: PAUSED and ACTIVE.

If this status is PAUSED, all its active ad sets and ads will be paused and have an effective status CAMPAIGN_PAUSED. Required.

topline_id
numeric string or integer

Topline ID. Optional.

Campaign Creation Call Example

curl -X POST \
  -F 'name=Automated App Ads Sample Campaign' \
  -F 'objective=APP_INSTALLS' \
  -F 'status=ACTIVE' \
  -F 'special_ad_categories=[]' \
  -F 'smart_promotion_type=SMART_APP_PROMOTION' \
  -F 'access_token={access-token}' \
https://graph.facebook.com/v10.0/act_{ad-account-id}/campaign

If you already have a campaign and want to update it, see After Launch, Update Campaign.

Step 2: Verify Campaign Creation (Optional)

As an option, you can check if you have successfully created an Automated App Ad Campaign. To do that, make a GET request to /{ad-campaign-id} with the field smart_promotion_type. A valid Automated App Ad Campaign returns SMART_APP_PROMOTION.

Campaign Verification Call Example

curl -X GET -G \
  -d 'fields="smart_promotion_type"' \
  -d 'access_token={access-token}' \
https://graph.facebook.com/v10.0/{ad-campaign-id}

Example response, if a valid Automated App Ad Campaign was created:

{
  "smart_promotion_type": "SMART_APP_PROMOTION",
  "id": {ad-campaign-id}
}

Step 3: Create Ad Set

Once you have an ad campaign, create your ad set. An ad set is a group of ads that share the same daily or lifetime budget, schedule, bid type, bid info, and targeting data.

To create an ad set, make a POST request to /act_{ad_account_id}/adsets. You may include the following parameters:

ParameterDescription
billing_event
enum

The billing event that this ad set is using. For Automated App Aps, specify IMPRESSIONS. Required.

campaign_id
numeric string or integer

The ID for a valid Automated App Ads ad campaign you wish to add this ad set to. Required.

name
string

Name for the Automated App Ads ad set. Required.

optimization_goal
enum

What the ad set is optimizing for. Automated App Ads supports the following optimization goals:

  • APP_INSTALLS: Optimizes for people more likely to install your app.
  • OFFSITE_CONVERSIONS: Optimizes for people more likely to make a conversion in your site.
  • APP_INSTALLS_AND_OFFSITE_CONVERSIONS: Optimizes for people more likely to install your app and make a conversion in your site.
  • VALUE: Optimizes for maximum total purchase value within the specified attribution window.
Required.
promoted_object
object

The object this ad set is promoting across all its ads. For Automated App Ads, provide:

  • application_id and object_store_url, or
  • application_id, object_store_url, and custom_event_type (if your optimization goal is not APP_INSTALLS).

Required for all campaigns except SKAdNetwork Campaign. Optional for SKAdNetwork Campaign.

targeting

targeting object

An Automated App Ad ad set’s targeting structure. Valid targeting options are geo_locations and locales. See Targeting Fields.


For example:

{
   "geo_location": {
     "countries": [“US”]
     },
   "locales": [8]
}

Automated App Ads do not support operating system targeting, however SKAdsNetwork Automated App Ad campaigns will only target iOS14.5+ users.

Required.

bid_strategy

enum

Choose a bid strategy for this ad set to suit your specific business goals. Each strategy has tradeoffs and may be available for certain optimization_goals. See Bidding Overview, Bid Strategies for more information.


For Automated App Ads, the following strategies are available:

  • LOWEST_COST_WITHOUT_CAP
  • LOWEST_COST_WITH_BID_CAP
  • LOWEST_COST_WITH_MIN_ROAS
Required.

bid_constraints

list of objects

Required if bid_strategy is set to lowest_cost_with_min_roas.

Similar to an ad set budget, minimum Return on Ads Spend (ROAS) bidding uses this to provide the ROAS floor, but you cannot use bid_amount with bid_constraints.

bid_amount

integer

Required if bid_strategy is set to LOWEST_COST_WITH_BID_CAP.

Bid cap or target cost for this ad set. The bid cap used in a lowest cost bid strategy is defined as the maximum bid you want to pay for a result based on your optimization_goal. The target cost used in a target cost bid strategy lets Facebook bid to meet your target on average and keep costs stable as you spend.


If an ad level bid_amount is specified, updating this value will overwrite the previous ad level bid.


The bid amount's unit is cents for currencies like USD, EUR, and the basic unit for currencies like JPY, KRW. The bid amount is for each occurrence, and has a minimum value 1 US cents. The minimum bid amounts of other currencies are of similar value to the US Dollar values provided.

status

enum

Only ACTIVE and PAUSED are valid for creation. The other statuses can be used for updates. If an ad set is set to PAUSED, all its active ads will be paused and have an effective status ADSET_PAUSED.

Required.

daily_budget

int64

The daily budget defined in your account currency, allowed only for ad sets with a duration (difference between end_time and start_time) longer than 24 hours.

Either daily_budget or lifetime_budget must be greater than 0.

Optional.

lifetime_budget

int64

Lifetime budget, defined in your account currency. If specified, you must also specify an end_time.

Either daily_budget or lifetime_budget must be greater than 0.

Optional.

end_time

datetime

Required when lifetime_budget is specified.

When creating an ad set with a daily_budget, specify end_time=0 to set the ad set as ongoing with no end date. Time should be provided in UTC UNIX timestamp.


For example: 2015-03-12 23:59:59-07:00 or 2015-03-12 23:59:59 PDT.

adlabels

list of objects

Specifies list of labels to be associated with this object.

Optional.

start_time

datetime

The start time of the set. For example: 2015-03-12 23:59:59-07:00 or 2015-03-12 23:59:59 PDT. Must be provided as a UTC UNIX timestamp.

time_stop

datetime

Time to stop running this ad set.

time_start

datetime

Time to start running this ad set.

Targeting Fields

ParameterDescription

geo_locations

array

Used to limit the audience of the ad set via the required argument countries. Valid value: countries. An array of 2 digit ISO 3166 format codes.

Required.

locales

array

Target people with language other than common language for a location. To use this field, provide an ID for the language, such as 5 for German. See Targeting Search, Locales for more information.

Ad Set Creation Call Example

curl -X POST \
  -F 'name=Automated App Ads Sample Ad Set' \
  -F 'campaign_id={campaign-id}' \
  -F 'optimization_goal=APP_INSTALLS' \
  -F 'promoted_object={ "application_id": "{app-id}", "object_store_url": "{store-object-id} }' \
  -F 'daily_budget=<num>' \
  -F 'billing_event=IMPRESSIONS' \
  -F 'targeting={"geo_locations": {"countries": ["US"]}}' \
  -F 'access_token={access-token}' \
https://graph.facebook.com/v10.0/act_{ad-account-id}/adsets

If you already have an ad set and want to update it, see After Launch, Update Ad Sets.

Optimization Compatibility

At the ad set level, you must specify optimization goal, bid strategy and custom event type. The following table outlines valid combinations of these fields.

Optimization GoalBid StrategyCustom Event Type

APP_INSTALLS

LOWEST_COST_WITHOUT_CAP and LOWEST_COST_WITH_BID_CAP

Not applicable.

OFFSITE_CONVERSIONS

LOWEST_COST_WITHOUT_CAP and LOWEST_COST_WITH_BID_CAP

All standard app events, including PURCHASE, ADD_TO_CART, INITIATED_CHECKOUT, and more.

APP_INSTALLS_AND_OFFSITE_CONVERSIONS

LOWEST_COST_WITHOUT_CAP

PURCHASE

VALUE

LOWEST_COST_WITHOUT_CAP and LOWEST_COST_WITH_MIN_ROAS

PURCHASE

SKAdNetwork Set Creation Call Example

curl -X POST \
  -F 'name=Automated App Ads Sample Campaign' \
  -F 'objective=APP_INSTALLS' \
  -F 'status=ACTIVE' \
  -F 'special_ad_categories=[]' \
  -F 'smart_promotion_type=SMART_APP_PROMOTION' \
  -F 'is_skadnetwork_attribution=true' \
  -F 'promoted_object={ "application_id": "{app-id}", "object_store_url": "{object-store-url}" }' \ 
  -F 'access_token={access-token}' \
https://graph.facebook.com/act_{ad-account-id}/campaign

Step 4: Provide Creative and Create Ads

Once you have an ad set, you can create your ad by posting to the /act_{ad_account_id}/ads endpoint. You may include the following parameters:

ParameterDescription

name

string

Name of the ad.

Required.

adset_id

int64

The ID of the ad set.

Required.

creative

AdCreative

The creative spec of the ad creative to be used by this ad. Valid fields are object_story_spec, asset_feed_spec, and use_page_actor_override. See Creative Fields for more information.

Required.

Provide a creative spec:

{
  "creative": {
    \"name\": \"<NAME>\", 
    \"object_story_spec\": <SPEC>
  }
}

status

AdCreative

type: enum

Valid options during creation: ACTIVE and PAUSED. During testing, it is recommended to set ads to a PAUSED status so as to not incur accidental spend.

Required.

adlabels

list of objects

Ad labels associated with this ad. Optional.

execution_options

list of enums

Default value: set. Other options are:

  • validate_only: when this option is specified, the API call does not perform the mutation but runs through the validation rules against values of each field.
  • synchronous_ad_review: this option should not be used by itself. It should always be specified with validate_only. When these options are specified, the API call performs Ads Integrity validations, which include message language checking, image 20% text rule, and so on, as well as the validation logics.
  • include_recommendations: this option cannot be used by itself. When this option is used, recommendations for ad object's configuration will be included. A separate section recommendations will be included in the response, but only if recommendations for this specification exist.

If the call passes validation or review, the response will be {"success": true}. If the call does not pass, an error will be returned with more details. Optional.

Creative Fields

ParameterDescription

object_story_spec

AdCreativeObjectStorySpec

Use if you want to create a new unpublished page post and turn the post into an ad. The Page ID and the content to create a new unpublished page post.

Required.

Available fields:

  • page_id (type: numeric string) - Required. ID of a Facebook page. An unpublished page post will be created on this page. Users must have Admin or Editor role for this page
  • instagram_actor_id (type: numeric string) - Optional. The Instagram user account that the story will be posted to.

asset_feed_spec

AdAssetFeedSpec

Used for Dynamic Creative to automatically experiment and deliver different variations of an ad's creative. Specifies an asset feed with multiple images, text and other assets used to generate variations of an ad. Formatted as a JSON string.


Available fields:

  • images (type: list of AdAssetFeedSpecImage) - Ad image asset spec in asset feed spec.
  • videos (type: list of AdAssetFeedSpecVideo) - Ad video asset spec in asset feed spec.
  • bodies (type: list of AdAssetFeedSpecBody) - Ad body asset spec in asset feed spec.
  • titles (type: list of AdAssetFeedSpecTitle) -
  • call_to_action_types (type: list of enums) - Ad call to action spec in asset feed spec. Available options for Automated App Ads are: SHOP_NOW, SIGN_UP, USE_APP, WATCH_MORE, SUBSCRIBE, BOOK_TRAVEL, DOWNLOAD, INSTALL_MOBILE_APP, LEARN_MORE, LISTEN_NOW, and PLAY_GAME.

use_page_actor_override

AdCreative

If set to true, we display the Facebook page associated with the App Ads.

Ad Creation Call Example

If you provide your creative formatted as creative spec:

curl -X POST \
  -F 'name=Automated App Ads Sample Ad' \
  -F 'adset_id={adset-id}' \
  -F 'creative={"creative": {"name": {name}, "object_story_spec": {specifications}}}' \
  -F 'access_token={access-token}' \
https://graph.facebook.com/v10.0/act_{ad-account-id}/ads

If you already have an ad and want to update it, go to After Launch, Update Ads.

After Launch

After you launch your Automated App Ads, you may need to update or read your ad objects. See how to perform those actions below.

Update Campaigns

If you need to update an Automatic App Ads campaign, make a POST request to /{campaign_id}. You can use the following parameters in your API call:

ParameterDescription

name

string

New name you would like to give to your Automated App Ads campaign.

adlabels

list of object

Ad Labels that should be associated with the Automated App Ads campaign.

execution_options

list of enums

Default value: set. Other available options are:

  • validate_only: when this option is specified, the API call will not perform the mutation but will run through the validation rules against values of each field.
  • include_recommendations: this option cannot be used by itself. When this option is used, recommendations for ad object's configuration will be included. A separate section recommendations will be included in the response, but only if recommendations for this specification exist.

If the call passes validation or review, the response is {"success": true}. If the call does not pass, an error is returned with more details.

topline_id

numeric string or integer

Topline ID.

status

enum

You can use the following status for an update API call:

  • ACTIVE
  • PAUSED
  • DELETED
  • ARCHIVED

If an ad campaign is set to PAUSED, its active child objects will be paused and have an effective status CAMPAIGN_PAUSED.

Campaign Update Example

curl -X POST \
-F 'name=Automated App Ads Update Sample Campaign' \
-F 'status=PAUSED' \
-F 'access_token={access-token}' \
https://graph.facebook.com/v10.0/{campaign-id}

Update Ad Sets

If you need to update an Automatic App Ads ad set, make a POST request to /{ad_set_id}. You can use the following parameters in your API call:

ParameterDescription

adlabels

list of objects

Specifies list of labels to be associated with this object. Optional.

bid_strategy

enum

Choose a bid strategy for this ad set to suit your specific business goals. Each strategy has tradeoffs and may be available for certain optimization_goals. See Bidding Overview, Bid Strategies for more information.

To update Automated App ad sets, the following strategies are available:

  • LOWEST_COST_WITHOUT_CAP
  • LOWEST_COST_WITH_BID_CAP

If you enable Campaign Budget Optimization, set bid_strategy at the parent campaign level.

bid_amount

integer

Required if bid_strategy is set to LOWEST_COST_WITH_BID_CAP.

Bid cap or target cost for this ad set. The bid cap used in a lowest cost bid strategy is defined as the maximum bid you want to pay for a result based on your optimization_goal. The target cost used in a target cost bid strategy lets Facebook bid to meet your target on average and keep costs stable as you spend.


If an ad level bid_amount is specified, updating this value will overwrite the previous ad level bid.


The bid amount's unit is cents for currencies like USD, EUR, and the basic unit for currencies like JPY, KRW. The bid amount is for each occurrence, and has a minimum value 1 US cents. The minimum bid amounts of other currencies are of similar value to the US Dollar values provided.

daily_budget

int64

The daily budget defined in your account currency, allowed only for ad sets with a duration (difference between end_time and start_time) longer than 24 hours. Either daily_budget or lifetime_budget must be greater than 0.

end_time

datetime

End time, required when lifetime_budget is specified. Must be provided in UTC UNIX timestamp. For example: 2015-03-12 23:59:59-07:00 or 2015-03-12 23:59:59 PDT.


When creating an ad set with a daily budget, specify end_time=0 to set the ad set as ongoing with no end date.

execution_options

list of enums

Optional.

Default value: set. Other options are:

  • validate_only: when this option is specified, the API call will not perform the mutation but will run through the validation rules against values of each field.
  • include_recommendations: this option cannot be used by itself. When this option is used, recommendations for ad object's configuration will be included. A separate section recommendations will be included in the response, but only if recommendations for this specification exist.

If the call passes validation or review, the response is {"success": true}. If the call does not pass, an error is returned with more details.

promoted_object

object

Required with certain campaign objectives.

The object this ad set is promoting across all its ads. Available options are:

  • APP_INSTALLS
  • custom_event_type (if the optimization_goal is not APP_INSTALLS)

start_time

datetime

The start time of the set. Must be provided in UTC UNIX timestamp. For example: 2015-03-12 23:59:59-07:00 or 2015-03-12 23:59:59 PDT.

status

enum

Available options for updates:

  • ACTIVE
  • PAUSED
  • DELETED
  • ARCHIVED

lifetime_budget

int64

Lifetime budget, defined in your account currency. If specified, you must also specify an end_time. Either daily_budget or lifetime_budget must be greater than 0.

time_start

datetime

Time to start running this ad set.

time_stop

datetime

Time to stop running this ad set.

Ad Set Update Example

curl -X POST \
  -F 'name=Automated App Ads Sample Updated Ad Set' \
  -F 'bid_strategy=LOWEST_COST_WITH_BID_CAP' \
  -F 'bid_amount=200' \
  -F 'access_token={access-token}' \
https://graph.facebook.com/v10.0/{ad-set-id}

Update Ads

If you need to update an Automatic App Ads ad, make a POST request to /{ad_id}. You can use the following parameters in your API call:

ParameterDescription

name

string

Name of the ad.

adlabels

list of objects

Ad labels associated with this ad.

execution_options

list of enums

Optional.

Default value: set. Other options are:

  • validate_only: when this option is specified, the API call does not perform the mutation but runs through the validation rules against values of each field.
  • synchronous_ad_review: this option should not be used by itself. It should always be specified with validate_only. When these options are specified, the API call performs ads integrity validations, which include message language checking, image 20% text rule, and so on, as well as the validation logics.
  • include_recommendations: this option cannot be used by itself. When this option is used, recommendations for an object's configuration are included. A separate section recommendations is included in the response, but only if recommendations for this specification exist.

If the call passes validation or review, the response is {"success": true}. If the call does not pass, an error is returned with more details.

status

enum

Options are:

  • ACTIVE
  • PAUSED
  • DELETED
  • ARCHIVED

During testing, it is recommended to set ads to a PAUSED status so as to not incur accidental spend.

creative

AdCreative

The creative spec of the ad creative to be used by this ad. Valid fields can be found on Creative Fields. Provide the creative spec as follows:

{
  "creative": {
    \"name\": \"<NAME>\", 
    \"object_story_spec\": <SPEC>
   }
}

Ad Update Example

curl -X POST \
-F 'name=Automated App Ads Sample Update Ad' \
-F 'creative={"creative": {"name": {name}, "object_story_spec": {specifications}}}' \
-F 'access_token={access-token}' \
https://graph.facebook.com/v10.0/{ad-id}

See Ad Asynchronous Batch Requests to update ads with multiple videos or images.

Troubleshooting

While uploading a high quantity of videos to your Automated App Ad creative spec, you may encounter one of the following errors:

  • Error Code 1: An unknown error occurred
  • Service temporarily unavailable
  • Error Code 2: An unexpected error has occurred. Please retry your request later.

If you see one of these errors, you can try one of the following solutions:

Solution 1: Use Async Batch Requests

Use asynchronous batch requests to make multiple Graph API calls in a single HTTP request —learn more about Asynchronous Batch Requests.

Use Async To Create Ads

Below is an example of an async batch request being used to create an Automated App Ads campaign ad with multiple videos:

curl -F 'access_token=<ACCESS_TOKEN>' \  
     -F 'asyncbatch=[{
          "method":"POST",
          "relative_url":"act_{ad_account_id}/ads",
          "body":"name":"Example Async Update Ad",
                 "creative={
                   "object_story_spec": {
                     "page_id": "<PAGE_ID>",
                    },
                  "asset_feed_spec": {
                    "videos": [
                      {
                       "url_tags": "example_url_tag_123",
                       "video_id": "<VIDEO_ID>",
                       "thumbnail_url": "https://www.facebook.com/ads/image/?d=<HASH>",
                       "thumbnail_hash": "1a2b3c4d"
                      },
                     ],
                 }
              }
         }]' \
https://graph.facebook.com/v10.0

The response returns an async_session_id, which you can then use to fetch the query results.

Use Async To Update Ads

To update an existing ad, change the relative_url to the "{ad_id}". Learn more about using an async request to update an ad here.

Solution 2: Use Ad Images

Using external thumbnail_urls for a large quantity of creatives can also cause potential timeout issues. To prevent this from happening, you can upload and manage images to later use in ad creative via Ad Images.

To use this solution, make a POST request to /adimages edge from the following path /act_{ad_account_id}/adimages.

When you post to this edge, an AdImage is created, returning an url and hash, which you can then use to create your video within the ad creative asset feed of your ad like so:

"asset_feed_spec": {
  "videos": [
    { 
     "url_tags": "example_tag_123",
     "video_id": "123456789",
     "thumbnail_url": "<url>",
     "thumbnail_hash": "<hash>"
    },
  ],
}