<img height="1" width="1" alt="" style="display:none" src="https://www.facebook.com/tr?id=799187456795375&amp;ev=PixelInitialized">

Personalization API Documentation

Use the Personalization API to retrieve information about an email, hashed email, or postal address. Sign up to receive your unique API Key.


The API can be queried with HTTP GET requests.



Request Examples

Query email for user "John Doe" with email personalize@example.com:


Query email for user "John Doe" with email personalize@example.com and display in browser for testing purposes:


Query MD5 hashed email for user personalize@example.com:


Query SHA-1 hashed email for user personalize@example.com:


Query for user John Doe with email john@doe.com at 667 Mission St:


Common Parameters

These parameters are required for all uses.

Parameter Description
api_key This API key is assigned to you by TowerData when you register for our API. It is used to identify you to us, and authorize your request. This API key should be kept private, and should not be displayed publicly, in javascript, for example.

Email Parameters

These parameters are used to query with an email address.
Tip: Querying by email, name, and postal will give you the highest match rate. Querying by email and name will also give you a better match rate than by email alone.

Parameter Description
email email must be URL encoded.
E.x."per+sonalize@example.com" => "per%2Bsonalize%40example.com"
sha1_email SHA-1 hashed email. must be a hex encoded string. Email must be lowercased and stripped of whitespaces before being hashed.
E.x."personalize@example.com" => abdb6425aaf715b65c17510bbfe382571374f859
md5_email MD5 hashed email. must be a hex encoded string. Email must be lowercased and stripped of whitespaces before being hashed.
E.x."personalize@example.com" => 5003bd7a456bdcc37e4f51984de9efcb

Postal Parameters

These parameters are used to query with a postal address. Providing email parameters will increase the match rate. first and last name must always be provided to query via postal. Either street, city, state, and zip must be provided or street, city, and state or street and zip.
Tip: All postal parameters should be URL encoded.

Tip: It's recommended to use the standardized format for postal addresses.

Parameter Description
first First name of person
Middle name of person
last Last name of person
street Street number and street name you wish to search
city Name of city in address
state The two letter state abbreviation
zip Five-digit zip and four-digit extension separated by a dash

Optional Parameters

These parameters are optional to aid viewing query responses within a browser.

Parameter Description
You can change the output format to pretty print responses as HTML within a browser. E.x. "format=html"

Query by Element

In order to query for a certain field, you can simply use the fields parameter on the end of your query string. For example, a regular query of personalize@rapleaf.com with your API key would look like this:


Now if you simply add the fields parameter followed by specific comma separated fields (as they appear in the response), you can view just the specific fields you queried for in the response.



Sample Emails and Postals

Here are a few email addresses and name and postal address combinations you can try out with our API:

Email Address Name and Postal Address
vlad@rapleafdemo.com Vladinski Volvo 27346 Post St. San Francisco CA 94109
anderson@rapleafdemo.com Anderson Jefferson 99 Franklin St. San Francisco CA 94109
caitlin@rapleafdemo.com Caitlin Plackard 789 Chestnut St. San Francisco CA 94123
grant@rapleafdemo.com Grant Leopold 38997 Embarcadero St. San Francisco CA 94123
alex@rapleafdemo.com Alex Andover 12345 Mission St. San Francisco CA 94105
pete@rapleafdemo.com Peter Schlick 112134 Leavenworth Rd. San Francisco CA 94109



GET Response

Successful responses are returned in JSON format. For more details about all the fields available and their possible values, download our data dictionary.

HTTP Status Codes

Status Code Description
200 OK Request processed successfully.
302 Redirect Your API key is not yet activated. Please load this URL in a browser to click through the Terms of Service before proceeding.
400 Bad Request Some part of the request was invalid. The response body will give further explanation as to what the problem is. Usually this means the email address was invalid, some of the parameters were not url encoded, or no parameters were passed.
401 Unauthorized API key was not provided or is invalid.
403 Forbidden Your query limit has been exceeded, or the API key is not associated with any available response section.Contact developer@towerdata.com if you would like to increase your limit or add available response sections.
429 Too Many Requests Rate limits have been exceeded. If you call the API more than 500 times per second, you will receive this error. Reduce the rate of your requests.
500 Internal Server Error There was an unexpected error on our server. This should be very rare and if you see it please contact developer@towerdata.com.

