Marketing API Version

Ad

Contains information to display an ad and associate it an ad set. Each ad is associated with an ad set and all ads in a set have the same daily or lifetime budget, schedule, and targeting. Creating multiple ads in an ad set helps optimize their delivery based on variations in images, links, video, text or placements.

Creating an ad:

use FacebookAds\Object\AdCreative;
use FacebookAds\Object\Ad;
use FacebookAds\Object\Fields\AdCreativeFields;
use FacebookAds\Object\Fields\AdFields;

// First, upload the ad image that you will use in your ad creative
// Please refer to Ad Image Create for details.

// Then, use the image hash returned from above
$creative = new AdCreative(null, 'act_<AD_ACCOUNT_ID>');
$creative->setData(array(
  AdCreativeFields::TITLE => 'My Test Creative',
  AdCreativeFields::BODY => 'My Test Ad Creative Body',
  AdCreativeFields::OBJECT_URL => 'https://www.facebook.com/facebook',
  AdCreativeFields::IMAGE_HASH => '<IMAGE_HASH>',
));

// Finally, create your ad along with ad creative.
// Please note that the ad creative is not created independently, rather its
// data structure is appended to the ad group
$ad = new Ad(null, 'act_<AD_ACCOUNT_ID>');
$ad->setData(array(
  AdFields::NAME => 'My Ad',
  AdFields::ADSET_ID => <AD_SET_ID>,
  AdFields::CREATIVE => $creative,
));
$ad->create(array(
  Ad::STATUS_PARAM_NAME => Ad::STATUS_PAUSED,
));
from facebookads.adobjects.ad import Ad
from facebookads.adobjects.adcreative import AdCreative

# First, upload the ad image that you will use in your ad creative
# Please refer to Ad Image Create for details.

# Then, use the image hash returned from above
creative = AdCreative(parent_id='act_<AD_ACCOUNT_ID>')
creative[AdCreative.Field.title] = 'My Test Creative'
creative[AdCreative.Field.body] = 'My Test Ad Creative Body'
creative[AdCreative.Field.object_url] = 'https://www.facebook.com/facebook'
creative[AdCreative.Field.image_hash] = '<IMAGE_HASH>'

# Finally, create your ad along with ad creative.
# Please note that the ad creative is not created independently, rather its
# data structure is appended to the ad group
ad = Ad(parent_id='act_<AD_ACCOUNT_ID>')
ad[Ad.Field.name] = 'My Ad'
ad[Ad.Field.adset_id] = <AD_SET_ID>
ad[Ad.Field.creative] = creative
ad.remote_create(params={
    'status': Ad.Status.paused,
})
// Upload image for your ad creative
curl \
-F "image.jpg=@myimage.jpg" \
-F "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/adimages"

// Provide ad creative with image hash ID returned in previous call
curl \
-F "name=sample creative" \ 
-F "title=hello world" \
-F "body=hi i'm an ad" \
-F "object_url=www.facebook.com" \ 
-F "image_hash=<IMAGE_HASH>" \
-F "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/adcreatives"

  // Create ad with ad creative. 
curl \
-F "name=my ad" \
-F "adset_id=<AD_SET_ID>" \
-F "creative={'creative_id':<AD_CREATIVE_ID>}" \
-F "status=PAUSED" \
-F "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/ads"

// Asynchronous creation.
curl \
-F "name=testasyncset" \
-F "ad_specs=
[{'name':'name 1', 
  'adset_id':'<AD_SET_ID>', 
  'creative':{'creative_id':<AD_CREATIVE_ID>}},
{'name':'name 2', 
  'adset_id':'<AD_SET_ID>',  
  'creative':{'creative_id':<AD_CREATIVE_ID>}}]" \
-F "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/asyncadrequestsets"

See:

Reading

An ad object contains the data necessary to visually display an ad and associate it with a corresponding ad set.

Permissions

Developers usually request these permissions for this endpoint:

Marketing Apps
  • ads_management
Page management Apps
No data
Other Apps
No data

By ad ID

use FacebookAds\Object\Ad;
use FacebookAds\Object\Fields\AdFields;

$ad = new Ad($ad_id);
$ad->read(array(
  AdFields::NAME,
));

