Marketing API Version

AdAccount

Fields

account_groups, account_id, account_status, adlabels, age, agency_client_declaration, amount_spent, balance, business, business_city, business_country_code, business_name, business_state, business_street, business_street2, business_zip, capabilities, currency, end_advertiser, funding_source, funding_source_details, id, is_personal, media_agency, name, offsite_pixels_tos_accepted, owner, partner, spend_cap, tax_id_status, timezone_id, timezone_name, timezone_offset_hours_utc, tos_accepted, users

AdAccount.get_activities (fields, params)

Returns iterator over Activity's associated with this account.

Name Type Description Required

fields

array

A list of fields to read.

No

params

map

A mapping of request parameters where a key is the parameter name and its value is a string or an object which can be JSON-encoded.

No

Sample Code

account = AdAccount('act_1505766289694659')
activities = account.get_activities(fields=[
    Activity.Field.event_type,
    Activity.Field.event_time,
])
print activities[0]

AdAccount.get_ad_conversion_pixels (fields, params)

Returns iterator over AdConversionPixels associated with this account.

Name Type Description Required

fields

array

A list of fields to read.

No

params

map

A mapping of request parameters where a key is the parameter name and its value is a string or an object which can be JSON-encoded.

No

Sample Code

account = AdAccount('act_1505766289694659')
pixels = account.get_ad_conversion_pixels(fields=[
    AdImage.Field.hash,
])
print pixels

AdAccount.get_ad_creatives (fields, params)

Returns iterator over AdCreative's associated with this account.

Name Type Description Required

fields

array

A list of fields to read.

No

params

map

A mapping of request parameters where a key is the parameter name and its value is a string or an object which can be JSON-encoded.

No

Sample Code

account = AdAccount('act_1505766289694659')
creatives = account.get_ad_creatives(fields=[
    AdCreative.Field.name,
    AdCreative.Field.image_hash,
])
print creatives[0:2]

AdAccount.get_ad_creatives_by_labels (fields, params)

Returns the ad creatives associated with the ad AdLabel

Name Type Description Required

fields

array

A list of fields to read.

No

params

map

A mapping of request parameters where a key is the parameter name and its value is a string or an object which can be JSON-encoded.

No

Sample Code

account = AdAccount('act_1505766289694659')
adlabel_id = '6037040407040'
params = {'ad_label_ids': [adlabel_id], 'operator': 'ALL'}
adcreatives = account.get_ad_creatives_by_labels(fields=[
    AdLabel.Field.name,
    AdLabel.Field.id,
], params=params)
print adcreatives

AdAccount.get_ad_images (fields, params)

Returns iterator over AdImage's associated with this account.

Name Type Description Required

fields

array

A list of fields to read.

No

params

map

A mapping of request parameters where a key is the parameter name and its value is a string or an object which can be JSON-encoded.

No

Sample Code

account = AdAccount('act_1505766289694659')
images = account.get_ad_images(fields=[
    AdImage.Field.hash,
])
print images

AdAccount.get_ad_labels (fields, params)

Returns all the ad labels associated with the ad account

Name Type Description Required

fields

array

A list of fields to read.

No

params

map

A mapping of request parameters where a key is the parameter name and its value is a string or an object which can be JSON-encoded.

No

Sample Code

account = AdAccount('act_1505766289694659')
adlabels = account.get_ad_labels(fields=[
    AdLabel.Field.name,
    AdLabel.Field.id,
])
print adlabels

AdAccount.get_ad_preview (fields, params)

Returns iterator over previews generated under this account.

Name Type Description Required

fields

array

A list of fields to read.

No

params

map

A mapping of request parameters where a key is the parameter name and its value is a string or an object which can be JSON-encoded.

No

Sample Code

account = AdAccount('act_1505766289694659')
ad_preview = account.get_ad_preview(params={
    'creative': {
        'title': 'This is the title',
        'body': 'This is the body',
        'object_url': 'https://facebookmarketingpartners.com',
        'image_hash': 'ed3345d875fec7ced81caf3c1f3aee28',
    },
    'ad_format': 'RIGHT_COLUMN_STANDARD',
})
print ad_preview

AdAccount.get_ad_sets (fields, params)

Returns iterator over AdSet's associated with this account.

Name Type Description Required

fields

array

A list of fields to read.

No

params

map

A mapping of request parameters where a key is the parameter name and its value is a string or an object which can be JSON-encoded.

No

Sample Code

