Bulk Personalization API Documentation

This API will allow you to query TowerData’s Personalization API in bulk, for up to 10,000 people at a time. Sign up to receive your unique TowerData API Key.

Note: This API supports one concurrent request per customer. A second request for a given customer will only execute once the first has finished.

Requests

This API can be queried with HTTP POST requests with a JSON array as the Body. Make sure to set the Content-Type header to “application/json”.

 

Request URL

The API key must be supplied as part of the Request URL.

https://personalize.rapleaf.com/v4/bulk?api_key=78ad9ddc21e3c220cc5da024b6dbe13c

Request Body

The API input is a JSON array of Personalization API Parameters, which are email, name, and postal data pertaining to people. This array can have up to 10,000 elements.

 

Responses

Successful responses are returned as a JSON array of Personalization API Responses guaranteed to be in the same order as the input data. Note that un-matched people will still return an empty JSON hash “{}”. If there is an error for a specific record, we return {“error_code”:XXX, “error_msg”:”The error message”}. For example, if the email is not a valid email address, we return {“error_code”:400, “error_msg”:”Invalid identifier.”}.

HTTP Status Codes

General errors are provided via HTTP Status Code, as in the Personalization API HTTP Status Codes. In addition, bulk API error messages for 400 Bad Request include:

  • 1. “Invalid JSON.”: Common cause is not setting the content type to “application/json”.
  • 2. “Too many records requested. Limit is 10000 and you requested 10001.”

Example Response

Post Body:

[
{"email":"unknown_email@example.com"},
{"email":"personalize@example.com","first":"John","last":"Doe"},
{"email":"personalize@example.com"},
{“email”:”NOT_AN_EMAIL_ADDRESS”}
]

Rapleaf Response:

[
{},
{"age":"25-34","gender":"Male"},
{"age":"25-34","gender":"Male"},
{“error_code”:400, “error_msg”:”Invalid identifier.”}
]

Example Using Curl

Using Curl will require you to set content type to “application/json”.

Curl Request for two people:

curl -H "Content-Type: application/json" -d '[{"email":"personalize@example.com", "first":"John", "last":"Doe"}, {"email":"unknown_email@rapleaf.com"}]' https://personalize.rapleaf.com/v4/bulk?api_key=78ad9ddc21e3c220cc5da024b6dbe13c

Curl Response:

[
{"age":"25-34","gender":"Male"},
{}
]

 

Please email questions to TowerData Developer Support

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