The FacebookAds class allows you to interact with parts of the Facebook Business API. Currently the connector provides methods for creating and deleting custom audiences, and for adding users to audiences.

The FacebookAds connector is a thin wrapper around the FB Business SDK, so some of that SDK is exposed, e.g., you may see exceptions like FacebookRequestError.

Facebook’s advertising and Pages systems are massive. Check out the overviews for more information:


Before using FacebookAds, you’ll need the following: * A FB application, specifically the app ID and secret. See https://developers.facebook.com to find your app details or create a new app. Note that a Facebook app isn’t necessarily visible to anyone but you: it’s just needed to interact with the Facebook API. * A FB ad account. See https://business.facebook.com to find your ad accounts or create a new one. * A FB access token representing a user that has access to the relevant ad account. You can generate an access token from your app, either via the Facebook API itself, or via console at https://developers.facebook.com.


To instantiate the FacebookAds class, you can either store your authentication credentials as environmental variables (FB_APP_ID, FB_APP_SECRET, FB_ACCESS_TOKEN, and FB_AD_ACCOUNT_ID) or pass them in as arguments:

from parsons import FacebookAds

# First approach: Use environmental variables
fb = FacebookAds()

# Second approach: Pass credentials as argument
fb = FacebookAds(app_id='my_app_id',

You can then use various methods:

# Create audience
fb.create_custom_audience(name='audience_name', data_source='USER_PROVIDED_ONLY')

# Delete audience


class parsons.FacebookAds(app_id=None, app_secret=None, access_token=None, ad_account_id=None)[source]

Instantiate the FacebookAds class

app_id: str
A Facebook app ID. Required if env var FB_APP_ID is not populated.
app_secret: str
A Facebook app secret. Required if env var FB_APP_SECRET is not populated.
access_token: str
A Facebook access token. Required if env var FB_ACCESS_TOKEN is not populated.
ad_account_id: str
A Facebook ad account ID. Required if env var FB_AD_ACCOUNT_ID isnot populated.
static get_match_table_for_users_table(users_table)[source]

Prepared an input table for matching into a FB custom audience, by identifying which columns are supported for matching, renaming those columns to what FB expects, and cutting away the other columns.

See FacebookAds.create_custom_audience for more details.

users_table: Table
The source table for matching
The prepared table
create_custom_audience(name, data_source, description=None)[source]

Creates a FB custom audience.

name: str
The name of the custom audience
data_source: str
One of USER_PROVIDED_ONLY, PARTNER_PROVIDED_ONLY, or BOTH_USER_AND_PARTNER_PROVIDED. This tells FB whether the data for a custom audience was provided by actual users, or acquired via partners. FB requires you to specify.
description: str
Optional. The description of the custom audience
ID of the created audience

Deletes a FB custom audience.

audience_id: str
The ID of the custom audience to delete.
add_users_to_custom_audience(audience_id, users_table)[source]

Adds user data to a custom audience.

Each user row in the provided table should have at least one of the supported columns defined. Otherwise the row will be ignored. Beyond that, the rows may have any other non-supported columns filled out, and those will all be ignored.

Column Type Valid Column Names
Email Address email, email address, voterbase_email
First Name fn, first, first name, vb_tsmart_first_name
Last Name ln, last, last name, vb_tsmart_last_name
Phone Number phone, phone number, cell, landline, vb_voterbase_phone, vb_voterbase_phone_wireless
City ct, city, vb_vf_reg_city, vb_tsmart_city
State st, state, state code, vb_vf_source_state, vb_tsmart_state, vb_vf_reg_state, vb_vf_reg_cass_state
Zip Code zip, zip code, vb_vf_reg_zip, vb_tsmart_zip
County country, country code
Gender gen, gender, sex, vb_vf_reg_zip
Birth Year doby, dob year, birth year
Birth Month dobm, dob month, birth month
Birth Day dobd, dob day, birth day
Date of Birth dob, vb_voterbase_dob, vb_tsmart_dob (Format: YYYYMMDD)

The column names will be normalized before comparing to this list - eg. removing whitespace and punctuation - so you don’t need to match exactly.

If more than one of your columns map to a single FB key, then for each row we’ll use any non-null value for those columns. Eg. If you have both vb_voterbase_phone and vb_voterbase_phone_wireless (which both map to the FB “phone” key), then for each person in your table, we’ll try to pick one valid phone number.

For details of the expected data formats for each column type, see Facebook Audience API, under “Hashing and Normalization for Multi-Key”.

Note that you shouldn’t have to do normalization on your data, as long as it’s reasonably close to what FB expects. Eg. It will convert “Male” to “m”, and ” JoSH” to “josh”.

FB will attempt to match the data to users in their system. You won’t be able to find out which users were matched. But if you provide enough data, FB will tell you roughly how many of them were matched. (You can find the custom audience in your business account at https://business.facebook.com).

Note that because FB’s matching is so opaque, it will hide lots of data issues. Eg. if you use “United States” instead of “US” for the “country” field, the API will appear to accept it, when in reality it is probably ignoring that field. So read the docs if you’re worried.

audience_id: str
The ID of the custom audience to delete.
users_table: obj
Parsons table