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.

Requests

The API can be queried with HTTP GET requests.

https://personalize.rapleaf.com/v4/dr?first=John&last=Doe&email=personalize%40example.com&api_key=78ad9ddc21e3c220cc5da024b6dbe13c&format=html

 

Request Examples

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

https://personalize.rapleaf.com/v4/dr?first=John&last=Doe&email=personalize%40example.com&api_key=78ad9ddc21e3c220cc5da024b6dbe13c

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

https://personalize.rapleaf.com/v4/dr?first=John&last=Doe&email=personalize%40example.com&api_key=78ad9ddc21e3c220cc5da024b6dbe13c&format=html

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

https://personalize.rapleaf.com/v4/dr?md5_email=5003bd7a456bdcc37e4f51984de9efcb&api_key=78ad9ddc21e3c220cc5da024b6dbe13c

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

https://personalize.rapleaf.com/v4/dr?sha1_email=abdb6425aaf715b65c17510bbfe382571374f859&api_key=78ad9ddc21e3c220cc5da024b6dbe13c

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

https://personalize.rapleaf.com/v4/dr?email=john%40doe.com&street=667%20Mission%20Street&city=San%20Francisco&state=CA&zip4=94105-0123&first=John&last=Doe&middle=M&api_key=78ad9ddc21e3c220cc5da024b6dbe13c

Common Parameters

These parameters are required for all uses.

ParameterDescription
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.

ParameterDescription
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 zip4 must be provided or street, city, and state.
Tip: All postal parameters should be URL encoded.

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

ParameterDescription
first First name of person
middle
(optional)
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
zip4 or 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.

ParameterDescription
format
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:

https://personalize.rapleaf.com/v4/dr?api_key=78ad9ddc21e3c220cc5da024b6dbe13c&email=personalize@towerdata.com

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.

https://personalize.rapleaf.com/v4/dr?api_key=78ad9ddc21e3c220cc5da024b6dbe13c&email=personalize@towerdata.com&fields=gender,household_income,Charitable%20Donors

Please note the %20 is simply the URL encoded space which is needed (you must exactly match
the field name as it appears in the response for this to work).

Sample Emails and Postals

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

Email AddressName 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

 

Responses

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 CodeDescription
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.
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

{
  "age":"21-24",
  "gender":"Male",
  "interests":{
    "Blogging":true,
    "High-End Brand Buyer":true,
    "Sports":true,
  },
  "education":"Completed Graduate School",
  "occupation":"Professional",
  "children":"No",
  "household_income":"75k-100k",
  "marital_status":"Single",
  "home_owner_status":"Rent"
}
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#

Ruby

This snippit requires the towerdata_api gem (gem install rapleaf_api).
require 'rapleaf_api'
begin
  api = RapleafApi::Api.new("API_KEY") # Set API key here
  hash = api.query_by_email("test@example.com")
  puts hash.inspect
rescue Exception => e
  puts e.message
end

Python

This snippit requires the towerdata_Api python module, which depends on the urllib3 module. (easy_install urllib3 rapleafApi).

 

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

PHP

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.)

 

 

Java

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

 

import org.json.JSONObject;
import com.rapleaf.api.personalization.RapleafApi;

public class Test {
  public static void main(String[] args) {
    TowerDataApi api = new RapleafApi("API_KEY"); // Set API key here
    try {
      JSONObject response = api.queryByEmail("test@example.com", 
                                             true);
      System.out.println(response);
    } catch (Exception e) {
      e.printStackTrace();
    }
  }
}

Perl

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.

 

do 'TowerDataApi.pl';
eval {
  my $response = query_by_email('test@example.com');
  while(my ($k, $v) = each %$response) {
      print "$k = $v.\n";
  }
};
if ($@) {
  print $@
}

C♯

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

 

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using personalization;

namespace MyApplication {
  class TowerDataExample {
    public static void Main(string[] args) {
      RapleafApi api = new RapleafApi("SET_ME"); // Set API key here
      try {
        Dictionary<string, string=""> response = api.queryByEmail("test@example.com",
                                               true);
        foreach (KeyValuePair<string, object=""> kvp in response) {
          Console.WriteLine("{0}: {1}", kvp.Key, kvp.Value);
        }
      }
      catch (System.Net.WebException e) {
        Console.WriteLine(e.Message);
      }
    }
  }
}

Extras

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 API Key