Use the Personalization API to retrieve information about an email, hashed email, or postal address. Sign up to receive your unique API Key.
- 1 Requests
- 1.1 Request Examples
- 1.2 Common Parameters
- 1.3 Email Parameters
- 1.4 Postal Parameters
- 1.5 Optional Parameters
- 1.6 Query by Element
- 1.7 Sample Emails and Postals
- 2 Responses
- 2.1 HTTP Status Codes
- 2.2 Example Response
- 3. Copy 'n' Paste Code Snippets
- 3. Extras
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&show_available&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.
| Parameter | Description |
|---|---|
| api_key | This API key is assigned to you by Rapleaf 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 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.
| Parameter | Description |
|---|---|
| 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.
| Parameter | Description |
|---|---|
| format |
You can change the output format to pretty print responses as HTML within a browser. E.x. "format=html" |
| show_available | Adding "show_available" as a parameter will display all fields that are available about the given user. If the API account is not subscribed to a field, the value returned will be "Data Available". E.x "show_available=true" |
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@rapleaf.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@rapleaf.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 Address | Name and Postal Address |
|---|---|
| vlad@rapleafdemo.com | Vladinski Volvo 27346 Post St. San Francisco CA 94109 |
| anders@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 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@rapleaf.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@rapleaf.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"
}
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
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
from rapleafApi import RapleafApi
api = RapleafApi.RapleafApi('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
<?php
namespace Rapleaf;
include "RapleafApi.php";
$api = new RapleafApi(YOUR_RAPLEAF_API_KEY);
try {
$response = $api -> query_by_email('test@example.com',
$hash_email = true);
foreach ($response as $key => $value) {
echo $key . " = " . $value . "n";
}
} catch (Exception $e) {
echo 'Caught exception: ' . $e->getMessage() . "n";
}
?>
Java
import org.json.JSONObject;
import com.rapleaf.api.personalization.RapleafApi;
public class Test {
public static void main(String[] args) {
RapleafApi 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
do 'RapleafApi.pl';
eval {
my $response = query_by_email('test@example.com');
while(my ($k, $v) = each %$response) {
print "$k = $v.\n";
}
};
if ($@) {
print $@
}
C♯
using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using personalization;
namespace MyApplication {
class RapleafExample {
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 Rapleaf Developer Support.