Service endpoint¶

https://api.targetsmart.com/person/listbuilder

Overview¶

The ListBuilder API allows for arbitrary low-latency record counting and list selection from the TargetSmart platform database. The request specifies a SQL WHERE clause to identify your selection criteria. The response is a JSON list of VoterBase record identifiers (voterbase_id) when performing list selection or an integer value when performing a record count. For list selection, the request may specify an optional sample percentage. Any field described in the platform data dictionary may be used in constructing the WHERE expression. The request is executed synchronously with low latency.

Request Parameters¶

Additional Parameter Details¶

where

A SQL where clause, valid in Presto, that includes only fields from the VoterBase component of the TargetSmart Data Dictionary.

Examples:

"vb.vf_source_state = 'NY'"

"vb.vf_age < 20"

    "vb.vf_source_state = 'AZ' AND
    vb.vf_reg_zip IN ('85224', '85226') AND
    ts.tsmart_partisan_score >= 90 AND
    (tsp.cell_tsmart_wireless_confidence_score between 1 and 5 OR
    vb.voterbase_phone IS NOT NULL)"

mode

• count - Returns a count of available records matching where clause
• distinct - Returns a count of distinct records matching where clause
• pivot - Returns pairwise counts on two fields. Counts are limited to a 500 column by 10,000 row pivot table.
  Warning, results may be incomplete if they exceed this limit.
• list - Returns a sorted list of limit available VoterBase IDs matching where clause
• sample - Returns a Bernoulli sample of a list as defined above

percentage

This parameter is required when mode=sample. When percentage=n, the service will return approximately n% results from the population defined by the where clause. Recommended use is to first submit a where request with mode=count to get a count of available results, then choose a percentage that provides the desired number of records, less than the maximum of 500,000. To ensure all records in the sample set are returned, set limit to “count”. If a specific number of records is desired, set the percentage slightly higher than required, and limit to desired number of records.

fields

Optional parameter combined with count, distinct, or pivot. When this is present, the counts returned are broken down by field as json. For example:

With count and {'fields': 'vb.tsmart_first_name,vb.voterbase_email'}

{count:{'vb.tsmart_first_name': '10033731', 'vb.voterbase_email': '5948429'}}

With pivot and {'fields': 'vb.voterbase_gender,vb.voterbase_email_presence_flag'}

{count:[{"vb.voterbase_gender":"Female","vb.voterbase_email_presence_flag":"Y","total":8103},
    {"vb.voterbase_gender":"Male","vb.voterbase_email_presence_flag":"Y","total":7724},
    {"vb.voterbase_gender":"Unknown","vb.voterbase_email_presence_flag":"Y","total":1738},
    {"vb.voterbase_gender":"Male","vb.voterbase_email_presence_flag":"N","total":6198},
    {"vb.voterbase_gender":"Female","vb.voterbase_email_presence_flag":"N","total":6122},
    {"vb.voterbase_gender":"Unknown","vb.voterbase_email_presence_flag":"N","total":2737}]}

format

Optional with mode=pivot. Defaults to json, may set to csv to get results as a csv string.

limit

A request with mode = list will return up to 500,000 IDs.

Recommended use is to first submit a where request with mode=count to get a count of available results, and then run the same where query with limit set to desired list length. The maximum number of results returned by a request is 500,000. However, there may be cases where your query takes too long to run and times out before all results can be fetched. If you encounter a timeout, or require more than 500,000 IDs, reformat your query into smaller parts.

JSON Response¶

Responses are JSON objects with the following keys:

• count: if mode = count a count of available records matching where clause, else the number of VoterBase IDs returned with this request – if fields are included, the count value is a json of {<field>:<count>}. if mode=pivot the value is either json (default) or csv string of the pivot results.
• list: list of VoterBase IDs or empty list
• bytes_scanned: database bytes scanned to complete the request

An example response (Note: Your responses will have different data fields based on your configuration):

{
    "count": 3,
    "list": ["OH-000123", "OH-000456", "OH-000789"]
}

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/person/listbuilder",
    params={
        "mode": "list",
        "where": "vb.voterbase_gender='Male' AND vb.vf_source_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({
  mode: "list",
  where: "vb.voterbase_gender='Male' AND vb.vf_source_state = 'OH'",
});

fetch(
  "https://api.targetsmart.com/person/listbuilder?" + 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/person/listbuilder?mode=list&where=vb.voterbase_gender%3D%27Male%27%20AND%20vb.vf_source_state%20%3D%20%27OH%27")
echo $result