// Output Ad name.
echo $ad->name;
from facebookads.objects import Ad

ad_id = <AD_ID>
ad = Ad(ad_id)
ad.remote_read(fields=[Ad.Field.name])
curl -G \
-d "fields=name" \
-d "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<AD_ID>"

By ad account

To read all ads from one ad account:

use FacebookAds\Object\AdAccount;
use FacebookAds\Object\Fields\AdFields;

$account = new AdAccount($account_id);
$ads = $account->getAds(array(
  AdFields::NAME,
));

// Outputs names of Ads.
foreach ($ads as $ad) {
  echo $ad->name;
}
from facebookads.objects import AdAccount, Ad

account_id = 'act_<AD_ACCOUNT_ID>'
ad_account = AdAccount(account_id)
ad_iter = ad_account.get_ads(fields=[Ad.Field.name])
for ad in ad_iter:
    print ad[Ad.Field.name]
curl -G \
-d "fields=name" \
-d "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/ads"

By ad campaign

Read all ads from a campaign:

use FacebookAds\Object\Campaign;
use FacebookAds\Object\Fields\CampaignFields;

$campaign = new Campaign($campaign_id);
$ads = $campaign->getAds(array(
  AdFields::NAME,
));

// Outputs names of Ads.
foreach ($ads as $ad) {
  echo $ad->name;
}
from facebookads.objects import Campaign, Ad

campaign_id = <CAMPAIGN_ID>
campaign = Campaign(campaign_id)
ad_iter = campaign.get_ads(fields=[Ad.Field.name])
for ad in ad_iter:
    print ad[Ad.Field.name]
curl \
-F "fields=name" \
-F "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<CAMPAIGN_ID>/ads"

By ad set

To read all ads from one ad set:

use FacebookAds\Object\AdSet;
use FacebookAds\Object\Fields\AdSetFields;

$adset = new AdSet($adset_id);
$ads = $adset->getAds(array(
  AdFields::NAME,
));

// Outputs names of Ads .
foreach ($ads as $ad) {
  echo $ad->name;
}
from facebookads.objects import AdSet, Ad

adset_id = <AD_SET_ID>
ad_set = AdSet(adset_id)
ad_iter = ad_set.get_ads(fields=[Ad.Field.name])
for ad in ad_iter:
    print ad[Ad.Field.name]
curl \
-F "fields=name" \
-F "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<AD_SET_ID>/ads"



If you want to learn how to use the Graph API, read our Using Graph API guide.

Parameters

This endpoint doesn't have any parameters.

Fields

FieldDescription

id

numeric string

The ID of this ad.

account_id

numeric string

The ID of the ad account that this ad belongs to.

ad_review_feedback

The review feedback for this ad after it is reviewed.

adlabels

Ad labels associated with this ad

adset

Ad set that contains this ad

adset_id

numeric string

ID of the ad set that contains the ad

bid_amount

int32

Bid amount for this ad which will be used in auction instead of the ad set bid_amount, if specified. Any updates to the ad set bid_amount will overwrite this value with the new ad set value.

bid_info

map<string, unsigned int32>

A dictionary of {objective}:{value} that you place on your bid, based on the bid_type of ad set.
Values are defined in your currency's minimum denomination:
For bid_type=CPM, bid_info={'IMPRESSIONS':<value>}
For bid_type=CPC, bid_info={'CLICKS':<value>}
For bid_type=ABSOLUTE_OCPM, bid_info={'ACTIONS':<value>, 'REACH':<value>, 'CLICKS':<value>, 'SOCIAL':<value>}
For bid_type=CPA, bid_info={'ACTIONS':<value>}

bid_type

enum {CPC, CPM, MULTI_PREMIUM, ABSOLUTE_OCPM, CPA}

Bid type

campaign

Ad campaign that contains this ad

campaign_id

numeric string

ID of the ad campaign that contains this ad

configured_status

enum {ACTIVE, PAUSED, DELETED, ARCHIVED}

The configured status of the ad. Prefer using 'status' instead of this.

conversion_specs

Conversion specs

created_time

datetime

Created time

creative

This field is required for create. The ID of the ad creative to be used by this ad. You can read more about creatives here. You should supply the ID within an object as follows:

{"creative_id": <CREATIVE_ID>}

