Service endpoint

https://api.targetsmart.com/voter/voter-suggest

Overview

Search TargetSmart’s service database to identify a registered voter using search inputs that can be refined. This service was designed to support low-latency interactive search user interfaces allowing a user to find a voter record with minimal keystrokes. Common use cases include petition verification and field voter record lookup. Voter suggest is a great tool for locating voters when incomplete information is available.

Request parameters

Key Required Optional Default Permitted Values
first_name OR Alpha character followed by 0 or more * or alpha characters
middle_name OR Alpha character followed by 0 or more * or alpha characters
last_name OR Alpha character followed by 0 or more * or alpha characters
street_number ✓ Alphanumeric character followed by 0 or more * or alphanumeric characters
street_name OR Alphanumeric character followed by 0 or more * or alphanumeric characters
city ✓ Alpha character followed by 0 or more * or alpha characters
state OR zip_code ✓ Two character U.S. state code (e.g. NY)
zip_code OR state ✓ 3 Integers followed by 2 or more * or integers
county ✓ Alphanumeric character followed by 0 or more * or alphanumeric characters
phone OR Integer followed by 0 or more * or integers
email OR Alphanumeric character followed by 0 or more * or legal characters (alphanumeric, @, -, .)
age ✓ Integer followed by 0 or more * or integers
dob ✓ Integers in YYYYMMDD format
max_results ✓ 25 An integer in range [1 - 50]

Additional parameter details

Each request uses required and allowed keys. The state or zip_code are required. If zip_code is provided and not state, the leading 3 digits in the zip_code will be used to look up the correct state. Additionally, each query must provide at least one valid character for any of the following: first_name, last_name, middle_name, street_name, phone, or email. All other allowed keys shown in the following table are optional.

Key values may contain a url-encoded (%2A) asterisk (*) as a wildcard, but cannot start with *.

max_results

By default the service returns up to 25 results. This can be set to up to 50.

JSON response

Search responses are JSON objects with the following keys:

  • potential_voter_matches: List of voter match objects (see below).
  • over_max_results: Boolean value indicating that search was too ambiguous, resulting in more matches than max_results.
  • states_updated: Voter file update date information represented as a JSON object where keys are two character U.S. state codes and values are dates the state voter file was last updated. The date format is YYYYMMDD.

Potential Voter Matches

Each matched voter object in potential_voter_matches will represent a registered voter and be associated with a TargetSmart voterbase_id. Additional attributes will be provided based on the fields configured for your API key. Contact Client Services for details.

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 requests

api_key = os.environ["TS_API_KEY"]
response = requests.get(
    "https://api.targetsmart.com/voter/voter-suggest",
    params={
        "first_name": "B*",
        "last_name": "SMITH",
        "state": "OH",
    },
    headers={"x-api-key": api_key},
)
response.raise_for_status()
print(response.json())

#! /usr/bin/env node

const fetch = require("node-fetch");

const targetSmartApiKey = process.env.TS_API_KEY;

const queryParams = new URLSearchParams({
  first_name: "B*",
  last_name: "SMITH",
  state: "OH",
});

fetch(
  "https://api.targetsmart.com/voter/voter-suggest?" + queryParams.toString(),
  {
    method: "GET",
    headers: {
      "x-api-key": targetSmartApiKey,
    },
  }
)
  .then((res) => res.json())
  .then((json) => console.log(json));

#! /usr/bin/env bash

result=$(curl -XGET \
    -H "x-api-key: $TS_API_KEY" \
    "https://api.targetsmart.com/voter/voter-suggest?first_name=B*&last_name=SMITH&state=OH")
echo $result