account = AdAccount('act_1505766289694659')
adsets = account.get_ad_sets(fields=[
    AdSet.Field.name,
    AdSet.Field.bid_info,
    AdSet.Field.configured_status,
    AdSet.Field.daily_budget,
    AdSet.Field.targeting,
])
print adsets

AdAccount.get_ad_users (fields, params)

Returns iterator over AdUser's associated with this account.

Name Type Description Required

fields

array

A list of fields to read.

No

params

map

A mapping of request parameters where a key is the parameter name and its value is a string or an object which can be JSON-encoded.

No

Sample Code

account = AdAccount('act_1505766289694659')
users = account.get_ad_users()
print users

AdAccount.get_ads (fields, params)

Returns iterator over Ad's associated with this account.

Name Type Description Required

fields

array

A list of fields to read.

No

params

map

A mapping of request parameters where a key is the parameter name and its value is a string or an object which can be JSON-encoded.

No

Sample Code

account = AdAccount('act_1505766289694659')
ads = account.get_ads(fields=[
    Ad.Field.name,
    Ad.Field.configured_status,
    Ad.Field.creative,
])
print ads

AdAccount.get_ads_by_labels (fields, params)

Returns the ad Groups associated with the ad AdLabel

Name Type Description Required

fields

array

A list of fields to read.

No

params

map

A mapping of request parameters where a key is the parameter name and its value is a string or an object which can be JSON-encoded.

No

Sample Code

account = AdAccount('act_1505766289694659')
adlabel_id = '6037040407040'
params = {'ad_label_ids': [adlabel_id], 'operator': 'ALL'}
ads = account.get_ads_by_labels(fields=[
    AdLabel.Field.name,
    AdLabel.Field.id,
], params=params)
print ads

AdAccount.get_ads_pixels (fields, params)

Name Type Description Required

fields

array

A list of fields to read.

No

params

map

A mapping of request parameters where a key is the parameter name and its value is a string or an object which can be JSON-encoded.

No

Sample Code

account = AdAccount('act_1505766289694659')
pixels = account.get_ads_pixels(fields=[
    AdsPixel.Field.name,
    AdsPixel.Field.id,
])
print pixels

AdAccount.get_adsets_by_labels (fields, params)

Returns the ad sets associated with the ad AdLabel

Name Type Description Required

fields

array

A list of fields to read.

No

params

map

A mapping of request parameters where a key is the parameter name and its value is a string or an object which can be JSON-encoded.

No

Sample Code

account = AdAccount('act_1505766289694659')
adlabel_id = '6037040407040'
params = {'ad_label_ids': [adlabel_id], 'operator': 'ALL'}
adsets = account.get_adsets_by_labels(fields=[
    AdLabel.Field.name,
    AdLabel.Field.id,
], params=params)
print adsets

AdAccount.get_broad_category_targeting (fields, params)

Returns iterator over BroadCategoryTargeting's associated with this account.

Name Type Description Required

fields

array

A list of fields to read.

No

params

map

A mapping of request parameters where a key is the parameter name and its value is a string or an object which can be JSON-encoded.

No

Sample Code

account = AdAccount('act_1505766289694659')
bct = account.get_broad_category_targeting()
print bct[0:2]

AdAccount.get_campaigns (fields, params)

Returns iterator over Campaign's associated with this account.

Name Type Description Required

fields

array

A list of fields to read.

No

params

map

A mapping of request parameters where a key is the parameter name and its value is a string or an object which can be JSON-encoded.

No

Sample Code

account = AdAccount('act_1505766289694659')
campaigns = account.get_campaigns(fields=[
    Campaign.Field.name,
    Campaign.Field.configured_status,
])
print campaigns

AdAccount.get_campaigns_by_labels (fields, params)

Returns the ad campaigns associated with the ad AdLabel

Name Type Description Required

fields

array

A list of fields to read.

No

params

map

A mapping of request parameters where a key is the parameter name and its value is a string or an object which can be JSON-encoded.

No

Sample Code

account = AdAccount('act_1505766289694659')
adlabel_id = '6037040407040'
params = {'ad_label_ids': [adlabel_id], 'operator': 'ALL'}
campaigns = account.get_campaigns_by_labels(fields=[
    AdLabel.Field.name,
    AdLabel.Field.id,
], params=params)
print campaigns

AdAccount.get_connection_objects (fields, params)

Returns iterator over ConnectionObject's associated with this account.

Name Type Description Required

fields

array

A list of fields to read.

No

params

map

A mapping of request parameters where a key is the parameter name and its value is a string or an object which can be JSON-encoded.

No

Sample Code

account = AdAccount('act_1505766289694659')
connection_objects = account.get_connection_objects()
connection_objects = [
    co for co in connection_objects if co['id'] == '606699326111137']
