NAV Navbar
CURL RUBY PYTHON JAVA JAVASCRIPT C#
  • TOPICS
  • EMAIL VALIDATION
  • EMAIL INTELLIGENCE
  • bulk email intelligence
  • LIST API
  • DEVELOPER LIBRARIES
  • SUPPORT
  • TOPICS

    Introduction

    TowerData API's help you to improve the quality and depth of your data by enabling you to quickly and securely verify email addresses and match demographics and behavioral data to your customer list in real-time.

    Our APIs are built with REST and data is returned in the JSON format. The API's are designed to be easy to use, and we provide API libraries to help you use them with several popular programming languages.

    Our API requests must be made using HTTPS and require an API key.

    TowerData's API's

    The following API's vary in which services they support, the quantity of records they can be queried with and how they return results.

    Try them now by registering for your free 100 age, gender and email validation queries.

    Authentication

    Example Email Validation API Request Code

    GET "https://api.towerdata.com/v5/ev?email=johndoe@yahoo.com&api_key=1234567890feedfacecafe1234567890"
    
    require 'uri'
    require 'net/http'
    url = URI("https://api.towerdata.com/v5/ev?timeout=10&email=johndoe%40yahoo.com&api_key=1234567890feedfacecafe1234567890")
    http = Net::HTTP.new(url.host, url.port)
    http.use_ssl = true
    http.verify_mode = OpenSSL::SSL::VERIFY_NONE
    request = Net::HTTP::Get.new(url)
    response = http.request(request)
    puts response.read_body
    
    import requests
    url = "https://api.towerdata.com/v5/ev"
    querystring = {"timeout":"10","email":"johndoe@yahoo.com","api_key":"1234567890feedfacecafe1234567890"}
    response = requests.request("GET", url, params=querystring)
    print(response.text)
    
    HttpResponse<String> response = Unirest.get("https://api.towerdata.com/v5/ev?timeout=10&email=johndoe%40yahoo.com&api_key=1234567890feedfacecafe1234567890")
    .asString();
    
    var settings = {
      "async": true,
      "crossDomain": true,
      "url": "https://api.towerdata.com/v5/ev?timeout=10&email=johndoe%40yahoo.com&api_key=1234567890feedfacecafe1234567890",
      "method": "GET",
      "headers": {  }
    }
    $.ajax(settings).done(function (response) {
      console.log(response);
    });
    
    var client = new RestClient("https://api.towerdata.com/v5/ev?email=johndoe%40yahoo.com&api_key=1234567890feedfacecafe1234567890");
    var request = new RestRequest(Method.GET);
    IRestResponse response = client.Execute(request);
    

    Replace 1234567890feedfacecafe1234567890 with your actual API key.

    To obtain a TowerData API key, first register here.

    To find your API key in your dashboard, click the API link in the top navigation. On the API page you'll see your API key like this example:

    b3caaf6d9efd4a9632eedb1c1b181a24 - API Key 1

    Your API key will immediately active for a limited trial of Email Validation and our Email Intelligence fields. Please keep your key safe and secret so it is not abused.

    EMAIL VALIDATION

    Introduction

    TowerData specializes in email address validation. We can help you filter out invalid and fraudulent email addresses which results in higher open rates, clicks and conversions.

    Our Email Validation service provides users with the following:

    Feature Benefit
    Syntax Engine Pinpoints invalid email formats.
    Email Correction Fixes address misspellings.
    Suppression Safeguards your list from spam traps and complainers.
    Domain Database Monitors email domain status for accuracy.
    Mailbox Check Determines whether an address will soft bounce, hard bounce or deliver.
    Status Codes Returns 30 diagnostic codes distinguishing good emails from bad and why.
    Activity Metrics Describes email age, activity and last open date.

    Validation API Endpoint

    Email Validation Endpoint

    https://api.towerdata.com/v5/ev
    

    The endpoint to verify a single email address is in the right column.

    Query Parameters

    The query parameters for Email Validation are shown in the table below.

    Parameter Required Description
    email yes The email address to be validated (and optionally corrected). The address should be URL encoded as needed.
    timeout no Timeout value in seconds; default is 10 and max is 30 (seconds). Floating-point numbers (e.g. 4.9, 3.55) are permitted.

    Example

    Email Validation Sample Query

    https://api.towerdata.com/v5/ev?email=bill,smith%40towerdata.com&api_key=78ad9ddc21e3c220cc5da024b6dbe13c
    

    Replace 78ad9ddc21e3c220cc5da024b6dbe13c with your API key.

    An Email Validation example query is in the right column.

    Response Overview

    {
      "email_validation": {
        "status": "invalid"
        "status_code": 110,
        "address": "bill,smith@towerdata.com",
        "domain_type": "biz",
        "email_corrections": [
          "bill.smith@towerdata.com"
        ],
      }
    }
    

    If your request contains an email parameter and your API key is configured for Email Validation, the API response will contain an “email_validation” section in JSON format like the example in the right column.

    The “email_validation” section will contain the following information:

    Field Description
    address Contains the email address you queried with in a standardized format.
    status A string describing the category of the email validation result. See our full List of Values.
    status_code A range from 5-999 will always be returned and describes the detailed results of the validation within the "status" categorization. Refer to Status Codes for a full list of codes and their descriptions.
    domain_type An optional field, domain_type indicates the type of the domain including, “disposable”, “freeisp”, etc. Refer to Domain Types for a full list of domains and their descriptions.
    role_account An optional field, role_account is returned if the email address is identified as the role related email account. A role account is an email address for a business job role or a group of people in a company such as sales, info, support, marketing or customer service (e.g. info@abc.com). Because role accounts are not intended for a single person, commercial emails are usually flagged as spam. For improved deliverability, we recommend only sending transactional emails to role accounts.
    email_corrections An optional field, if your API key is configured for corrections, and the input address has a syntax or spelling error, we may suggest one or more corrected forms of the address. The returned value is a JSON array of possible corrected email addresses, although most often there is only one email address returned like this example: "email_corrections":[ "johndoe@gmail.com"].

    Sample Responses

    The Email Validation sample responses below provide example requests and responses to help you learn the behavior of our API. Sample data values are in the right column.

    Valid email

    Valid Email Request

    GET https://api.towerdata.com/v5/ev?email=johndoe@yahoo.com&api_key={API-Key}
    

    Response

    {  
       "email_validation":{  
          "status":"valid",
          "domain_type":"freeisp",
          "status_code":50,
          "address":"johndoe@yahoo.com"
       }
    }
    

    A valid email address has accurate syntax, a working domain and can receive email. In the right column is the sample request and response.

    Invalid email address & correction

    Invalid Email Request

    GET https://api.towerdata.com/v5/ev?email=johndoe@imaginerealty.com&api_key={API-Key}
    

    Response

    {  
       "email_validation":{  
          "status":"invalid",
          "status_code":325,
          "address":"johndoe@imaginerealty.com"
       }
    }
    

    An email address will be invalid if it has a syntax error, a bad domain, or the mailbox doesn't exist or can not receive email. The status_code in the response can be used to determine the specific reason the address is invalid. In the right column is the sample request and response.

    Unverifiable email

    Unverifiable Email Request

    GET https://api.towerdata.com/v5/ev?email=johndoe@ablboats.com&api_key={API-Key}
    

    Response

    {  
       "email_validation":{  
          "status_code":45,
          "address":"johndoe@ablboats.com",
          "status":"unverifiable"
       }
    }
    

    Some domains don't support email verification. These domains are also known as "accept all" or "catchall" domains, and, in these cases, we can't determine whether an address is valid or not. In the right column is the sample request and response.

    Unknown status

    Unknown Status Request

    GET https://api.towerdata.com/v5/ev?email=johndoe@twlakes.net&api_key={API-Key}
    

    Response

    {  
       "email_validation":{  
          "status":"unknown",
          "domain_type":"paidisp",
          "status_code":20,
          "address":"johndoe@twlakes.net"
       }
    }
    

    TowerData has to connect to a domain in real-time to verify each email address, and sometimes we’re not able to get through in time. An unknown status means we didn’t get a response, but, if you try again later, we may be able to fully verify the address. In the right column is the sample request and response.

    Risky email

    Risky Email Request

    GET https://api.towerdata.com/v5/ev?email=risky@hotmail.com&api_key={API-Key}
    

    Response

    {  
       "email_validation":{  
          "status_code":525,
          "address":"risky@hotmail.com",
          "status":"risky"
       }
    }
    

    Risky addresses are valid but may cause delivery issues (e.g. spamtrap, honeypot or complainer). If you’re having deliverability issues, don’t send email to these addresses. In the right column is the sample request and response.

    Disposable email

    Disposable Email Request

    GET https://api.towerdata.com/v5/ev?email=johndoe@mailinator.com&api_key={API-Key}
    

    Response

    {  
      "email_validation":{  
         "status":"unverifiable",
         "domain_type":"disposable",
         "status_code":45,
         "address":"johndoe@mailinator.com"
       }
    }
    

    A disposable email address is either for temporary use, to mask the identity of the user or to uniquely identify the website it is registered on. Depending on your application, you may or may not want to accept disposable emails. In the right column is the sample request and response.

    Role account

    Role Account Request

    GET https://api.towerdata.com/v5/ev?email=info@towerdata.com&api_key={API-Key}
    

    Response

    {  
       "email_validation":{  
          "Status":"valid",
          "domain_type":"biz",
          "status_code":50,
          "address":"info@towerdata.com",
          "role_account":true;
       }
    }
    

    A role account is a group mailbox often managed by multiple people. While transactional emails are safe to send to role accounts, you may not want to send newsletters to them in case one of the recipients marks it as spam. In the right column is the sample request and response.

    Invalid API key

    Invalid API Key Request

    GET https://api.towerdata.com/v5/ev?email=c@i.com&api_key={Missing or bad API-Key}
    

    Response

    Invalid API Key
    

    An invalid API key response means your key is either inactive or you’re requesting data the key isn't permitted to retrieve based on your user credentials. Login to your Dashboard to check your API key. In the right column is the sample request and response.

    Lists of Values

    Email status

    Every validation response will include one of the status values below:

    Status Description
    valid The email address passed all checks and is safe to mail.
    invalid Do not mail. The email does not have proper syntax, the domain is dead or the mailbox doesn't exist.
    risky The email address is valid but it may cause delivery issues (e.g. spamtrap, honeypot or complainer). If you’re having deliverability issues, don’t send email to risky addresses.
    unverifiable The domain doesn’t support a mailbox level check. Also known as an "accept all" or "catch all" domain. Expect some bounces from these addresses should you choose to mail them.
    unknown We couldn't get a response in time. The email syntax and domain are usually valid, but we could not confirm the mailbox. Messages to these addresses may see bounces. Repeating the query later may deliver a valid/invalid status.

    Status codes

    The status_code field is a number ranging from 5-999, will always be present in the response and describes the detailed results of the validation. In the table below is our full list of status codes, which status value it corresponds to and their descriptions.

    Status Code Description
    unknown 5 Timeout. Did not get a response in time.
    unknown 10 Syntax OK.
    unknown 20 Syntax OK and the domain is valid.
    unverifiable 45 Domain is a catch all and does not support validation.
    valid 50 Valid email address.
    invalid 100 General syntax error.
    invalid 110 Invalid character in address.
    invalid 115 Invalid domain syntax.
    invalid 120 Invalid username syntax.
    invalid 125 Invalid username syntax for that domain.
    invalid 130 Address is too long.
    invalid 135 Address has unbalanced parentheses.
    invalid 140 Address doesn’t have a username.
    invalid 145 Address doesn’t have a domain.
    invalid 150 Address doesn’t have an @ sign.
    invalid 155 Address has more than one @ sign.
    invalid 200 Invalid top-level domain (TLD) in address.
    invalid 205 IP address is not allowed as a domain.
    invalid 210 Address contains an extra space or character.
    invalid 215 Unquoted spaces not allowed in email addresses.
    invalid 310 Domain doesn’t exist.
    invalid 315 Domain doesn’t have a valid IP address.
    invalid 325 Domain can’t receive email.
    invalid 400 Mailbox doesn't exist.
    invalid 410 The mailbox is full and can’t receive email.
    invalid 420 Mail isn't accepted for this domain.
    invalid 500 Emails with that username aren’t accepted.
    invalid 505 Emails with that domain aren’t accepted.
    invalid 510 That address isn’t accepted.
    invalid 520 Address matched to known bouncers (optional feature).
    risky 525 Address is a spamtrap, a known complainer or is suppressed.
    risky 530 Address has opted out from commercial email.
    unknown 999 System error.

    Domain types

    The domain_type field will be present in the response if the type of domain has been categorized. The table below shows the full list of domain types and their descriptions.

    Domain_type Description
    biz The domain of a company.
    disposable Disposable domain.
    edu An educational institution.
    freeisp Free ISP (internet service provider).
    gov A government institution.
    org A non-profit organization.
    paidisp Paid ISP.
    wireless Wireless domain. Do not send unsolicited emails.

    EMAIL INTELLIGENCE

    Introduction

    TowerData’s Email Intelligence API helps you to understand who your customers are and to segment them by their attributes by providing 50+ demographic and behavioral data fields. Improve personalization and create more targeted, relevant content by obtaining:

    Try it for free.

    Intelligence API Endpoint

    Email Intelligence Endpoint

    https://api.towerdata.com/v5/td
    

    The endpoint to obtain data on a single person, using email and/or postal address, is in the right column.

    Query Parameters

    The Intelligence API may be queried by email address and/or by postal address.

    The section immediately below describes how to call with one contact record at a time. You may call with 5,000 records at a time using the Bulk API and you can submit files with up to one million records using the List API.

    All calls must be authenticated with your API key.

    Email parameters

    email Example

    per+sonalize@example.com outputs to: per%2Bsonalize%40example.com
    

    sha1_email Example

    personalize@example.com outputs to: abdb6425aaf715b65c17510bbfe382571374f859
    

    md5_email Example

    personalize@example.com outputs to: 5003bd7a456bdcc37e4f51984de9efcb
    

    While Email Validation does not accept them, the Email Intelligence API may be queried with SHA1 and MD5 hashed forms of an email address. Be sure to use lower case characters and trim prior to hashing.

    In the right column are the parameter examples used to query with an email address.

    Parameter Description
    email The raw email address. It must be URL encoded.
    sha1_email SHA-1 hashed email. The email must be lower case and stripped of white spaces before being hashed.
    md5_email MD5 hashed email. The email must be lower case and stripped of white spaces before being hashed.

    Name parameters

    Including the name parameters below increase the accuracy of our match and allows us to infer gender if it is not in our database.

    Parameter Description
    first First name of person.
    middle Middle name of person (optional).
    last Last name of person.

    Postal parameters

    The parameters below are used to query by United States postal address and, when used, name parameters must be included. All postal parameters should be URL encoded.

    Parameter Description
    street Street number & name.
    city Name of city.
    state Two letter state abbreviation.
    zip Five-digit zip and, optionally, four-digit extension separated by a dash.

    Optional parameters

    These parameters are optional.

    Parameter Description
    format You can change the output format to pretty print responses as HTML within a browser. Example: format=html.
    fields A comma-separated list of the data fields you want returned. By default, all available fields are returned.

    Specific Field Query Example

    https://api.towerdata.com/v5/td?api_key=78ad9ddc21e3c220cc5da024b6dbe13c&email=personalize@rapleaf.com&fields=gender,household_income,charitable_donors
    

    Replace 78ad9ddc21e3c220cc5da024b6dbe13c with your API key.

    If your API key is configured for multiple data fields, you can specify which ones you want returned by adding the field names to your query. You will only be charged for the data you receive. See the example in the right column.

    In the table below are sample field values you can test using the TowerData API:

    Email Address Name 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

    Example

    Sample Query

    https://api.towerdata.com/v5/td?api_key=78ad9ddc21e3c220cc5da024b6dbe13c&email=johndoe@yahoo.com&first=john&last=doe
    

    Replace 78ad9ddc21e3c220cc5da024b6dbe13c with your API key.

    The Email Intelligence example query is in the right column.

    Response Overview

    {
      "age":"35-44",
      "gender":"Male",
      "interests":{
        "automotive":true,
        "sports":true,
      },
      "eam":{
        "date_first_seen":"2009-06-20",
        "month_last_open":"2017-10",
        "velocity":2,
        "popularity":6
      },
      "aci": {
        "deal_seeker": {
          "value": "A"
        },
        "kids_and_babies": {
          "value": "B"
        },
        "electronics": {
          "value": "I"
        }
      },
      "education":"Completed Graduate School",
      "occupation":"Professional",
      "children":"Yes",
      "household_income":"75k-100k",
      "marital_status":"Married",
      "home_owner_status":"Rent"
    }
    

    If your API key is configured with Email Intelligence, the API response may contain one or more data fields like those shown in the right column.

    The Email Intelligence API includes the following types of fields:

    The response will contain only these fields activated for your API key and that match to the individual you included in the query parameters.

    For example, a successful call for age and income could return no fields if we do not have that email in our database or if the requested fields are not populated for that email.

    Demographic Data

    {
      "age":"35-44",
      "gender":"Female",
      "zip":"90210"
    }
    

    The Email Intelligence data fields below are matched to the individual in the query.

    Field Possible Values
    age 18-20, 21-24, 25-34, 35-44, 45-54, 55-64, 65+
    Gender Male, Female
    Zip 94105

    Household Data

    {
      "household_income":"35k-50k",
      "net_worth":"25k-50k",
      "home_owner_status":"Rent",
      "length_of_residence":"3 Years",
      "marital_status":"Single",
      "presence_of_children":"No",
      "education":"Completed College",
      "occupation":"Teacher"
    }
    

    The fields below correspond to the household of the individual in the query.

    Field Values
    household_income 0-15k, 15k-25k, 25k-35k, 35k-50k, 50k-75k, 75k-100k, 100k-125k, 125k-150k, 150k-175k, 175k-200k, 200k-250k, 250k+
    net_worth 0-5k, 5k-10k, 10k-25k, 25k-50k, 50k-100k, 100k-250k, 250k-500k, 500k-750k, 750k-1mm, 1mm+
    home_market_value 1k-25k, 25k-50k, 50k-75k, 75k-100k, 100k-150k, 150k-200k, 200k-250k, 250k-300k, 300k-350k, 350k-500k, 500k-1mm, 1mm+
    home_owner_status Own, Rent
    length_of_residence Less than 1 year, 1 Year, 2 Years, 3 Years, 4 Years, 5 Years, 6 Years, 7 Years, 8 Years, 9 Years, 10 Years, 11-15 years, 16-19 years, 20+ years
    marital_status Single, Married
    presence_of_children Yes, No
    education Completed High School, Attended College, Completed College, Completed Graduate School, Attended Vocational/Technical School
    occupation Blue Collar Worker, Business Owner, Civil Service, Executive/Upper Management, Health Services, Homemaker, Middle Management, Military Personnel, Nurse, Part Time, Professional, Retired, Secretary, Student, Teacher, Technology, White Collar Worker,

    Interest & Purchase Data

    Example Interest & Purchase Response

    {
      "interests":{"automotive":true,
                   "charitable_donors":true,
                   "cooking":true}
    }
    

    The interest and purchase data features the categories in the table below. The returned value true means the individual has displayed that interest or purchased in that category. If the field name is not present, it means we have not seen that behavior. The data is returned within the interests JSON object, as shown in the example in the right column.

    Field Value
    arts_and_crafts true
    automotive true
    baby_product_buyer true
    beauty true
    blogging true
    books true
    business true
    charitable_donors true
    cooking true
    discount_shopper true
    health_and_wellness true
    high_end_brand_buyer true
    home_and_garden true
    home_improvement true
    luxury_goods true
    magazine_buyer true
    news_and_current_events true
    outdoor_and_adventure true
    pets true
    sports true
    technology true
    travel true

    Active Customer Intelligence

    The Active Customer Intelligence (ACI) data is based upon online browsing and search behavior and provides the following information:

    Value Description
    Purchase intent Products that the individual is actively shopping for online.
    Life stage Milestone data such as newly-married, the purchase of a new home and recently had children.
    Lifestyle Collections of behaviors and interests such as Fashion Insiders, Tech Enthusiasts and more.
    Shopper type Deal seeker, luxury buyer, online buyer and more.

    Field descriptions

    Example ACI Response

    {
      "aci": {
        "deal_seeker": {
          "value": "A"
        },
        "kids_and_babies": {
          "value": "B"
        },
        "electronics": {
          "value": "I"
        }
      }
    }
    

    The Active Customer Intelligence data fields return a single letter value that describes the level of Internet searching and browsing activity the individual has shown in each category. There are four possible values as shown in the table below.

    Value Description
    M In-Market activity seen within the last 30 days.
    A Actively interested and searched or browsed for the product within the last 30-90 days.
    I Interested and seen within the last 3-12 months.
    B Bought products or services within the last 120 days.

    The table below contains the Active Customer Intelligence field values and descriptions. If there is no value for a field, it will not be in the response.

    Field Value Description
    Adrenaline A Adrenaline junkies are actively shopping for camping, hiking, biking, kayaking, skiing, snowboarding and other outdoor adventure sports gear.
    Appliances IBAM Consumers actively shopping online for appliances.
    Auto Parts IBAM Consumers actively shopping online for automotive parts, tires and accessories.
    Baby Products IBAM Consumers actively shopping online for baby items.
    Bathroom IBAM Consumers actively shopping online for bathroom accessories, hardware and towels.
    Beauty IBAM Consumers actively shopping online for health and beauty products.
    Beauty Style A Beauty mavens are defined by their consistent shopping behavior for beauty products such as cosmetics, hair care, skin care, perfume and beauty tools.
    Big Spender IBAM Consumers making big purchases spending large sums of money.
    Cats IBAM Consumers actively shopping online for cat supplies.
    Childrens Clothing IBAM Consumers actively shopping online for kids clothes and shoes.
    Computers IBAM Consumers actively shopping online for laptops, desktops and tablets.
    Computers & Software IBAM Consumers actively shopping online for computers and software.
    Connected A Consumers actively shopping for connected home technology. These include lighting, security, thermostat and voice-controlled devices.
    Cord Cutter A Consumers who cut traditional media services like cable. They buy streaming media solutions and prefer mobile devices for their content consumption.
    Cosmetics IBAM Consumers actively shopping online for cosmetics.
    Deal Seeker IBAM Consumers actively shopping online using coupons and discount comparison sites.
    Design A Consumers actively shopping for home décor products such as furniture, bedding sets, curtains, drapes, rugs and table linens.
    DIY Neighbors A Consumers actively shopping for do-it-yourself building supplies such as power tools, flooring supplies, plumbing supplies, hardware, electrical supplies and equipment.
    Dogs IBAM Consumers actively shopping online for dog supplies.
    Early Tech Adopters A Consumers actively shopping for new technologies. These consumers are defined as early tech adopters based on their shopping habits of new products and brands, general demographic data and website content visitation.
    Electronics IBAM Consumers actively shopping online for electronics.
    Engaged A Couples planning to marry. This field is defined by their shopping behavior for engagement rings, wedding bands, wedding dresses, wedding shoes, wedding invitations, wedding flowers and wedding décor.
    Expecting A Parents expecting a baby or likely to be expecting a baby based on their online shopping activity for maternity clothing and website visitation to pregnancy and parenting websites.
    Family CEO A Defined as being the decision-maker for purchases of products such as baby and kids items, kitchen, home and pets.
    Fashionista A Consumers actively shopping for handbags, shoes, dresses, jewelry and other fashion accessories.
    Fitness A Consumers actively shopping for fitness equipment, activewear, yoga and pilates gear, vitamins and nutritional supplements.
    Flowers IBAM Consumers actively shopping online for flowers.
    Food Gifts IBAM Consumers actively shopping online for food.
    Furniture IBAM Consumers actively shopping online for furniture.
    Gamer A Male consumers ages 18 to 44 actively shopping for video games, video game consoles, computers and electronics.
    Garden and Patio IBAM Consumers actively shopping online for gardening, landscaping and outdoor supplies.
    Gearhead A Consumers actively shopping for auto parts, auto accessories and tires.
    Gift Buyer IBAM Consumers actively shopping online for gifts.
    Hair Care IBAM Consumers actively shopping online for hair care products.
    Holiday Shopper IBAM Consumers actively shopping online for holiday accessories.
    Home Buyer A Home buyers or likely to become home buyers. This field is defined by online shopping habits.
    Home Furnishings IBAM Consumers actively shopping online for home décor.
    Home and Garden IBAM Consumers actively shopping online for home and garden products.
    Home Improvement IBAM Consumers actively shopping online for home improvement products.
    Jewelry IBAM Consumers actively shopping online for jewelry and watches.
    Kids and Babies IBAM Consumers actively shopping online for baby and kids products.
    Kitchen and Dining IBAM Consumers actively shopping online for cooking supplies, tableware and glassware.
    Lamps and Lighting IBAM Consumers actively shopping online for home lighting.
    Linens and Bedding IBAM Consumers actively shopping online for bedding.
    Luxury Shopper IBAM Consumers actively shopping for high-end fashion items and luxury brands.
    Mens Accessories IBAM Consumers actively shopping online for mens accessories.
    Mens Clothing IBAM Consumers actively shopping online for mens clothing.
    Mens Shoes IBAM Consumers actively shopping online for mens shoes.
    Millennial A College millennials are ages 18-24 attending universities and colleges.
    Mobile Phones IBAM Consumers actively shopping online for cell phones and smartphones.
    Mobile Phone Accessories IBAM Consumers actively shopping online for cell phone and smartphone accessories.
    Mom A Moms are identified by a core set of declared data at the individual level.
    New Parent A New parents are defined by their demographics and shopping behavior for infant and baby clothing, baby feeding products, strollers, car seats, baby furniture, infant toys and other baby gear.
    Nutrition IBAM Consumers actively shopping online for vitamins and nutritional products.
    Online Buyer IBAM Verified online buyers across the retail vertical.
    Outdoors A Consumers actively shopping for hunting, fishing, boating, camping and hiking gear.
    Perfume and Cologne IBAM Consumers actively shopping online for perfume and cologne.
    Pets and Supplies IBAM Consumers actively shopping online for pet supplies.
    Pet Lover A Consumers actively shopping for pet toys, food, health items and accessories for their dogs, cats and other pets.
    Printing and Copying IBAM Consumers actively shopping online for printers and ink.
    Skin Care IBAM Consumers actively shopping online for skin care products.
    Sports and Outdoors IBAM Consumers actively shopping online for sports equipment and outdoor gear.
    Team Player A Consumers actively shopping for baseball, softball, football, basketball, volleyball and hockey gear.
    Tech Fan A Consumers actively shopping for computers and electronics such as smartphones, tablets, TVs, speakers, headphones and digital cameras.
    Toys IBAM Consumers actively shopping online for toys and games.
    Video Games IBAM Consumers actively shopping online for video games.
    Womens Accessories IBAM Consumers actively shopping online for womens handbags, scarves, sunglasses and hats.
    Womens Clothing IBAM Consumers actively shopping online for womens clothing.
    Womens Shoes IBAM Consumers actively shopping online for womens shoes.

    Email Activity Metrics

    Example EAM Response

    {
      "eam":{"date_first_seen":"2008-04-09",
             "popularity":10,
             "longevity":3,
             "velocity":10,
             "month_last_open":"2017-07"}
    }
    

    The EAM fields provide information about the age and activity of an email address based on when and how often it has passed through the TowerData database. EAM data can be used to evaluate the legitimacy of an email address and whether it is actively used. An "eam" sample response is shown in the example in right column.

    The following table displays the EAM fields and their descriptions.

    Field Value Description
    date_first_seen YYYY-MM-DD The date the email address first appeared in TowerData's records. The value now will be returned if the email address is new to the TowerData database.
    longevity 0-3 A score describing when TowerData first encountered the email address. See table below for descriptions.
    velocity 0-10 A score reflecting the activity of the email address over the last 3 months, from 0 (no activity) to 10 (most active).
    popularity 0-10 A score gauging the popularity of the email address over the last 12 months based on the number of sources from which TowerData has received the address, from 0 (no sources in 12 months) to 10 (most sources).
    month_last_open YYYY-MM The year and month TowerData last detected an open by the email address in a rolling 12 month period.

    Longevity Field Values

    The following table describes the different values for longevity:

    Value Description
    0 TowerData has not encountered this email address before.
    1 TowerData first encountered this email within the last month.
    2 TowerData first encountered this email within the last year.
    3 TowerData first encountered this email over a year ago.

    Postal Append

    Example Postal Append Response

    {
      "postal_address": {
        "first_name": "ADAM",
        "last_name": "ERVIN",
        "address": "742 EVERGREEN TER APT 4",
        "city": "SPRINGFIELD",
        "state": "MA",
        "zip": "01107-2424"
      }
    }
    

    TowerData can match name and postal address to approximately 35% of U.S. email addresses, enabling direct mail marketing to your email prospects or helping you link email subscribers with your catalog or in-store customers. Postal data is DPV certified and NCOA'd once per year. A sample response is shown in the example in right column.

    HTTP Status Codes

    The Email Intelligence API may return the following HTTP Status Codes in the table below.

    Code Description
    200 Request OK.
    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. Either the api_key was missing or invalid.
    403 Forbidden. Your query limit has been exceeded, or the API key is not associated with any available response section.
    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.
    500 Internal server error. Please contact support.
    502 Bad gateway. The API is not available. Please try again later or contact support.

    bulk email intelligence

    Introduction

    TowerData’s Bulk Email Intelligence API allows you to synchronously query Email Intelligence for up to 5,000 people at a time.

    To process larger lists for Intelligence or any size of Email Validation files asynchronously, check out our List API.

    Sign up to get your TowerData API Key and give it a try.

    Bulk Intelligence Endpoint

    Bulk Email Intelligence Endpoint

    https://api.towerdata.com/v5/ei/bulk
    

    This endpoint can be used to query up to 5,000 records at a time for Email Intelligence (only).

    Requests

    Request URL

    https://api.towerdata.com/v5/ei/bulk?api_key=78ad9ddc21e3c220cc5da024b6dbe13c
    

    Replace 78ad9ddc21e3c220cc5da024b6dbe13c with your API key.

    Post Body

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

    The Bulk Email Intelligence API is queried with HTTP POST requests using a JSON array as the body. Set the Content-Type header to application/json.

    The JSON array in the POST BODY can contain up to 5,000 elements of personalization parameters. Each element in the array may contain email, name as well as postal parameters.

    Responses

    BULK Response

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

    Successful Bulk Email Intelligence responses are returned as an array of Email Intelligence responses. The elements in the response array will be in the same order as the query parameters in the query array.

    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"}, where XXX is based on the HTTP status code. For example, if the email is not a valid email address, we return {"error_code":400, "error_msg":”Invalid identifier.”}.

    Example using curl

    Curl Request

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

    Replace 78ad9ddc21e3c220cc5da024b6dbe13c with your API key.

    Curl Response

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

    When using Curl set the Content-Type: to application/json. In the right column is an example Curl request and response for two people.

    HTTP status codes

    In addition to the Email Intelligence HTTP status codes, the bulk API has the following additional error messages for 400 Bad Request:

    Error Description
    Invalid JSON The common cause of this error is not setting the Content-Type: to application/json.
    Too many records requested The quantity of records you requested exceeds our limit of 10000 (e.g. 10001).

    LIST API

    Introduction

    The TowerData List API can be used to process up to 1,000,000 customer records for Email Validation and/or Email Intelligence asynchronously. It provides faster results than calling the regular API's one record at a time. The List API allows you to

    LIST API Endpoint

    List API Endpoint

    https://api.towerdata.com/v5/list
    

    All calls to the List API use the endpoint shown in the right column.

    Submitting Lists

    There are two methods to submit a list:

    Example Multipart Method using Curl

    $ curl -X POST -H "api_key: 78ad9ddc21e3c220cc5da024b6dbe133" -H "Content-Type:multipart/form-data" -F "file=@customer_emails.zip" "https://api.towerdata.com/v5/list?email_column=1&header=true&delimiter=,&name=customer_emails.zip"
    

    Example Text/CSV Method Using Curl

    $ curl -X POST -H "api_key: 78ad9ddc21e3c220cc5da024b6dbe133" -H "Content-Type:multipart/form-data" -F "file=@customer_emails.csv" "https://api.towerdata.com/v5/list?email_column=1&header=true&delimiter=,&name=customer_emails.csv"
    

    Both methods require you to set a api_key header in the POST that contains your API key. See the examples in the right column.

    Optional parameters

    The optional parameters that can be used when submitting lists are in the table below.

    Parameter Example Description
    email_column email_column=1 The index of the column, starting at 1, containing the email addresses; default=1.
    header header=true Used to indicate the presense of a header line with values of true or false; default=false.
    delimiter delimiter="," The character used to separate multiple columns within the file; default variable is tab (\t).
    name name="abc.txt" File name, which must use one of these file extensions: .txt, .csv or .zip; default=myfile.csv.

    File format

    Example CSV File Format

    Email,First,Last,Address,City,State,Zip
    emaila@example.com,John,Doe,100 Main St Apt 12B,Springfield,MA,01020
    emailb@example.com,Mary,Smith,22 Clark Ave,Denton,TX,75065
    emailc@example.com,Greg,Flynn,16 Park Ave,New York,NY,10016
    

    The file format can contain unlimited delimiter separated columns. If more than one email column is in your file, you must specify which column to be processed using the email_column parameter. Submitted .csv files should contain a comma delimiter. Files with a .txt extension will be processed as tab delimited files.

    To ensure the file is properly parsed, use a header line in your first row to denote field data. See example CSV file format in the right column.

    Response

    Example Location Header

    Location: https://api.towerdata.com/v5/list/4321
    

    Example JSON Response

    {"list_id":4321,"size_bytes":22709}
    

    When a list is successfully submitted the List API will

    Check List Status

    Check List URL for list 4321

    https://api.towerdata.com/v5/list/4321
    

    Example Check List Request Using Curl

    $ curl -H 'api_key: 78ad9ddc21e3c220cc5da024b6dbe133' 'https://api.towerdata.com/v5/list/4321'
    

    Replace 78ad9ddc21e3c220cc5da024b6dbe133 with your API key

    Check the status of your uploaded list with a HTTP GET request. You can poll the URL https://api.towerdata.com/v5/list/{list_id} until your results are returned. Please wait 5 seconds between requests.

    See the example to the right.

    Response

    After the initial submission, the status query will return data in JSON as it's processing and will look like this:

    {
      "list_id": 4321,
      "name": "customer_emails.csv",
      "status": "Pending",
      "records": 1002,
      "size_bytes": 22709,
      "created_at": "2017-10-19T20:46:58Z",
      "services": {
        "email_validation": {
          "input_count": 1002,
          "completed_count": 100,
          "status": "Processing"
        },
        "email_validation": {
          "input_count": 1002,
          "completed_count": 700,
          "status": "Processing"
        }
      }
    }
    
    

    Once a service has successfully completed, a "reporting" object will be available for that service. For "email_validation", the completed return data will look like this:

    {
      "list_id": 4321,
      "name": "customer_emails.csv",
      "created_at": "2017-10-19T20:46:58Z",
      "status": "Results",
      "records": 1002,
      "size_bytes": 22709,
      "services": {
        "email_validation": {
          "status": "Completed",
          "input_count": 1002,
          "completed_count": 1002,
          "reporting": {
            "statuses": {
              "Corrected": 0,
              "Unknown": 47,
              "Valid": 723,
              "Risky": 0,
              "Unverifiable": 78,
              "Invalid": 154
            },
            "invalid_categories": {
              "Syntax Errors": 9,
              "Domain Errors": 19,
              "Mailbox Errors": 123,
              "Suppressions": 3
            },
            "domain_type": {
              "Disposable": 2,
              "Wireless": 0,
              "Free ISP": 591,
              "Unknown": 0,
              "Education": 33,
              "Government": 1,
              "Paid ISP": 117,
              "Non-profit": 35,
              "Business": 12
            },
            "status_codes": {
              "45": 78,
              "150": 1,
              "130": 0,
              "110": 2,
              "155": 1,
              "210": 1,
              "310": 13,
              "530": 0,
              "135": 1,
              "410": 0,
              "510": 0,
              "115": 1,
              "215": 0,
              "315": 3,
              "50": 723,
              "10": 0,
              "140": 1,
              "120": 0,
              "100": 0,
              "145": 0,
              "200": 0,
              "420": 0,
              "520": 0,
              "125": 1,
              "400": 123,
              "500": 1,
              "325": 3,
              "205": 0,
              "525": 0,
              "505": 2,
              "20": 29
            },
            "role_accounts": 6
          }
        },
        "email_intelligence": {
          "status": "Completed",
          "input_count": 1002,
          "completed_count": 1002,
        }
      }
    }
    

    TowerData will first parse your list and confirm it is in a valid format. Next, we'll process your list using the services your API key is configured for. In the right column are the steps.

    The following table displays the List Status Response file attributes and descriptions.

    Attribute Description
    list_id The TowerData numeric identifier for the list.
    name The name of the list.
    status The status of the list.
    records The quantity of non-blank records in the file that have data to be processed. Header records will not be included in this count.
    size_bytes The number of bytes of data that was originally contained in the list.
    created_at The date and time the list was submitted in ISO 8601 format. All times use the UTC time zone.
    services An object containing child objects for each service run on the list such as email_validation.
    input_count The quantity of input records for the current service.
    completed_count The quantity of records processed for the current service. To gauge your response progress, compare the completed_count value to the input_count value.

    In the table below are the processing status attributes and descriptions.

    Attribute Description
    cancelled The service was cancelled.
    completed The service has successfully completed.
    error The service failed and must be investigated or restarted.
    pending The service is waiting for the file to be fully parsed before starting.
    processing The service is currently running.

    The reporting attributes and descriptions are in the table below.

    Attribute Description
    domain_types The counts for the types of domains in the list.
    invalid_categories The invalid category reason.
    role_accounts The number of role account emails.
    statuses The summary counts for email validation status.
    status_codes The status code values in the list.

    Retrieve List Results

    GET URL

    https://api.towerdata.com/v5/list/{list_id}/result
    

    Once a list status returns "Results", you can retrieve a .ZIP file that contains the results for the services run on the list and save it locally. Issue a GET request using the URL in the right column.

    Curl Example Saving The towerdata_results_4321.zip File

    $ curl -H "api_key: 78ad9ddc21e3c220cc5da024b6dbe133" -o towerdata_results_34201.zip 'https://api.towerdata.com/v5/list/4321/results'
    

    For example, to save the file towerdata_results_4321.zip using curl, add the -o flag. See the example in the right column.

    Response

    Example Header Response

    Content-Disposition:attachment; filename=towerdata_results_{list_id}.zip Content-Type:application/zip
    

    Once your results are completed the call will return the HTTP 200 status, a header as shown to the right and a .ZIP file containing your data. The .ZIP file contains a folder for each service run as part of your API key as described below.

    Email intelligence results

    The Email Intelligence results are in the .ZIP file in a folder titled intelligence and may contain the following files:

    File Name Description
    towerdata_{list_id}_intelligence.{extension} Contains the results in .txt (tab delimited) or .csv (comma delimited) formats depending on the delimiter of the raw file. The results are based on your API account and are appended using the file's delimited format.
    towerdata_{list_id}_intelligence_summary.csv Reports the success of your query. Each row contains the field name, number of records matched and the match % (e.g. Gender,90,90.0%).
    towerdata_{list_id}_intelligence_charts.csv File is present when results include fields with standardized values. Each row contains field name, field value and record count (e.g. Gender,Male,43).
    towerdata_{list_id}_intelligence_charts.pdf A PDF containing charts showing the distribution of standardized values.

    Email validation results

    The Email Validation results are in a folder titled validation which contains two files described below.

    Field Description
    Validation Status A string describing the category of the email validation result. In addition to the Email Validation Status Values, there is a corrected status value that indicates the original email had a syntax or spelling error and a fix was made.
    Validation Code A numeric code that describes the detailed results of the validation within the "Validation Status" categorization. Refer to Status Codes for a full list of codes and their descriptions.
    Domain Type Indicates the type of the domain including, if known. Refer to the list of Domain Types.
    Role Account Has the value true if the email address is identified as a role related email account. Learn more here.
    Duplicate Has the value true if the email address appears elsewhere in the list.
    Valid Email The email addresses that can be safely mailed. Only email addresses with a status of valid or corrected appear here. If the status was corrected, the corrected form of the address appears in this column.

    HTTP Status Codes

    The List API may return the following HTTP Status Codes in the table below.

    Code Description
    200 Request OK.
    202 Request accepted.
    400 Bad request. Either an invalid parameter exists or the data expected is not present.
    401 Unauthorized. Check you're using the right api_key.
    403 Access denied. The API key provided does not have the required permissions.
    404 The list or results file isn't found. Verify you have the correct list_id and the list is in the right status.
    415 Invalid Content-Type submitted.
    422 Invalid file. Verify file has proper name and format.
    500 Internal server error. Please contact support.
    502 Bad gateway. The API is not available. Please try again later or contact support.

    DEVELOPER LIBRARIES

    Library Introduction

    The TowerData software library provides support and code examples for different programming languages. Each language helps you obtain data on email addresses, names and postal addresses using the TowerData API.

    If you have questions or care to make suggestions please send us an email to: developer @ towerdata dot com. We’re here to help so please don’t be shy about contacting us. If you send us code please keep in mind it will be distributed under the same TowerData API license. This code is licensed under the Apache License which follows:

    Copyright 2018 TowerData

    Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0.

    Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

    C#

    The C# SDK contains two solutions: example and personalization. The example solution provides several usage examples of the API. The personalization solution is used to compile a DLL containing the TowerData C# API. A pre-compiled DLL is provided that should work with most modern CPUs and Windows operating systems.

    Example

    For sample usage of direct and bulk APIs, see the example in our GitHub C# SDK. It uses the JavaScriptSerializer class which is available in .NET Frameworks 3.5 and higher in the system.web.extensions element.

    Example C# Code Path

    cd <path-to-SDK>\csharp\example\example\bin
    

    Usage Syntax

    example.exe <your API key> [sample email 1] [sample email 2] [sample email 3]
    

    Usage

    To run the sample solution open a command prompt and cd into the bin directory of the example. The only required parameter is a valid API key. Optional parameters allow up to three sample email addresses. When you Hit ENTER a series of queries run. See the example code path and usage syntax in the right column.

    The first query uses sample email 1 (or the default if not entered) and performs a query by email only. The second query is a bulk query containing an email and NAP. If entered, sample email 1 will be used in this query. The third queries by email iteratively using three different email addresses. Your sample email 1, 2 and 3 will be used for this query. After each query, the results are returned to the console. You'll be prompted to Hit ENTER to proceed to the next query.

    Recompiling

    A C# compiler is required if recompilation of either solution is necessary. The TowerData C# SDK was compiled with Microsoft Visual Studio Community 2013. Begin at the Windows Start menu and select:

    All Programs > Visual Studio 2013 > Visual Studio Tools

    The Visual Studio Common Tools folder will open in Windows Explorer. Double-click the shortcut:

    Developer Command Prompt for VS2013

    In the open command prompt cd to the directory containing the solution you want to recompile. See the example below:

    Example C# Clean & Rebuild Command

    msbuild /p:Configuration=Release /p:Platform="Any CPU" /target:Rebuild
    

    cd \csharp\personalization

    To clean and rebuild the solution use the command in the right column.

    Java

    The Java SDK has two API jar files located in the /java/build folder. The first is towerdata-api-complete.jar and bundles json.jar with the TowerData API. The second is towerdata-api.jar and isn’t bundled but it can be found in /java/lib.

    Example

    Example Java Compile Command

    javac -cp <path-to-towerdata-api-complete.jar> TowerDataExample.java
    

    This example class takes two arguments: an api-key and the email to query. After compiling the class you can run it from the command line using the command below:

    java -cp <path-to-towerdata-api-complete.jar> com.towerdata.api.personalization.TowerDataExample <api-key> <email>
    

    The TowerData API is queried by calling any of the query functions belonging to the towerdata-api.jar file. See the TowerDataApiExample.java personalization example in our GitHub Java SDK.

    The TowerDataApiExample.java example queries the TowerData API for an email address. From the command line you can compile this class by entering the command displayed in the right column.

    Query Options

    The Java SDK supports several ways to query TowerData's API: by email, hashed email (either MD5 or SHA1 hash), name and postal (NAP), or name and ZIP+4 (NAZ).

    The queryByEmail(String email, boolean hash_email) method queries TowerData's API with the specified email. If the second parameter is set to true, the email address will be hashed to an MD5 before querying TowerData's API; default = false.

    The queryByMd5(String md5Email) and queryBySha1(String sha1Email) methods query TowerData's API with the hashed emails using either the MD5 or SHA1 hash functions respectively.

    The queryByNap(String first, String last, String zip4, String email) method queries TowerData's API with a name and postal address: first name, last name, street, city and state acronym (e.g. 2-character state postal code). It also accepts an optional email address which increases the match rate.

    The queryByNaz(String first, String last, String zip4, String email) method queries TowerData's API with a name and ZIP+4 code. The ZIP+4 is a string with a 5-digit ZIP code and 4-digit extension separated by a dash. It also accepts an optional email address which increases the match rate.

    The bulkQuery(set) method queries the TowerData API with a HashMap of emails or names and postal addresses and returns a JSON array containing information on each input identifier.

    Perl

    Example Directory Path

    use lib '/path/to/directory/with/dot_pm_file';
    

    Example

    > use TowerDataAPI;
    > my $response = query_by_email('pete@rapleafdemo.com');
    > print "Gender is $response->{'gender'}\n";
    => Gender is Male
    
    > my $response = query_by_nap('Pete', 'Schlick', '112134 Leavenworth Rd.',
                                  'San Francisco', 'CA');
    > print "Age is $response->{'age'}\n";
    => Gender is 25-34
    

    The Perl SDK retrieves the contents of a list query.

    Installation

    The TowerDataAPI.pm package file should be in the same directory as your script. Or set your script to include the directory with the package file. See the examples in the right column. At the top of TowerDataAPI.pm update the $API_KEY variable with your API key.

    Query Options

    The Perl SDK supports several ways to query TowerData's API: email, hashed email (either MD5 or SHA1 hash), name and postal (NAP), or name and ZIP+4 (NAZ).

    The query_by_email($email, $options) method queries TowerData's API with the specified email. If $options is set to true the email address will be hashed to MD5 before querying TowerData's API.

    The query_by_md5($md5_email) and query_by_sha1($sha1_email) methods query TowerData's API with either the MD5 or the SHA1 of an email. The email address should be in lower case and you need to remove the whitespace prior to hashing.

    The query_by_nap($first, $last, $street, $city, $state, $optional_email) method queries TowerData's API with a name and postal address: first name, last name, street, city and state acronym (e.g. 2-character state postal code). It also accepts an optional email address which increases the match rate.

    The query_by_naz($first, $last, $zip4, $optional_email) method queries the API with a name and ZIP+4 code. The ZIP+4 is a string with a 5-digit ZIP code and 4-digit extension separated by a dash. It also accepts an optional email address which increases the match rate.

    PHP 4

    Example PHP 4 Script

    namespace TowerData;
    include "TowerDataApi.php";
    
    $person = $argv[1];
    $response = query_by_email($person, false);
    print_r($response);
    

    The PHP 4 SDK calls the query functions belonging to the TowerDataApi.php file. The example TowerDataExample.php script takes an email as a command line parameter and connects it to the TowerData service to return (and sends to stdout) a collection of associated key-value pairs. See the example in the right column.

    Remember to set your TowerData API key in TowerDataApi.php prior to using the PHP 4 SDK.

    Query Options

    There’s several ways to query TowerData's API: email, hashed email (either MD5 or SHA1 hash), name and postal (NAP), or name and ZIP+4 (NAZ).

    The query_by_email($email, $hash_email = false) method queries TowerData's API with the specified email. If the second parameter is set to true the email address will be hashed to an MD5 before querying the API with it; default = false.

    The query_by_md5($md5_email) and query_by_sha1($sha1_email) methods query TowerData's API with the hashed emails using either the MD5 or SHA1 hash functions respectively.

    The query_by_nap($first, $last, $street, $city, $state, $email = null) method queries TowerData's API with a name and postal address: first name, last name, street, city and state acronym (e.g. 2-character state postal code). It also accepts an optional email address which increases the match rate.

    The query_by_naz($first, $last, $zip4, $email = null) method queries TowerData's API with a name and ZIP+4 code. The ZIP+4 is a string with a 5-digit ZIP code and 4-digit extension separated by a dash. It also accepts an optional email address which increases the match rate.

    PHP 5

    Example PHP 5 Script

     namespace TowerData;
      include "TowerDataApi.php";
    
      $person = $argv[1];
      $api = new TowerDataApi('api_key');
      try {
          $response = $api -> query_by_email($person, $hash_email = true);
          foreach ($response as $key => $value) {
              echo $key . " = " . $value . "\n";
          }
      } catch (\Exception $e) {
          echo 'Caught exception: ' .  $e->getMessage() . "\n";
      }
    

    The PHP 5 SDK calls the query functions belonging to the TowerDataApi.php file. The example TowerDataExample.php script takes an email as a command line parameter and connects it to the TowerData service to return (and sends to stdout) a collection of associated key-value pairs. See the example in the right column.

    Remember to set your TowerData API key in TowerDataApi.php prior to using the PHP 5 SDK.

    Query Options

    There’s several ways to query TowerData's API: email, hashed email (either MD5 or SHA1 hash), name and postal (NAP), or name and ZIP+4 (NAZ).

    The query_by_email($email, $hash_email = false) method queries TowerData's API with the specified email. If the second parameter is set to true the email address will be hashed to an MD5 before querying the API with it; default = false.

    The query_by_md5($md5_email) and query_by_sha1($sha1_email) methods query TowerData's API with the hashed emails using either the MD5 or SHA1 hash functions respectively.

    The query_by_nap($first, $last, $street, $city, $state, $email = null) method queries TowerData's API with a name and postal address: first name, last name, street, city and state acronym (e.g. 2-character state postal code). It also accepts an optional email address which increases the match rate.

    The query_by_naz($first, $last, $zip4, $email = null) method queries TowerData's API with a name and ZIP+4 code. The ZIP+4 is a string with a 5-digit ZIP code and 4-digit extension separated by a dash. It also accepts an optional email address which increases the match rate.

    Python

    Example

    from towerDataApi import TowerDataApi
    api = TowerDataApi.TowerDataApi('API_KEY')
    api.query_by_email('test@example.com')
    {u'gender': u'Male', u'age': u'25-34'}
    

    Replace API_KEY with your API key.

    The Python SDK retrieves the contents of a list query. See the example Python use in the right column.

    Installation

    pip install towerDataApi

    Query Options

    The Python egg supports several ways to query TowerData's API: email, hashed email (either MD5 or SHA1 hash), name and postal (NAP), or name and ZIP+4 (NAZ).

    The query_by_email(self, email, hash_email = False) method queries TowerData's API with the specified email. If the hash_email option is set the email will be hashed before it's sent to TowerData.

    The query_by_md5(self, md5_email) and query_by_sha1(self, sha1_email) methods query TowerData's API with the hashed emails using either the MD5 or SHA1 hash functions respectively.

    The query_by_nap(self, first, last, street, city, state, email = None) method queries TowerData's API with a name and postal address: first name, last name, street, city and state acronym (e.g. 2-character state postal code). It also accepts an optional email address which increases the match rate.

    The query_by_naz(self, first, last, zip4, email = None) method queries TowerData's API with a name and ZIP+4 code. The ZIP+4 is a string with a 5-digit ZIP code and 4-digit extension separated by a dash. It also accepts an optional email address which increases the match rate.

    Dependencies

    urllib3

    pip install urllib3

    Visit https://github.com/shazow/urllib3/zipball/master to download the file. Once you've unzipped the file open a terminal window and navigate to the local folder. The subdirectory urllib3 contains a script called setup.py which you'll run via the command python setup.py install.

    Ruby

    Example Ruby

    require 'towerdata_api'
    api = TowerDataApi::Api.new('my secret API key')
    h = api.query_by_email('test@rapleaf.com')
    => {"gender"=>"Male", "age"=>"25-34"}
    

    Replace API_KEY with your API key.

    Example Using Global Configuration

    require 'towerdata_api'
    TowerDataApi::Configuration.begin do |config|
      config.api_key= 'my secret API key'
      config.timeout= 10
    end
    api = TowerDataApi::Api.new
    h = api.query_by_email('test@rapleaf.com')
    => {"gender"=>"Male", "age"=>"25-34"}
    

    The Ruby SDK retrieves the contents of a list query. See the example Ruby uses in the right column.

    Installation

    gem install towerdata_api

    This installation uses the JSON gem.

    Constructor Options

    You can pass an options hash to the API constructor like the example below:

    api = TowerData::Api.new('my secret API key', :timeout => 10)

    The possible options/keys accepted by the constructor are described in the table below.

    Options/Keys Description
    :timeout => The max amount of time to wait for a request to finish. Defaults to 2.
    :ca_file => Set this to your system-wide root CA cert path if you're having SSL verification issues. Defaults to nil.

    Query Options

    The gem supports several ways to query TowerData's API: email, hashed email (either MD5 or SHA1 hash), name and postal (NAP), or name and ZIP+4 (NAZ).

    The query_by_email(email, options) method queries our API with the specified email. The options hash accepts the following keys:

    The query_by_md5(md5_email, options) and query_by_sha1(sha1_email, options) methods query TowerData's API with the hashed emails using either the MD5 or SHA1 hash functions respectively.

    The query_by_nap(first, last, street, city, state, options) method queries TowerData's API with a name and postal address: first name, last name, street, city and state acronym (e.g. 2-character state postal code). It also accepts the following options hash:

    The query_by_naz(first, last, zip4, options) method queries TowerData's API with a name and ZIP+4 code. The ZIP+4 is a string with a 5-digit ZIP code and 4-digit extension separated by a dash. This method accepts the following option:

    The email_validation(email) method queries TowerData's API with email and returns the email_validation object. Raise error if email_validation is not enabled.

    The valid_email?(email) method queries TowerData's API with email and returns boolean or nil if response is timeout. Raise error if email_validation is not enabled.

    SUPPORT

    Contact TowerData

    If you have questions or care to make suggestions please send us an email to: developer @ towerdata dot com or fill or use the form or contact information here. We’re here to help so please don’t be shy about contacting us.

    Data Dictionary

    The TowerData dictionary contains all possible consumer data, fields, descriptions and possible values.

    Demographic data

    The following demographic data table contains fields, descriptions and possible values for API & Batch.

    Field Description & Possible Values
    Age Age range: 18-20, 21-24, 25-34, 35-44, 45-54, 55-64, 65+
    First Name First name of person.
    Gender male, female
    Last Name Last name of person.
    Postal Address Address where person lives or works: street, city, state, zip

    Device data

    The following device data table contains fields, descriptions and possible values for Batch.

    Value definitions:

    IDFA = Identifier for Advertising on iOS devices AAID = Google Advertising ID on Android devices

    Field Value Description
    Device ID IDFA Apple's Identifier for Advertising: the person's iOS smartphone advertising identifier for marketing activity tracking.
    Device ID AAID Google's Android Advertising ID: the person's Android smartphone advertising identifier for marketing activity tracking.

    Email activity metrics data

    The following Email Activity Metrics data table contains fields, descriptions and possible values for API & Batch.

    Field Value Description
    Date First Seen yyyy-mm-dd The date the email address first appeared in our records. The value now will be returned if the email address is new to the TowerData database.
    Longevity 0-3 A score when TowerData first encountered the email address.
    Month Last Open yyyy-mm The year and month TowerData last detected an open by the email address in a rolling 12 month period.
    Popularity 0-10 A score gauging the popularity of the email address over the last 12 months.
    Velocity 0-10 A score reflecting the activity of the email address over the last 3 months.

    Household data

    The following household data table contains fields, descriptions and possible values for API & Batch.

    Field Description & Possible Values
    Education Indicates the highest known level of education the person has completed: Completed High School, Attended College, Completed College, Completed Graduate School, Attended Vocational/Technical School
    Home Market Value Market value of person's home: 1-25k, 25-50k, 50-75k, 75-100k, 100-150k, 150-200k, 200-250k, 250k-300k, 300-350k, 350-500k, 500k-1mm, 1mm+
    Homeowner Status The person owns or rents their home: Own, Rent
    Household Income Income of household by range: 0-15k, 15-25k, 25-35k, 35-50k, 50-75k, 75k-100k, 100-125k, 125-150k, 150-175k, 175-200k, 200-250k, 250k+
    Length of Residence Number of years spent in the current residence: Less than 1 year, 1 Year, 2 Years, 3 Years, 4 Years, 5 Years, 6 Years, 7 Years, 8 Years, 9 Years, 10 Years, 11-15 years, 16-19 years, 20+ years
    Marital Status Single, Married
    Net Worth The approximate net worth of the household: 0-5k, 5-10k, 10-25k, 25-50k, 50-100k, 100-250k, 250-500k, 500-750k, 750k-1mm, 1mm+
    Occupation The occupation of the person: Blue Collar Worker, Business Owner, Civil Service, Technology, Executive/Upper Management,Health Services, Homemaker, Middle Management, Military Personnel, Nurse, Part Time, Professional, Retired, Secretary, Student, Teacher, White Collar Worker
    Presence of Children Indicates whether there's one or more children in the household: Yes, No

    Interest data

    The following interest data table contains fields, descriptions and possible values for API & Batch.

    Field Value Description
    Arts & Crafts true;(blank) Purchases of arts and crafts products.
    Automotive true;(blank) Purchases of automotive products.
    Books true;(blank) Purchases of books and interest in reading.
    Business true;(blank) Interest in business.
    Health & Wellness true;(blank) Purchases of healthy lifestyle products; interest in health and wellness.
    Movies true;(blank) Interest in movies.
    News & Current Events true;(blank) Purchases of subscriptions for news and current events.
    Music true;(blank) Interest in music.

    Life stage data

    The following life stage data table contains fields, descriptions and possible values for API & Batch.

    Value definitions:

    I = interested, B = bought, A = actively interested, M = in market

    Field Value Description
    Adrenaline A Adrenaline junkies are actively shopping for camping, hiking, biking, kayaking, skiing, snowboarding and other outdoor adventure sports gear.
    Beauty Style A Beauty mavens are defined by their consistent shopping behavior for beauty products such as cosmetics, hair care, skin care, perfume and beauty tools.
    Connected A Consumers actively shopping for connected home technology. These include lighting, security, thermostat and voice-controlled devices.
    Cord Cutter A Consumers who cut traditional media services like cable. They buy streaming media solutions and prefer mobile devices for their content consumption.
    Design A Consumers actively shopping for home décor products such as furniture, bedding sets, curtains, drapes, rugs and table linens.
    DIY Neighbors A Consumers actively shopping for do-it-yourself building supplies such as power tools, flooring supplies, plumbing supplies, hardware, electrical supplies and equipment.
    Early Tech Adopters A Consumers actively shopping for new technologies. These consumers are defined as early tech adopters based on their shopping habits of new products and brands, general demographic data and online shopping behavior.
    Engaged A Couples planning to marry. This field is defined by their shopping behavior for engagement rings, wedding bands, wedding dresses, wedding shoes, wedding invitations, wedding flowers and wedding décor.
    Expecting A Parents expecting a baby or likely to be expecting a baby based on their online shopping activity for maternity clothing and website visitation to pregnancy and parenting websites.
    Family CEO A Defined as being the decision-maker for purchases of products such as baby and kids items, kitchen, home and pets.
    Fashionista A Consumers actively shopping for handbags, shoes, dresses, jewelry and other fashion accessories.
    Fitness A Consumers actively shopping for fitness equipment, activewear, yoga and pilates gear, vitamins and nutritional supplements.
    Gamer A Male consumers ages 18 to 44 actively shopping for video games, video game consoles, computers and electronics.
    Gearhead A Consumers actively shopping for auto parts, auto accessories and tires.
    Home Buyers A Home buyers or likely to become home buyers. This field is defined by online shopping habits.
    Millennial A College millennials are defined by their age and active presence on university and college campuses.
    Mom A Moms are identified by a core set of declared data at the individual level.
    New Parent A New parents are defined by their demographics and shopping behavior for infant and baby clothing, baby feeding products, strollers, car seats, baby furniture, infant toys and other baby gear.
    Outdoors A Consumers actively shopping for hunting, fishing, boating, camping and hiking gear.
    Pet Lover A Consumers actively shopping for pet toys, food, health items and accessories for their dogs, cats and other pets.
    Team Player A Consumers actively shopping for baseball, softball, football, basketball, volleyball and hockey gear.
    Tech Fan A Consumers actively shopping for computers and electronics such as smartphones, tablets, TVs, speakers, headphones and digital cameras.

    Purchase data

    The following purchase data table contains fields, descriptions and possible values for API & Batch.

    Field Value Description
    Automotive true;(blank) Purchases of automotive goods.
    Charitable Donor true;(blank) Indicates likelihood of being a charitable donor.
    Cooking true;(blank) Purchases of cooking magazines.
    High End Brand Buyer true;(blank) Purchases of premium brands in the past 18 months.
    Magazine Buyer true;(blank) Purchases of magazine subscriptions.
    Travel true;(blank) Interest in travel.

    Purchase intent data

    The following purchase intent data table contains fields, descriptions and possible values for API & Batch.

    Value definitions:

    I = interested, B = bought, A = actively interested, M = in market

    Field Value Description
    Appliances IBAM Consumers actively shopping online for appliances.
    Auto Parts IBAM Consumers actively shopping online for automotive parts, tires and accessories.
    Baby Products IBAM Consumers actively shopping online for baby gear.
    Bathroom IBAM Consumers actively shopping online for bathroom accessories, hardware and towels.
    Beauty IBAM Consumers actively shopping online for health and beauty products.
    Cats IBAM Consumers actively shopping online for cat supplies.
    Childrens Clothing IBAM Consumers actively shopping online for baby and kids clothes and shoes.
    Computers IBAM Consumers actively shopping online for laptops, desktops and tablets.
    Computers and Software IBAM Consumers actively shopping online for computers and software.
    Cosmetics IBAM Consumers actively shopping online for cosmetics.
    Dogs IBAM Consumers actively shopping online for dog supplies.
    Electronics IBAM Consumers actively shopping online for electronics.
    Flowers IBAM Consumers actively shopping online for flowers.
    Food Gifts IBAM Consumers actively shopping online for food and snacks.
    Furniture IBAM Consumers actively shopping online for furniture.
    Garden and Patio IBAM Consumers actively shopping online for gardening, landscaping and outdoor cooking supplies.
    Garden Supplies IBAM Consumers actively shopping online for gardening supplies.
    Gift Buyer IBAM Consumers actively shopping online for gifts, flowers and food.
    Hair Care IBAM Consumers actively shopping online for hair care.
    Home and Garden IBAM Consumers actively shopping online for home and garden products.
    Home Décor IBAM Consumers actively shopping online for home décor.
    Home Improvement IBAM Consumers actively shopping online for home improvement products.
    Jewelry IBAM Consumers actively shopping online for jewelry and watches.
    Kids and Babies IBAM Consumers actively shopping online for baby and kids product.
    Kitchen and Dining IBAM Consumers shopping online for cooking supplies, tableware and glassware.
    Mobile Phones IBAM Consumers actively shopping online for cell phones and smartphones.
    Lamps and Lighting IBAM Consumers actively shopping online for home lighting.
    Linens and Bedding IBAM Consumers actively shopping online for bedding.
    Mens Accessories IBAM Consumers actively shopping online for mens accessories.
    Mens Clothing IBAM Consumers actively shopping online for mens clothing and accessories.
    Mens Shoes IBAM Consumers actively shopping online for mens shoes.
    Mobile Phone Accessories IBAM Consumers actively shopping online for accessories for cell phones and smartphones.
    Nutrition IBAM Consumers actively shopping online for vitamins and nutrition products.
    Perfume and Cologne IBAM Consumers actively shopping online for perfume and cologne.
    Pets and Supplies IBAM Consumers actively shopping online for pet supplies.
    Phone Products IBAM Consumers actively shopping online for cell phones, smartphones and accessories.
    Printing and Copying IBAM Consumers actively shopping online for printers and ink.
    Skin Care IBAM Consumers actively shopping online for skin care products.
    Sports and Outdoors IBAM Consumers actively shopping online for sports equipment and outdoor gear.
    Table and Glassware IBAM Consumers shopping online for tableware and glassware.
    Tools IBAM Consumers actively shopping online for tools.
    Toys IBAM Consumers actively shopping online for toys and games.
    Video Games IBAM Consumers actively shopping online for video games.
    Womens Accessories IBAM Consumers actively shopping online for womens accessories.
    Womens Clothing IBAM Consumers actively shopping online for womens clothing and accessories.
    Womens Shoes IBAM Consumers actively shopping online for womens shoe.

    Shopper type data

    The following shopper type data table contains fields, descriptions and possible values for API & Batch.

    Value definitions:

    I = interested, B = bought, A = actively interested, M = in market

    Field Value Description
    Big Spender IBAM Consumers making big purchases spending large sums of money.
    Deal Seeker IBAM Consumers actively shopping online using coupons and discount comparison sites.
    Holiday Shopper IBAM Consumers actively shopping online for holiday accessories.
    Luxury Shopper IBAM Consumers actively shopping for high-end fashion items and luxury brands.
    Online Buyer IBAM Verified online buyers across the retail vertical.