effective_status

enum {ACTIVE, PAUSED, DELETED, PENDING_REVIEW, DISAPPROVED, PREAPPROVED, PENDING_BILLING_INFO, CAMPAIGN_PAUSED, ARCHIVED, ADSET_PAUSED}

The effective status of the ad. The status could be effective either because of its own status, or the status of its parent units.

last_updated_by_app_id

id

Last Updated By App ID

name

string

Name of the ad.

recommendations

If there are recommendations for this ad, this field includes them. Otherwise, will not be included in the response. (This field is not included in redownload mode.)

status

enum {ACTIVE, PAUSED, DELETED, ARCHIVED}

The configured status of the ad. The field returns the same value as 'configured_status', and is the suggested one to use.

tracking_specs

Tracking specs

updated_time

datetime

Updated time

Edges

EdgeDescription

adcreatives

Creative associated with this ad

insights

Insights on advertising performance of this ad

keywordstats

Stats of keywords of this ad

previews

Preview of the ad

targetingsentencelines

The targeting description sentence for this ad

Validation Rules

ErrorDescription
100Invalid parameter
275Cannot determine the target object for this request. Currently supported objects include ad account, business account and associated objects.
274The ad account is not enabled for usage in Ads API. Please add it in developers.facebook.com/apps -> select your app -> settings -> advanced -> advertising accounts -> Ads API
278Reading advertisements requires an access token with the extended permission ads_read
273This Ads API call requires the user to be admin of the ad account
272This Ads API call requires the user to be admin of the application
200Permissions error

Creating

Before you create an ad, you need an existing ad set and ad creative. You can create ads synchronously and asynchronously.

New ads are in pending state and do not run until Facebook approves or rejects them. After we approve an ad it runs. If you do not want an ad to automatically run after approval, create it and set it to paused, see ad set. Run the set when you are ready.

Synchronous Creation

Creates one ad at a time:

use FacebookAds\Object\Ad;
use FacebookAds\Object\Fields\AdFields;

$data = array(
  AdFields::NAME => 'My Ad',
  AdFields::ADSET_ID => <AD_SET_ID>,
  AdFields::CREATIVE => array(
    'creative_id' => <CREATIVE_ID>,
  ),
);

$ad = new Ad(null, 'act_<AD_ACCOUNT_ID>');
$ad->setData($data);
$ad->create(array(
  Ad::STATUS_PARAM_NAME => Ad::STATUS_PAUSED,
));
from facebookads.adobjects.ad import Ad

ad = Ad(parent_id='act_<AD_ACCOUNT_ID>')
ad[Ad.Field.name] = 'My Ad'
ad[Ad.Field.adset_id] = <AD_SET_ID>
ad[Ad.Field.creative] = {
    'creative_id': <CREATIVE_ID>,
}
ad.remote_create(params={
    'status': Ad.Status.paused,
})
Ad ad = new AdAccount(act_<AD_ACCOUNT_ID>, context).createAd()
  .setName("My Ad")
  .setAdsetId(<AD_SET_ID>)
  .setCreative(
    new AdCreative()
      .setFieldId(<CREATIVE_ID>)
  )
  .setStatus(Ad.EnumStatus.VALUE_PAUSED)
  .execute();
curl \
  -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/v2.9/act_<AD_ACCOUNT_ID>/ads

Asynchronous Creation

Create multiple ads at a time asynchronously. Receive a notification when all the ads in the request exist. Make an HTTP POST to: https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/asyncadrequestsets

Use these fields:

NameTypeDescriptionRequired

name

string

Name of ad set for newly created ads.

yes

ad_specs

array of ad specs

Ads can be created for different ad sets inside the current ad account. To use images in ad creative, provide image_hash in ad spec after you upload the image at https://graph.facebook.com/<API_VERSION>/ act_<AD_ACCOUNT_ID>/adimages.
image_file inside ad_specs.

yes

notification_uri

string

Async job completed. This URI notifies the caller with a POST and ad set id.

no

notification_mode

string

Notification mode:
OFF – No notification
ON_COMPLETE – Send notification when all ads for set created.

no



For information on asynchronous request sets, see Asynchronous Requests.

Limits

These are the maximum number of ads per object:

LimitValue

Ads in regular ad account

