Service endpoint

https://api.targetsmart.com/voter/voter-registration-check

Overview

This service can be used to search TargetSmart’s service database of registered voters, to check if a voter is registered at a given address.

TargetSmart’s voter database is of the highest quality and updated weekly. However, there will always be some delta between our maintained data and official state sources. Given this, it is suggested that your application provide a disclaimer instructing visitors to use the resources provided by state election authorities for the final word on registration status.

By design this service is very conservative in matching queries to voter registration records. This is to limit the number of false positives. We want to avoid telling individuals they are registered when in fact they may not be. Even minor differences in submitted query data and registration records will result in a failure to match and this should be considered in your application design.

Request parameters

Key Required Optional Default Permitted Values
first_name ✓ One or more alpha characters. Trailing wildcard allowed
last_name ✓ One or more alpha characters. Trailing wildcard allowed
street_number ✓ One or more alphanumeric characters. Trailing wildcard allowed
street_name ✓ One or more alphanumeric characters. Trailing wildcard allowed
city ✓ One or more alpha characters. Trailing wildcard allowed
state ✓ Two character U.S. state code (e.g. NY)
zip_code ✓ Numeric characters. Trailing wildcard allowed
age ✓ One or more integers. Trailing wildcard allowed
dob ✓ Numeric characters in YYYYMMDD format. Trailing wildcard allowed
phone ✓ Integer followed by 0 or more * or integers
email ✓ Alphanumeric character followed by 0 or more * or legal characters (alphanumeric, @, -, .)
unparsed_full_address ✓ One or more alphanumeric characters. No wildcards.

A * character may be present as a wildcard to support field prefix search, but must not be the first character in a search term.

Additional parameter details

street_name, street_number

It is recommended to only provide USPS CASS (United Postal Service Coding Accuracy System) standardized values for street_name to increase the likelihood of a successful match to our database. The street_name field should only contain the CASS standardized street name. For best results do not include street predirectional or suffix when defining the street_name parameter.

If you are unsure if your street name values are in a standard format, preprocess with a third party CASS API or utilize the unparsed_full_address parameter.

unparsed_full_address

If you do not have standardized parsed address fields to provide in your requests, it is suggested that you instead include the entire address in the unparsed_full_address parameter.

An attempt will be made to parse the provided information into standardized street number, street name, and zip code values that will have a higher probability to match our database. Those values, along with the value of the required parameter state will be used as the query input.

At this time, this option is offered as a convenience and may not provide optimal results. For best results, pre-standardize your address fields with a CASS provider.

TIPS

  • The unparsed_full_address parameter is to be used instead of street_name and street_number. Do not use this field for requests with only city and state, for those use the city and state fields. Otherwise, your city name will be parsed as a street name.
  • If you have multiple address lines, separate them with spaces, do not include newline characters in any parameters.
  • Review the parsed_address parameter in the response to troubleshoot issues with unparsed addresses (see below).

JSON response

Search responses are JSON objects with the following keys:

  • result: true if exactly one match was found, false otherwise
  • result_set: List of single matching voter JSON object or empty list
  • too_many: true if more than one potential match was found, false otherwise
  • parsed_address: If unparsed_full_address is given, this parameter provides the corresponding parsed address in JSON format, or an empty object if the address was not parsable
  • 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.

Result Set

A matched voter object in result_set 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. Note, this “list” will never be more than a single item and is kept as a list for backwards compatibility.

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-registration-check",
    params={
        "first_name": "BOB",
        "last_name": "EXAMPLE",
        "state": "OH",
        "phone": "1112223333",
    },
    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: "BOB",
  last_name: "EXAMPLE",
  state: "OH",
  phone: "1112223333",
});

fetch(
  "https://api.targetsmart.com/voter/voter-registration-check?" +
    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-registration-check?first_name=BOB&last_name=EXAMPLE&state=OH&phone=1112223333")
echo $result