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

Key Required Optional Default Permitted Values
filename 1-50 alphanumeric or underscore characters
webhook valid HTTP(S) endpoint
include_email False boolean value
include_landline False boolean value
include_wireless False boolean value
include_voip False boolean value
max_matches 1 integer in the range 1-10
format csv csv, zip, gzip
search_radius Integer or float (in miles, i.e. 1.5 = 1 1/2 miles)

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.

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.

voterbase_id Voterbase ID: We accept TargetSmart Voterbase identifiers Examples: - AL-3733374 - CT-000001336310 - MD-000001022750
smartvan_id SmartVAN VAN ID: We accept valid SmartVAN record identifiers. Note, an associated `state` value should be specified. Examples: - 3 - 450 - 10001
voter_id Voter id assigned by state government: We accept valid state voter id values as applied by state governments. Note, an associated `state` value should be specified. Examples: - 3 - 0450 - 10001
exact_track ExactTrack Person ID: We accept ExactTrack person identifiers Examples: - Y29454910243612 - N29456ZHZ3DBHGNLMV8E
full_name Full Name: We accept a single individual's full name. Where possible please provide accurately parsed name components. Examples: - Michelle Obama - Philip K. Dick - Robert Downey Jr
first_name_combined Combined First Name: We accept two individual's first names in a single field. Where possible please provide a single record per individual. Examples: - Bonnie and Clyde - Susan and LD
first_name First Name: We accept a single individual's first name or first initial. Examples: - Robert - Simone - F. - D - Abdélina
middle_name Middle Name: We accept a single middle name or middle initials. Examples: - Ann - S. - S
last_name Last Name: We accept a single last name. Examples: - Stout - Zeta-Jones - André
name_suffix Name Suffix: We accept a single individual's name suffix. Examples: - Sr. - II - Jr
address1 Address Line 1: We accept full street address information or parsed address line 1. If you do not have parsed street address, include the full street address here. Examples: - 123 Main St. - 34 W Oak Ave.
address2 Address Line 2: We accept parsed address line 2 information. Examples: - Apt 3 - Suite 17
city City: We accept U.S. city names Examples: - Chicago - Davenport
state U.S. State: We accept two-letter abbreviations for U.S. States. Use DC for District of Columbia. Examples: - NY - DC - OH
zip USPS ZIP Code: We accept USPS postal codes (ZIP) Examples: - 72501 - 33410
age Age: We accept age (integer) Examples: - 25 - 42 - 80
gender Gender: We accept gender (F: Female, M: Male, U: Unknown, or ) Examples: - F - M - U
dob Date of birth: We accept date of birth in YYYYMMDD format Examples: - 19760114 - 19520820 - 20000101
phone Phone: We accept U.S. phone numbers. Examples: - 1112223333 - 111-222-3333 - (111) 222-3333 - 111.222.3333
email Email: We accept email addresses. Examples: - bob.smith@example.com
latitude Latitude: We accept latitude (WGS 84) in decimal form. Examples: - 38.8976805 - 47.541887
longitude Longitude: We accept longitude (WGS 84) in decimal form. Examples: - -77.0387185 - -121.837672

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/onboarding 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