5000 non-deleted ads

Ads in bulk ad account

50000 non-deleted ads

Ads in an ad set

50 non-deleted ads

Archived ads in an ad account

100,000 archived ads

Examples

Download details for an ad:

from facebookads.adobjects.ad import Ad

ad = Ad(parent_id='act_<AD_ACCOUNT_ID>')
ad[Ad.Field.name] = 'My Ad'
ad[Ad.Field.adset_id] = <AD_SET_ID>
ad[Ad.Field.creative] = {'creative_id': <CREATIVE_ID>}
ad[Ad.Field.redownload] = True
ad.remote_create(params={
    'status': Ad.Status.paused,
})
curl \
-F "name=my ad" \
-F "adset_id=<AD_SET_ID>" \
-F "creative={'creative_id':<AD_CREATIVE_ID>}" \
-F "redownload=true" \
-F "status=PAUSED" \
-F "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/ads"



You can make a POST request to adgroups edge from the following paths:
When posting to this edge, an Ad will be created.

Permissions

Developers usually request these permissions for this endpoint:

Marketing Apps
  • ads_management
Page management Apps
No data
Other Apps
No data

Parameters

NameDescription
adlabels
list<Object>

Ad labels associated with this ad

adset_id
int64

The ID of the ad set, required on creation.

adset_spec
Ad set spec

The ad set spec for this ad. When the spec is provided, adset_id field is not required.

bid_amount
integer

Bid amount for this ad which will be used in auction instead of the ad set bid_amount, if specified. Any updates to the ad set bid_amount will overwrite this value with the new ad set value.

creative
AdCreative

This field is required for create. The ID of the ad creative to be used by this ad. You can read more about creatives here. You should supply the ID within an object as follows:

{"creative_id": <CREATIVE_ID>}

RequiredSupports Emoji
date_format
string

The format of the date.

display_sequence
int64

The sequence of the ad within the same campaign

dynamic_creative_optimization_split_test_mode
enum{RANDOM}

Dynamic creative optimization split test mode. Currently supported value is:
RANDOM: All possible combinations will be created. If there are too many combinations a random subset will be selected so that the limit of ads is not exceeded

execution_options
list<enum{validate_only, synchronous_ad_review, include_recommendations}>
Default value: Set

An execution setting
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.
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 will perform Ads Integrity validations, which include message language checking, image 20% text rule, and so on, as well as the validation logics.
If the call passes validation or review, response will be {"success": true}. If the call does not pass, an error will be returned with more details. These options can be used to improve any UI to display errors to the user much sooner, e.g. as soon as a new value is typed into any field corresponding to this ad object, rather than at the upload/save stage, or after review.

name
string

Name of the ad.

Required
redownload
boolean

Set this value to true and the API will respond with all fields instead of just id.

status
enum{ACTIVE, PAUSED, DELETED, ARCHIVED}

Only ACTIVE and PAUSED are valid during creation. Other statuses can be used for update. When an ad is created, it will first go through ad review, and will have the ad status PENDING_REVIEW before it finishes review and reverts back to your selected status of ACTIVE or PAUSED. During testing, it is recommended to set ads to a PAUSED status so as to not incur accidental spend.

tracking_specs
Object

Tracking specs

Return Type

Struct {
id: numeric string,
success: bool,
}
You can make a POST request to ads edge from the following paths:
When posting to this edge, an Ad will be created.

Permissions

Developers usually request these permissions for this endpoint:

Marketing Apps
  • ads_management
Page management Apps
No data
Other Apps
No data

Parameters

NameDescription
adlabels
list<Object>

Ad labels associated with this ad

adset_id
int64

The ID of the ad set, required on creation.

adset_spec
Ad set spec

The ad set spec for this ad. When the spec is provided, adset_id field is not required.

bid_amount
integer

Bid amount for this ad which will be used in auction instead of the ad set bid_amount, if specified. Any updates to the ad set bid_amount will overwrite this value with the new ad set value.

creative
AdCreative

This field is required for create. The ID of the ad creative to be used by this ad. You can read more about creatives here. You should supply the ID within an object as follows:

{"creative_id": <CREATIVE_ID>}

RequiredSupports Emoji
date_format
string

The format of the date.

display_sequence
int64

