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


ct, city, vb_vf_reg_city, vb_tsmart_city


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


country, country code


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