Enhance your data with SmartMatch¶

This guide is Step 1 in our Example Walkthrough: 1. append data to existing lists.

To append data, we’ll be using the SmartMatch API for WAG’s list. WAG has a list of names and addresses that they collected from a recent campaign.

Below is a sample list before the SmartMatch matching:

Below is a sample list with additional fields you’ll receive after the SmartMatch process:

Getting started¶

1. Prepare a CSV with the data you want to match. The file must meet these requirements:

   • Excel compatible, comma delimited CSV
   • UTF-8 character encoding
   • Header record with one or more fields matching the supported identifiers

2. Access your API key. Make sure to never expose this publicly.

3. You’ll need to have the Python library requests installed.
4. Make sure you have a code editor. Some options are Sublime or Visual Studio Code.

Let’s get to the code!¶

Step 1: Make a GET request¶

Using the code example as a reference, we’ll first make a GET request to the SmartMatch API endpoint. The response will contain a presigned URL that WAG can use to upload the file they want to append data to.

import os
import json
import requests

api_key = os.environ["TS_API_KEY"]

endpoint = "https://api.targetsmart.com/service/smartmatch"
# request URL to upload data
params = {
    "filename": "WAG_data",
}
headers = {"x-api-key": api_key}

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

The response_1_info object will look something like:

{
    "input": {"filename": "WAG_data",}, 
    "error": null, 
    "url": "https://ts-smartmatch-api.s3.amazonaws.com/xxxxx", 
    "gateway_id": "XXXXXXX-XXXX-XXXX-XXXX-XXXXXXX", 
    "function_id": "XXXXXXX-XXXX-XXXX-XXXX-XXXXXXX" 
} 

Step 2: Make a PUT request¶

Now that we have the upload URL, we can make a PUT request to upload our local CSV to SmartMatch, where it can be processed and matched.

if not response_1_info["error"]:
    print("Registration request successful")

    # Stream your prepared UTF8 CSV input file to the provided pre-signe URL.
    # Content-Type should be <empty>.
    # This request interacts with AWS S3. Do not include the TargetSmart API key in the request header.
    with open("<local_file>.csv", "rb") as reader:
        response_2 = requests.put(
            response_1_info["url"], data=reader, headers={"Content-Type": ""}
        )
    response_2.raise_for_status()
    print("Execution started")

This starts off a SmartMatch job to append data to your file! The fields that will be appended depend on what you have configured to your account. Reach out to client services to configure the fields you’d like.

Step 3: Check for Complete SmartMatch Processing¶

Depending on the size of the input file, SmartMatch can take some time to process, match, and append data to your file. There are 3 ways to check on the status of a job:

1. GET Poll endpoint.¶

Make a GET request to the SmartMatch Poll endpoint to check the status of your job using the filename you used to create the job as a parameter.

import os
import json
import requests

api_key = os.environ["TS_API_KEY"]

endpoint = "https://api.targetsmart.com/service/smartmatch/poll"
# request URL to upload data
params = {
    "filename": "WAG_data",
}
headers = {"x-api-key": api_key}

response_1 = requests.get(endpoint, params=params, headers=headers)
response_1.raise_for_status()
response_1_info = response_1.json()

If the file is ready, the returned JSON object url attribute will be populated with the presigned URL for your application to download.

2. Check your FileBrowser account.¶

Check the SmartMatch folder in MyTargetSmart File Browser. If the file is ready, the enriched list will be there with the filename in it’s title.

3. Use a Webhook.¶

Provide a valid URL that can be used as a webhook to the webhook parameter of the service/smartmatch GET request.

What are webhooks?
Webhooks are user-defined HTTP callbacks, which are triggered by specific events. Whenever a new event occurs in the endpoint, it posts the event data to your specified URL, meaning you get data immediately. TargetSmart uses webhooks to notify your application when an event happens. Some resources to create your own webhook are:

• Create a Serverless Webhook with Python and AWS Lambda

• Using AWS Lambda with Amazon API Gateway

See more info on the webhook parameter in the SmartMatch documentation.

Creating Media Buying Platform audiences¶

It is also possible to create custom digital audiences based on SmartMatch results for use in your TargetSmart Media Buying Platform ad campaigns. Contact TargetSmart Digital Services for more information about accessing the Media Buying Platform.

To create a digital audience, utilize these additional service/smartmatch parameters:

• mbp_onboarding: Set to true to enable interaction with the Media Buying Platform
• digital_audience_name: Provide a name for your custom audience
• notification_email: Include an email address to receive Media Buying Platform processing notifications

Where to next?¶

Next, we’ll compare demographic data from our enhanced list to the national voter file using the ListBuilder API. When you’re ready to use the enhanced list, check out our Python notebook guide to gain more insight and analyze your data.