Push your enriched list to Facebook with Onboarding:


This guide is step 3 in our Example Walkthrough: upload their list to Facebook for digital advertising with Onboarding.

WAG can use the Onboarding API to create custom audience segments for digital ad targeting. Upon Facebook onboarding workflow completion, the custom audience will be ready to be used in Facebook Ads Platform.

Getting started

  1. Read the Overview to know how Onboarding works with Facebook.
  2. Meet these requirements:
  3. Start with a code editor.

Let’s get to the code!

Step 1: Define the functions you need

To use function onboarding, pass in the path of your enriched list into get_onboarding_ids to make it a DataFrame in order to return a list of matched IDs.

import os
import json
import requests
import pandas as pd

def get_onboarding_ids(csv_file):
    Returns a list of Voterbase IDs from a file enhanced by SmartMatch.

    :param csv_file: the enriched SmartMatch list.
    :type csv_file: string.
    :return: list of matched IDs.
    wag_df = pd.read_csv(csv_file)
    ids_list = wag_df["vb.voterbase_id"].dropna()
    ids_list = ids_list.sort_values()
    # Turns the sorted list of valid Voterbase IDs into a comma separated list (without spaces):
    string_of_ids = ",".join(str(id) for id in ids_list)

    return string_of_ids

Use the onboarding function to onboard your enriched list from SmartMatch onto Facebook with the Onboarding API.

def onboarding(audience_name, execution_payload):
    Onboard your enriched SmartMatch list onto Facebook.

    :param audience_name: This is the Audience Name that will be used to create a custom audience.
    :type audience_name: string.
    :param execution_payload: a dictionary with the fields: status_email, ids, facebook_adid.
    :type execution_payload: dictionary.

    api_key = os.environ["TS_API_KEY"]

    endpoint = "https://api.targetsmart.com/service/onboarding"
    # request URL to upload data
    params = {"platform": "facebook", "audience": audience_name}
    headers = {"x-api-key": api_key}

    # Register with service/onboarding to produce a target URL for upload.
    response_1 = requests.get(endpoint, params=params, headers=headers)
    response_1_info = response_1.json()

    if not response_1_info["error"]:

        print("Registration request successful")
        # PUT the onboarding request body to the returned pre-signed url to initiate asynchronous audience creation.
        # This request interacts with AWS S3. Do not include the TargetSmart API key in the request header.

        response_2 = requests.put(
            headers={"Content-Type": ""},
    print("Execution started")

Step 2: Run your Python Program

Store the path to your SmartMatch list in csv_file to get back a list of valid Voterbase IDs. Putting that list along with facebook_adid and status_email into onboarding_data makes the request in onboarding.

#Pass in the enriched list from SmartMatch:
csv_file = "<path to local file>.csv"
ids_list = get_onboarding_ids(csv_file) 

# Pass these fields in the onboarding function:
onboarding_data = {
    'facebook_adid': '123456789',
    'status_email': 'example@example.com',
    'ids': ids_list

# The main method to run:
onboarding('WAG_audience', onboarding_data)

Your request needs to contain the following fields:

  • status_email: An email address to receive status updates on your request

  • ids: A sorted comma separated list (without spaces) of valid Voterbase IDs

  • facebook_adid: Your Ad Account ID (required if platform=facebook)

Step 3: Wait for an email

You will get an “Onboarding Request Succeeded” email when the audience is ready for creating ads. Onboarding Request Succeeded After using the Onboarding endpoint to create custom audiences, you can then create Facebook ad sets and follow these Ad Set Targeting steps.