print connection_objects

AdAccount.get_custom_audiences (fields, params)

Returns iterator over CustomAudience's associated with this account.

Name Type Description Required

fields

array

A list of fields to read.

No

params

map

A mapping of request parameters where a key is the parameter name and its value is a string or an object which can be JSON-encoded.

No

Sample Code

account = AdAccount('act_1505766289694659')
custom_audiences = account.get_custom_audiences()
print custom_audiences

AdAccount.get_insights (fields, params, async)

Name Type Description Required

fields

array

A list of fields to read.

No

params

map

A mapping of request parameters where a key is the parameter name and its value is a string or an object which can be JSON-encoded.

No

async

boolean

Whether or not to call this asynchronously.

No

Sample Code

account = AdAccount('act_1505766289694659')
insights = account.get_insights(fields=[
    Insights.Field.campaign_id,
    Insights.Field.unique_clicks,
    Insights.Field.impressions,
], params={
    'level': Insights.Level.campaign,
    'date_preset': Insights.Preset.yesterday,
})
print insights

AdAccount.get_minimum_budgets (fields, params)

Returns the minimum budget associated with the AdAccount

Name Type Description Required

fields

array

A list of fields to read.

No

params

map

A mapping of request parameters where a key is the parameter name and its value is a string or an object which can be JSON-encoded.

No

Sample Code

account = AdAccount('act_1505766289694659')
min_budgets = account.get_minimum_budgets()
print min_budgets

AdAccount.get_partner_categories (fields, params)

Returns iterator over PartnerCategory's associated with this account.

Name Type Description Required

fields

array

A list of fields to read.

No

params

map

A mapping of request parameters where a key is the parameter name and its value is a string or an object which can be JSON-encoded.

No

Sample Code

account = AdAccount('act_1505766289694659')
partner_categories = account.get_partner_categories()
print partner_categories[0]

AdAccount.get_rate_cards (fields, params)

Returns iterator over RateCard's associated with this account.

Name Type Description Required

fields

array

A list of fields to read.

No

params

map

A mapping of request parameters where a key is the parameter name and its value is a string or an object which can be JSON-encoded.

No

Sample Code

account = AdAccount('act_1505766289694659')
rate_cards = account.get_rate_cards()
print rate_cards[0:2]

AdAccount.get_reach_estimate (fields, params)

Returns iterator over ReachEstimate's associated with this account.

Name Type Description Required

fields

array

A list of fields to read.

No

params

map

A mapping of request parameters where a key is the parameter name and its value is a string or an object which can be JSON-encoded.

No

Sample Code

account = AdAccount('act_1505766289694659')
reach_estimate = account.get_reach_estimate(params={
    'currency': 'USD',
    'optimize_for': 'OFFSITE_CONVERSIONS',
    'targeting_spec': {
        'geo_locations': {
            'countries': ['US'],
        }
    }
})
print reach_estimate

AdAccount.get_targeting_description (fields, params)

Returns TargetingDescription object associated with this account.

Name Type Description Required

fields

array

A list of fields to read.

No

params

map

A mapping of request parameters where a key is the parameter name and its value is a string or an object which can be JSON-encoded.

No

Sample Code

adgroup = Ad('6040236409040')
targeting = {
    TargetingSpecsField.geo_locations: {
        TargetingSpecsField.countries: ['US'],
    },
}
targeting_desc = adgroup.get_targeting_description(fields=[
    'targetingsentencelines'
], params={
    'targeting_spec': targeting
})
print targeting_desc

AdAccount.get_transactions (fields, params)

Returns iterator over Transaction's associated with this account.

Name Type Description Required

fields

array

A list of fields to read.

No

params

map

A mapping of request parameters where a key is the parameter name and its value is a string or an object which can be JSON-encoded.

No

Sample Code

account = AdAccount('act_1505766289694659')
transactions = account.get_transactions()
print transactions

AdAccount.opt_out_user_from_targeting (schema, users, app_ids)

Opts out users from being targeted by this ad account.

Args: schema: A CustomAudience.Schema value users: a list of identites that follow the schema given

Returns: Return FacebookResponse object

Name Type Description Required

schema

string

Specify whether you are adding users using email, user IDs, or phone numbers.

Yes

users

array

An array of user IDs.

Yes

app_ids

array

An array of application IDs.

No

Sample Code

account = AdAccount('act_1505766289694659')
response = account.opt_out_user_from_targeting(
    schema=CustomAudience.Schema.email_hash,
    users=['joe@example.com'],
)
print response