The sequence of the ad within the same campaign

dynamic_creative_optimization_split_test_mode
enum{RANDOM}

Dynamic creative optimization split test mode. Currently supported value is:
RANDOM: All possible combinations will be created. If there are too many combinations a random subset will be selected so that the limit of ads is not exceeded

execution_options
list<enum{validate_only, synchronous_ad_review, include_recommendations}>
Default value: Set

An execution setting
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.
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 will perform Ads Integrity validations, which include message language checking, image 20% text rule, and so on, as well as the validation logics.
If the call passes validation or review, response will be {"success": true}. If the call does not pass, an error will be returned with more details. These options can be used to improve any UI to display errors to the user much sooner, e.g. as soon as a new value is typed into any field corresponding to this ad object, rather than at the upload/save stage, or after review.

name
string

Name of the ad.

Required
redownload
boolean

Set this value to true and the API will respond with all fields instead of just id.

status
enum{ACTIVE, PAUSED, DELETED, ARCHIVED}

Only ACTIVE and PAUSED are valid during creation. Other statuses can be used for update. When an ad is created, it will first go through ad review, and will have the ad status PENDING_REVIEW before it finishes review and reverts back to your selected status of ACTIVE or PAUSED. During testing, it is recommended to set ads to a PAUSED status so as to not incur accidental spend.

tracking_specs
Object

Tracking specs

Return Type

Struct {
id: numeric string,
success: bool,
}
You can make a POST request to leads edge from the following paths:
When posting to this edge, an Ad will be created.

Parameters

NameDescription
end_time
datetime

Leads created before end_time will be exported

start_time
datetime

Leads created after start_time will be exported

Return Type

This endpoint supports read-after-write and will read the node represented by report_run_id in the return type.
Struct {
report_run_id: numeric string,
}
You may perform a POST request to the following edge from this node:

Validation Rules

ErrorDescription
100Invalid parameter
200Permissions error
273This Ads API call requires the user to be admin of the ad account
2626The request for a reach frequency campaign has failed.
300Edit failure
2633This shared login is disabled. Go to Ads Manager for more information.
500Message contains banned content
380There was a problem uploading your thumbnail file. Please try again.
192Invalid phone number
384The video you tried to upload is too long. Please try again with a shorter video.

Updating

Update certain fields:

use FacebookAds\Object\Ad;
use FacebookAds\Object\Fields\AdFields;

$ad = new Ad($ad_id);
$ad->update(array(
  AdFields::NAME => 'New Ad Name',
));
from facebookads.objects import Ad

ad_id = <AD_ID>
ad = Ad(ad_id)
ad[Ad.Field.name] = 'New Ad Name'
ad.remote_update()
curl \
-F "name=New Ad Name" \
-F "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<AD_ID>"

Limitations

Use fields you used to Create Ads, including status and execution_options. You cannot use adset_id and social_prefs.

  • Ads with status = ARCHIVED have only two mutable fields: name and status. You can only change the latter to DELETED.

  • Ads with status = DELETED only can have name changed.

  • Ads in an ad set with creative_sequence set cannot be changed to PAUSED, ARCHIVED, or DELETED.

Examples

Update the name:

use FacebookAds\Object\Ad;
use FacebookAds\Object\Fields\AdFields;

$ad = new Ad(<AD_ID>);
$ad->{AdFields::NAME} = 'New Ad Name';
$ad->update();
from facebookads.adobjects.ad import Ad

ad = Ad(<AD_ID>)
ad[Ad.Field.name] = 'New Ad Name'
ad.remote_update()
new Ad(<AD_ID>, context).update()
  .setName("New Ad Name")
  .execute();
curl \
-F "name=newname" \
-F "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<AD_ID>"

Update the name and download ad information:

use FacebookAds\Object\Ad;
use FacebookAds\Object\Fields\AdFields;

$ad = new Ad(<AD_ID>);
$ad->setData(array(
  AdFields::NAME => 'New Ad Name',
));
$ad->update(array(
  'redownload' => true,
));
from facebookads.adobjects.ad import Ad

ad = Ad(<AD_ID>)
ad[Ad.Field.name] = 'New Ad Name'
ad['redownload'] = True
ad.remote_update()
new Ad(<AD_ID>, context).update()
  .setName("New Ad Name")
  .setRedownload(true)
  .execute();
