Service endpoint¶

https://api.targetsmart.com/service/smartmatch

Overview¶

Use this service to execute SmartMatch list matching workflows. Your application provides a CSV contact list which will be matched to TargetSmart’s database of voting age individuals. Upon workflow completion, the enriched list is available for secure file transfer. The results are made available in the smartmatch folder of your TargetSmart file transfer account. Optionally, a webhook url can be specified in the request as a target for posting the processed results.

TargetSmart Client Services provisions SmartMatch for your API key, configuring the fields from our Data Dictionary that will be appended to each matched record.

To successfully consume this service, your application will make a pair of HTTP requests for each file submission:

1. GET request to the service/smartmatch endpoint. The JSON response provides a presigned url.
2. PUT request to stream the contents of your contact list file to the provided url.

More about SmartMatch¶

Please also review the TargetSmart Smartmatch documentation.

Request parameters¶

Additional parameter details¶

webhook

This optional parameter provides an HTTP endpoint that the service will send an HTTP POST request with body {"callback": <signed_url>} where signed_url is an AWS S3 presigned GET URL to download results.

include_email, include_landline, include_wireless, include_voip

These parameters allow you to control if the associated phone and email values should be included in your deliverable. TargetSmart Client Services may include these data points in your configuration at extra cost. Setting to True indicates that you desire to receive and potentially incur additional costs for these attributes

search_radius

SmartMatch utilizes multiple matching strategies, including a geographic proximity search that compares similar names. By default, SmartMatch determines the search radius dynamically based on the “urbanicity” of each input record, which results in a smaller search radius for input addresses in densely populated areas and a larger one addresses in rural areas. To accommodate specific use cases requiring a consistent search radius across all input records, you can set a fixed radius size using the search_radius parameter. Assign a positive numeric value to this optional parameter to define the search radius in miles, which will override the default dynamic radius. Fractional sizes are allowed.

notification_email

Optionally provide an email address to receive SmartMatch and Media Buying Platform processing notifications.

Media Buying Platform audience creation

mbp_onboarding, digital_audience_name

SmartMatch can use your matched results to create a digital advertising audience in the TargetSmart Media Buying Platform. To do so, set mbp_onboarding to true and specify a digital_audience_name value which must be a string consisting of no more than 35 alphanumeric or underscore characters.

JSON response¶

Responses are JSON objects with the following keys:

• url: Presigned URL to upload data. Stream your CSV content encoded as UTF-8 using a PUT request.

PUT to upload file¶

Upon a successful GET request, then target the provided presigned url to upload your input file using an HTTP PUT request. The uploaded input file must meet these requirements:

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

Supported field identifiers¶

Your CSV header record should contain one or more of the following field identifiers. SmartMatch will adapt its matching strategies based on the field identifiers found.

An optional “matchback_id” field can be included. This field will be passed through and returned with your results.

Obtaining results¶

Upon successful workflow completion, the output will be stored to the smartmatch folder of your TargetSmart file transfer account, accessible by SFTP or My TargetSmart File Browser. A .zip archive is delivered containing the Excel compatible CSV output along with a summary report of the SmartMatch results. Your application may poll for these results via SFTP.

Alternatively, your application may rely on the webhook request parameter to be notified upon workflow completion, or use the poll endpoint.

Webhook¶

You may optionally provide a valid url to the webhook parameter of the initial request. In this case, a POST JSON request will be made to the provided url, providing a presigned url for the deliverable CSV resource.

The JSON object will have an attribute named callback and the associated value will be the presigned url for your application to download. The presigned url download body will be UTF-8 encoded Excel compatible CSV.

Poll Endpoint (Rate-Limited)¶

In addition to the webhook option, we offer a poll endpoint:

https://api.targetsmart.com/service/smartmatch/poll

This endpoint is rate-limited to 1 request every 30 seconds

The endpoint takes filename as a parameter. If the file is ready, the returned JSON object will have an attribute named url and the associated value will be the presigned url for your application to download. If the file is not ready, the url field will be blank. The error field is present as usual and will contain an error string if one occurred.

Max Matches¶

You may optionally include a parameter that will return multiple matches per record from your input file. When using the max_matchesparameter, your output file will include a separate csv file with the additional multiple matches, and a file with the best match for each record. Allowed values for the max_matches parameter are an integer of 1-10.

Please note that depending on your contract there may be additional costs if multiple matches are returned. Also that the max matches value that you set does not mean it will return that number of additional matches for every record. For example, if you set your max_matches paramter value to 5 then the maximum number of matches that will be returned for a record will be 5, including the best match, so 1 best match, and 4 additional matches.

Format¶

The SmartMatch API allows you to select the format of your export file. By default the file will be returned as an UTF-8 encoded Excel compatible CSV. If you want to have the file compressed before delivery, you can use the format parameter to have the file delivered in a zip or gzip format.

Code Examples¶

🔐 Remember to secure your API key

Never expose your API key in plain text or source control accessible by a third party.

#! /usr/bin/env python3

import os
import json
import requests

api_key = os.environ["TS_API_KEY"]

endpoint = "https://api.targetsmart.com/service/smartmatch"
headers = {"x-api-key": api_key}

# request URL to upload data
params = {
    "filename": "testinput",
    "webhook": "https://webhook.example.com/test/webhook",
}

# 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()

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

    # Stream your prepared UTF8 CSV input file to the provided pre-signed 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("smartmatch_input_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")

#! /usr/bin/env node

const fetch = require("node-fetch");
const fs = require("fs");
const filepath = "smartmatch_input_file.csv";
const targetSmartApiKey = process.env.TS_API_KEY;

// Register with service/smartmatch to produce a target url for upload.
fetch(
  "https://api.targetsmart.com/service/smartmatch?" +
    new URLSearchParams({
      filename: "testinput",
      webhook: "https://webhook.example.com/test/webhook",
    }).toString(),
  {
    method: "GET",
    headers: {
      "x-api-key": targetSmartApiKey,
    },
  }
).then((response) => {
  if (response.status === 200) {
    response.json().then((respdata) => {
      if (!respdata.error) {
        console.log("Registration request successful");

        /* Stream your prepared UTF8 CSV input file to the provided pre-signed
         * URL. Content-Type should be <empty>. This request interacts with AWS
         * S3. Do not include the TargetSmart API key in the request header. */
        const stats = fs.statSync(filepath);
        const reader = fs.createReadStream(filepath, { encoding: null });
        reader.on("error", console.log);

        fetch(respdata.url, {
          method: "PUT",
          headers: { "Content-Length": stats.size, "Content-Type": "" },
          body: fs.createReadStream(filepath),
        }).then((response2) => {
          if (response2.status === 200) {
            console.log("Execution started");
          }
        });
      }
    });
  }
});

#! /usr/bin/env bash

# Register with service/smartmatch to produce a target url for upload.
if result_1=$(curl -XGET \
    -H "x-api-key: $TS_API_KEY" \
    "https://api.targetsmart.com/service/smartmatch?filename=testinput&webhook=https%3A%2F%2Fwebhook.example.com%2Ftest%2Fwebhook"); then

    # Stream your prepared UTF8 CSV input file to the provided pre-signed URL.
    # Content-Type should be <empty>.
    # This request interacts with AWS S3. Do not include the TargetSmart API key in the request header.
    echo "Registration request successful";
    aws_url=$(echo $result_1| jq -r '.url');
    if result_2=$(curl -L -H 'Content-Type:' --upload-file smartmatch_input_file.csv $aws_url); then
        echo "Execution started"
    fi
fi