Note: This list does not cover all possible HTTP Status Codes that could be returned, only those returned specifically from our API. For example, if the request cannot make it to our API you will likely get a "503 Service Unavailable" response. With this in mind do not code exclusively to handle the response codes listed above.

Example JSON Response

  "education":"Completed Graduate School",
For more details about all the fields available and their possible values, download our data dictionary.


Copy 'n' Paste Code Snippets

The Personalization API is easy to implement in a variety of languages. The code snippets below use the libraries on our GitHub Page to query our API and output the results. For more details, please consult each library's accompanying README docs.

Ruby | Python | PHP | Java | Perl | C#


This snippit requires the towerdata_api gem (gem install towerdata_api).
require 'towerdata_api'
  api = TowerDataApi::Api.new("API_KEY") # Set API key here
  hash = api.query_by_email("personalize@rapleaf.com")
  puts hash.inspect
rescue Exception => e
  puts e.message


This snippit requires the towerdata_Api python module, which depends on the urllib3 module. (pip install towerDataApi).


from towerDataApi import TowerDataApi
api = TowerDataApi.TowerDataApi('API_KEY')
  response = api.query_by_email('personalize@rapleaf.com')
  for k, v in response.iteritems():
    print '%s = %s' % (k, v)
except Exception as e:
  print e


This snippit requires the TowerData Api library for PHP5. Make sure to set your API key at the top of RapleafApi.php. (Not on PHP5? Check out our devkit for older versions of PHP.)


namespace TowerData;
include "TowerDataApi.php";

$person = $argv[1];
$response = query_by_email($person, false);


This snippit relies on the towerdata-api-complete jar, which you can find in TowerData's Java devkit onGitHub.


import org.json.JSONObject;
import com.towerdata.api.personalization.TowerDataApi;

public class TowerDataApiExample {
  public static void main(String[] args) {
    TowerDataApi api = (args[0] != null) ? new TowerDataApi(args[0]):new TowerDataApi("YOUR_KEY"); // Set API key here
final String email = (args[1] != null) ? args[1]:"personalize@rapleaf.com";

// Query by email try { JSONObject response = api.queryByEmail(email, true); System.out.println("Query by email: \n" + response); } catch (Exception e) { e.printStackTrace(); } } }


This snippit requires the TowerData API library for Perl, which depends on the JSON module (perl -MCPAN -e 'install JSON'). Make sure to set your API key at the top of RapleafApi.pl.


use 'TowerDataAPI.pm';
eval {
  my $response = query_by_email('pete@rapleafdemo.com');
  while(my ($k, $v) = each %$response) {
      print "$k = $v.\n";
if ($@) {
  print $@


This snippit relies on the TowerDataApi dll, which you can find in TowerData's C♯ API devkit onGitHub.


using System.Collections.Generic;
using System;
using System.Net;
using Personalization;

namespace example
    class TowerDataExample
        // outlined below are three separate ways of querying the API using the TowerDataApi library
        public static void Main(string[] args)
            TowerDataApi api = (args.Length >= 1 && args[0] != null) ? new TowerDataApi(args[0]) : new TowerDataApi("YOUR_API_KEY");
            String email = (args.Length >= 2 && args[1] != null) ? args[1] : "pete@rapleafdemo.com";

            // Query by email
            Console.WriteLine("\nQuery by email: "+email+"\n");
                Dictionary<string, object=""> response = api.queryByEmail(email);
                foreach (KeyValuePair<string, object=""> kvp in response)
            catch (WebException e)

        private static void printKeyValuePair(KeyValuePair<string, object=""> kvp)
            if (kvp.Value is Dictionary<string, object="">)
                Console.WriteLine("--" + kvp.Key + "--");
                foreach (KeyValuePair<string, object=""> sub_kvp in (Dictionary<string, object="">)kvp.Value)
                Console.WriteLine("--" + kvp.Key + "--");
                Console.WriteLine("{0}: {1}", kvp.Key, kvp.Value);


Need to query multiple people in a single request? Check out the Personalization API, Bulk Version.

If you add '&format=html' to the url of a request in your browser, it will automatically 'pretty print' JSON for testing purposes.

Please email questions to TowerData Developer Support.

1,000 free age and gender queries. Get your API Key now!