curl \
-F "name=newname" \
-F "redownload=true" \
-F "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<AD_ID>"

Update the status:

use FacebookAds\Object\Ad;

$ad = new Ad(<AD_ID>);
$ad->update(array(
  Ad::STATUS_PARAM_NAME => Ad::STATUS_PAUSED,
));
from facebookads.adobjects.ad import Ad

ad = Ad(<AD_ID>)
ad.remote_update(params={
    'status': Ad.Status.paused,
})
new Ad(<AD_ID>, context).update()
  .setStatus(Ad.EnumStatus.VALUE_PAUSED)
  .execute();
curl \
-F "status=ADGROUP_PAUSED" \
-F "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<AD_ID>"



You can update an Ad by making a POST request to /{ad_id}.

Permissions

Developers usually request these permissions for this endpoint:

Marketing Apps
  • ads_management
Page management Apps
No data
Other Apps
No data

Parameters

NameDescription
adlabels
list<Object>

Ad labels associated with this ad

adset_id
int64

The ID of the ad set, required on creation.

bid_amount
integer

Bid amount for this ad which will be used in auction instead of the ad set bid_amount, if specified. Any updates to the ad set bid_amount will overwrite this value with the new ad set value.

creative
AdCreative

This field is required for create. The ID of the ad creative to be used by this ad. You can read more about creatives here. You should supply the ID within an object as follows:

{"creative_id": <CREATIVE_ID>}

Supports Emoji
display_sequence
int64

The sequence of the ad within the same campaign

execution_options
list<enum{validate_only, synchronous_ad_review, include_recommendations}>
Default value: Set

An execution setting
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.
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 will perform Ads Integrity validations, which include message language checking, image 20% text rule, and so on, as well as the validation logics.
If the call passes validation or review, response will be {"success": true}. If the call does not pass, an error will be returned with more details. These options can be used to improve any UI to display errors to the user much sooner, e.g. as soon as a new value is typed into any field corresponding to this ad object, rather than at the upload/save stage, or after review.

name
string

Name of the ad.

redownload
boolean

Set this value to true and the API will respond with all fields instead of just id.

status
enum{ACTIVE, PAUSED, DELETED, ARCHIVED}

Only ACTIVE and PAUSED are valid during creation. Other statuses can be used for update. When an ad is created, it will first go through ad review, and will have the ad status PENDING_REVIEW before it finishes review and reverts back to your selected status of ACTIVE or PAUSED. During testing, it is recommended to set ads to a PAUSED status so as to not incur accidental spend.

tracking_specs
Object

Tracking specs

Return Type

This endpoint supports read-after-write and will read the node to which you POSTed.
Struct {
success: bool,
}
You may perform a POST request to the following edge from this node:

Validation Rules

ErrorDescription
100Invalid parameter
200Permissions error
273This Ads API call requires the user to be admin of the ad account
2626The request for a reach frequency campaign has failed.
300Edit failure
2633This shared login is disabled. Go to Ads Manager for more information.
500Message contains banned content
380There was a problem uploading your thumbnail file. Please try again.
192Invalid phone number
384The video you tried to upload is too long. Please try again with a shorter video.

Deleting

Deleting an ad

You can remove values for any optional fields by updating the value to empty. You cannot delete ads in ad set with creative_sequence settings.

use FacebookAds\Object\Ad;

$ad = new Ad(<AD_ID>);
$ad->deleteSelf();
from facebookads.adobjects.ad import Ad

ad = Ad(<AD_ID>)
ad.remote_delete()
new Ad(<AD_ID>, context).update()
  .setStatus(Ad.EnumStatus.VALUE_DELETED)
  .execute();
curl \
-F "status=DELETED" \
-F "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<AD_ID>"



You can delete an Ad by making a DELETE request to /{ad_id}.

Permissions

Developers usually request these permissions for this endpoint:

Marketing Apps
  • ads_management
Page management Apps
No data
Other Apps
No data

Parameters

This endpoint doesn't have any parameters.

Return Type

Struct {
success: bool,
}
You may perform a DELETE request to the following edge from this node:

Validation Rules

ErrorDescription
100Invalid parameter