NAV Navbar
CURL RUBY PYTHON JAVA JAVASCRIPT C#
  • TOPICS
  • SafeToSend
  • EMAIL VALIDATION
  • IDENTITY MATCHING
  • EMAIL INTELLIGENCE
  • EMAIL ACTIVITY METRICS
  • BULK EMAIL INTELLIGENCE
  • LIST API
  • DEVELOPER LIBRARIES
  • SUPPORT
  • TOPICS

    Introduction

    AtData (formerly 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.

    AtData'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.atdata.com/v5/ev?email=johndoe@yahoo.com&api_key=1234567890feedfacecafe1234567890"
    
    require 'uri'
    require 'net/http'
    url = URI("https://api.atdata.com/v5/ev?timeout=5&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.atdata.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.atdata.com/v5/ev?timeout=5&email=johndoe%40yahoo.com&api_key=1234567890feedfacecafe1234567890")
    .asString();
    
    var settings = {
      "async": true,
      "crossDomain": true,
      "url": "https://api.atdata.com/v5/ev?timeout=5&email=johndoe%40yahoo.com&api_key=1234567890feedfacecafe1234567890",
      "method": "GET",
      "headers": {  }
    }
    $.ajax(settings).done(function (response) {
      console.log(response);
    });
    
    var client = new RestClient("https://api.atdata.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 an AtData 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.

    SafeToSend

    SafeToSend - Introduction

    AtData specializes in email address verification. We can help you filter out invalid and high risk email addresses which results in higher open rates, clicks and conversions.

    Our SafeToSend Email Verification & Hygiene 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, honeypots, and high risk emails..
    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.
    Engagement Score A simple 0 - 10 score representing the relative engagement behavior of a specific email address*

    SafeToSend API Endpoint

    SafeToSend Endpoint

    https://api.atdata.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

    SafeToSend Sample Query

    https://api.atdata.com/v5/ev?email=sales%40%40atdata.com&api_key=78ad9ddc21e3c220cc5da024b6dbe13c
    

    Replace 78ad9ddc21e3c220cc5da024b6dbe13c with your API key.

    A SafeToSend email verification example query is in the right column.

    Response Overview

    {
      "safe_to_send": {
        "status_code": 155,
        "address": "sales@@atdata.com",
        "role_account": true,
        "email_corrections": [
          "sales@atdata.com"
        ],
        "status": "invalid"
      }
    }
    

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

    The "safe_to_send" 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"].
    engagement_score Engagement Score -- which is free for SafeToSend subscription customers -- provides a simple 0-10 score representing the relative engagement behavior of a specific email address, helping marketers to better segment and qualify subscribers to improve deliverability, response, and core metrics. For more information on Engagement Score data and use cases, please review our Engagement Score documentation. The engagement score will only be returned for email addresses that have been labeled safetosend, valid or catchall. If an email is determined to be invalid, a spam trap or from any other risky category, then the engagement score data will not be returned.

    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.

    SafeToSend email

    SafeToSend Email Request

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

    Response

    {  
       "safe_to_send":{  
          "domain_type":"biz",
          "status_code":50,
          "address":"sales@atdata.com",
          "role_account": true,
          "status":"safetosend"
       }
    }
    

    An email address that is SafeToSend has accurate syntax, a working domain, can receive email and is not a known spam trap or honeypot. SafeToSend emails are backed by AtData's 100% deliverable guarantee. In the right column is the sample request and response.

    Valid email

    Valid Email Request

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

    Response

    {  
       "safe_to_send":{  
          "status":"valid",
          "status_code":20,
          "address":"valid@demo.atdata.com"
       }
    }
    

    Valid emails have passed the majority of our SafeToSend checks, but they cannot be 100% confirmed as deliverable and thus are not covered by our deliverability guarantee. Valid emails may still bounce and should be messaged cautiously. In the right column is the sample request and response.

    Invalid email address

    Invalid Email Request

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

    Response

    {  
       "safe_to_send":{  
          "status":"invalid",
          "status_code":400,
          "address":"accountnotfound@atdata.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.

    Email corrections

    Invalid Email Request with Correction

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

    Response

    {  
      "safe_to_send": {
        "status": "invalid",
        "status_code": 155,
        "address": "sales@@atdata,com",
        "role_account": true,
        "email_corrections": [
          "sales@atdata.com"
        ]
      }
    }
    

    AtData can fix many syntax and spelling errors in email addresses, including misspellings of common domain names. Any suggested fixes to an invalid email address will be in array called "email_corrections" in the response, as shown to the right. All corrections are fully validated.

    Catchall email

    Catchall Email Request

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

    Response

    {  
       "safe_to_send":{  
          "status":"catchall",
          "status_code":45,
          "address":"anyuser@google.com"
       }
    }
    

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

    Trap email

    TRAP Email Request

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

    Response

    {  
       "safe_to_send":{  
          "status_code":525,
          "address":"trap@demo.atdata.com",
          "status":"trap"
       }
    }
    

    Trap addresses are deliverable but are confirmed spamtraps, suspected spamtraps, disposable emails, or otherwise considered high risk. To avoid delivery issues, don’t send email to these addresses. In the right column is the sample request and response.

    Emails that are clearly dangerous, such as abuse@... or ...@spamcop.net, will be marked as invalid.

    Disposable email

    Disposable Email Request

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

    Response

    {  
      "safe_to_send":{  
          "domain_type":"disposable",
          "status_code":525,
          "address":"johndoe@mailinator.com",
          "status":"trap"
       }
    }
    

    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. We categorize these emails as traps, but you may have reason to allow them. In the right column is the sample request and response.

    Role account

    Role Account Request

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

    Response

    {  
       "safe_to_send":{  
          "domain_type":"biz",
          "status_code":50,
          "address":"sales@atdata.com",
          "role_account":true,
          "status":"safetosend"
       }
    }
    

    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.atdata.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. The message "Invalid API key." will be returned along with a HTTP 401 error status. 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
    safetosend The email address passed all checks of the SafeToSend process, is safe to mail, and is backed by our deliverability guarantee.
    valid The email address passed the majority of SafeToSend checks; however, the mailbox could not be confirmed as deliverable and may still bounce.
    invalid Do not mail. The email does not have proper syntax, the domain is dead or the mailbox doesn't exist.
    trap The email address is valid but it may cause delivery issues (e.g. spamtrap, honeypot, disposable, or complainer). We recommend that you don't email trap addresses.
    catchall The domain doesn't support a mailbox level check. Also known as an "accept all" domain. Expect some bounces from these addresses should you choose to mail them. Note that currently, the List API is returning "unverifiable" instead of "catchall". On April 29, 2024, we will be making an update so that both the List API and the single-call API will return "valid" for domains of this type.
    unknown We were not able to complate any checks on the address. Messages to these addresses may see bounces. Repeating the query later may provide a valid/invalid status.
    corrected This status is only returned in files submitted via InstantData or the List API. The email address is invalid because it had a syntax or spelling error, and we fixed it. The corrected form of the address is in the Valid Email column of your results file.

    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. Note that AtData may add additional codes in the future.

    Status Code Description
    unknown 5 Timeout. Did not get a response in time.
    valid 10 Syntax OK.
    valid 20 Syntax OK and the domain is valid.
    catchall 45 Domain is a catch all and does not support validation.
    safetosend 50 Valid and guaranteed SafeToSend email address.
    valid 55 Address is allowed by client-configured exception.
    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 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 210 Address contains an extra space or character.
    invalid 215 Unquoted spaces not allowed in email addresses.
    invalid 255 Address is not allowed by client-configured suppression.
    invalid 310 Domain doesn’t exist.
    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).
    trap 525 Address is a spamtrap or is suppressed.
    trap 530 Address has opted out from commercial email.
    trap 535 Address is on ANA's "Do Not Email List"
    trap 540* Address is a known or frequent complainer
    unknown 999 System error.

    *currently, code 540 needs to be enabled to be returned via SafetoSend. Please work with your client services representative to enable this setting.

    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.
    parked The domain does not have an active website.
    privacy The domain is used to protect the privacy of the user.
    wireless Wireless domain. Do not send unsolicited emails.

    EMAIL VALIDATION

    Email Validation - Introduction

    This is the documentation for the TowerData email address validation API. For advanced spam trap detection, industry-leading B2B email validation, and guaranteed results, check out the SafeToSend API.

    Validation API Endpoint

    Email Validation Endpoint

    https://api.atdata.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.atdata.com/v5/ev?email=sales%40%40atdata.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_code": 155,
        "address": "sales@@atdata.com",
        "email_corrections": [
          "sales@atdata.com"
        ],
        "status": "invalid"
      }
    }
    

    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.atdata.com/v5/ev?email=sales@atdata.com&api_key={API-Key}
    

    Response

    {  
       "email_validation":{
          "domain_type":"biz",
          "status_code":50,
          "address":"sales@atdata.com",
          "role_account": true,
          "status":"valid"
       }
    }
    

    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

    Invalid Email Request

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

    Response

    {  
       "email_validation":{  
          "domain_type": "biz",
          "status_code":400,
          "address":"accountnotfound@atdata.com",
          "status":"invalid"
       }
    }
    

    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.

    Email corrections

    Invalid Email Request with Correction

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

    Response

    {  
      "email_validation": {
        "status": "invalid",
        "status_code": 155,
        "address": "sales@@atdata,com",
        "role_account": true,
        "email_corrections": [
          "sales@atdata.com"
        ]
      }
    }
    

    AtData can fix many syntax and spelling errors in email addresses, including misspellings of common domain names. Any suggested fixes to an invalid email address will be in array called "email_corrections" in the response, as shown to the right. All corrections are fully validated.

    Unverifiable email

    Unverifiable Email Request

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

    Response

    {  
       "email_validation":{  
          "domain_type": "biz",
          "status":"unverifiable",
          "status_code":45,
          "address":"anyuser@google.com"
       }
    }
    

    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.atdata.com/v5/ev?email=timeout@demo.atdata.com&api_key={API-Key}
    

    Response

    {  
       "email_validation":{  
          "status":"unknown",
          "status_code":20,
          "address":"timeout@demo.atdata.com"
       }
    }
    

    AtData 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.atdata.com/v5/ev?email=trap@demo.atdata.com&api_key={API-Key}
    

    Response

    {  
       "email_validation":{  
          "status_code":525,
          "address":"trap@demo.atdata.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.

    Emails that are clearly dangerous, such as abuse@... or ...@spamcop.net, will be marked as invalid.

    Disposable email

    Disposable Email Request

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

    Response

    {  
      "email_validation":{
        "domain_type":"disposable",
          "status":"invalid",
          "status_code":505,
          "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.atdata.com/v5/ev?email=sales@atdata.com&api_key={API-Key}
    

    Response

    {  
       "email_validation":{  
          "domain_type":"biz",
          "status":"valid",
          "status_code":50,
          "address":"sales@atdata.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.atdata.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.
    corrected This status is only returned in files submitted via InstantData or the List API. The email address is invalid because it had a syntax or spelling error, and we fixed it. The corrected form of the address is in the Valid Email column of your results file.

    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 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 210 Address contains an extra space or character.
    invalid 215 Unquoted spaces not allowed in email addresses.
    invalid 310 Domain doesn’t exist.
    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.
    parked The domain does not have an active website.
    privacy The domain is used to protect the privacy of the user.
    wireless Wireless domain. Do not send unsolicited emails.

    IDENTITY MATCHING

    Identity Matching - Introduction

    AtData's identity graph connects multiple points of contact or forms of identity together. Use our Identity Matching API to link one form of identity with another.

    With Identity Matching, you can

    Contact us for a free trial of this API.

    Identity Matching Endpoints

    Identity Matching Single Request Endpoint

    https://api.atdata.com/v5/eppend
    

    Identity Matching Bulk Request Endpoint

    https://api.atdata.com/v5/eppend/bulk
    

    See the endpoints to append single or multiple contacts to the right.

    The Identity Matching bulk endpoint can be used to query up to 1,250 records at a time, and it uses the same request/response format as the Bulk API.

    Query Parameters

    For Email Append, matching an email address to a postal address, the Name Parameters and Postal Parameters must be used.

    For Postal Append, matching a postal address to an email address, use the Email Parameters.

    All calls must be authenticated with your API key.

    Alternate Email

    AtData's "Alternate Email" service allows access via API for multiple email addresses to be returned from a single email address input.

    If you have a large database of customer email addresses, either as a single database or disparately kept, the Alternate Email API allows you to create linkages between identities for improved accuracy and reach of your Identity Graph and attribution challenges. It's also handy for real-time use cases during new account origination.

    AtData's U.S.-patented Alternate Email technology has been the authority of email address associations for over two decades, evolving from a simple "change of email address" solution to now acting as a core component for building an accurate and deep identity graph.

    Example

    Example Query

    https://api.atdata.com/ae?email=sample@atdata.com&api_key=78ad9ddc21e3c220cc5da024b6dbe13c
    

    Replace 78ad9ddc21e3c220cc5da024b6dbe13c with your API key.

    Example Alternate Email Response

    { 
      "alternate_email": [ 
        { 
          "email": "cplackard@domain.com",
          "email_match_type": "Individual" 
    
        }, 
        {
          "email": "chris.plackard@domain2.com",
          "email_match_type": "Individual"
        } 
      ] 
    } 
    

    See an example of Alternate Email query and response to the right.

    Response Fields

    If your API key is configured for Alternate Email and an email is found for your input parameters, the API response will contain an "alternate_email" section in JSON format as shown in the example above.

    The "alternate_email" section will contain the following information:

    Field Description
    email The alternate email address that matched to the original email address.
    email_match_type Indicates at what level the email matched to the email input, with options of "Individual" or "Household."

    Please note that the array of alternate emails will contain more than one alternate if it is available in our database. The priority order of what is returned will be any "Individual" matches first, followed by any "Household" matches.

    The default number of alternate email matches is 1. However, you can work with your sales or customer support representative to increase the "max matches" to up to 5 alternate email addresses.

    Note that un-matched request will still return an empty JSON hash {}. If there is an error related to the request data, we return {"error_code":XXX, "error_msg":"The error message"} in the JSON response, where XXX is based on our list of HTTP status code.

    Email Append

    AtData Email Append can match an email address to 20% - 35% of U.S. postal addresses. Use it to reach your postal customers via email or a Facebook custom audience.

    Example

    Example Query

    https://api.atdata.com/v5/eppend?first=caitlin&last=plackard&street=789%20CHESTNUT%20ST&city=SAN%20FRANCISCO&state=CA&zip=94133&api_key=78ad9ddc21e3c220cc5da024b6dbe13c
    

    Replace 78ad9ddc21e3c220cc5da024b6dbe13c with your API key.

    Example Email Append Response

    {
      "email_append": [
        {
          "email_match_type": "Individual",
          "email": "sample@atdata.com"
        }
      ]
    }
    

    See an example Email Append query and response to the right.

    Response Fields

    If your API key is configured for Email Append and an email is found for your input parameters, the API response will contain an "email_append" section in JSON format as shown in the example above.

    The "email_append" section will contain the following information:

    Field Description
    email The email address that matched to the name and postal address.
    email_match_type Indicates at what level the email matched to the input individual. "Individual" means the email matched the full name and postal address. "Household" means the email matched postal address and the last name.

    Note that un-matched request will still return an empty JSON hash {}. If there is an error related to the request data, we return {"error_code":XXX, "error_msg":"The error message"} in the JSON response, where XXX is based on our list of HTTP status code. For example, if the postal address is correctly formatted but is not a real physical address, we may return {"error_code":400, "error_msg":”Invalid United States postal address.”}.

    Postal Append

    AtData Postal Append, also known as Reverse Email Append, can match name and postal address to 35% - 50% 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.

    Example

    Example Postal Append Query

    https://api.atdata.com/v5/eppend?email=sample@atdata.com&api_key=78ad9ddc21e3c220cc5da024b6dbe13c
    

    Replace 78ad9ddc21e3c220cc5da024b6dbe13c with your API key.

    Example Postal Append Response

    {
      "postal_address": {
        "first_name": "CAITLIN",
        "last_name": "PLACKARD",
        "address": "789 CHESTNUT ST",
        "city": "SAN FRANCISCO",
        "state": "CA",
        "zip": "94133-1234"
      }
    }
    

    See an example Postal Append query and response to the right.

    Do your testing needs require additional examples? The list of sample emails below will return different postal addresses for each example:

    postal_sample1@atdata.com postal_sample2@atdata.com postal_sample3@atdata.com postal_sample4@atdata.com postal_sample5@atdata.com postal_sample6@atdata.com postal_sample7@atdata.com postal_sample8@atdata.com postal_sample9@atdata.com postal_sample10@atdata.com

    Response Fields

    If your API key is configured for Postal Append and a postal address is found for the email you queried with, the API response will contain an "postal_address" section in JSON format as shown in the example above.

    The "postal_address" section will contain the following information:

    Field Description
    first_name The first name of the individual with that email address.
    last_name The last name of the individual with that email address.
    address The street address of the individual.
    city The city.
    state The state.
    zip The 9 digit zip code for the address.

    EMAIL INTELLIGENCE

    Email Intelligence - Introduction

    AtData’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.atdata.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

    demo+email@atdata.com outputs to: demo%2Bemail%40atdata.com
    

    sha1_email Example

    demo@atdata.com outputs to: 1d604932232d089ab1a1cad148f20d942db666a7
    

    md5_email Example

    demo@atdata.com outputs to: 3cf1e81405a4bdf4f7e3a2453cd441c3
    

    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.atdata.com/v5/td?api_key=78ad9ddc21e3c220cc5da024b6dbe13c&email=demo@atdata.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.

    Example

    Sample Query by Email Address

    https://api.atdata.com/v5/td?email=sample@atdata.com&first=caitlin&last=plackard&api_key=78ad9ddc21e3c220cc5da024b6dbe13c
    

    Replace 78ad9ddc21e3c220cc5da024b6dbe13c with your API key.

    Sample Query by Name and Postal Address

    https://api.atdata.com/v5/td?first=caitlin&last=plackard&street=789%20CHESTNUT%20ST&city=SAN%20FRANCISCO&state=CA&zip=94133&api_key=78ad9ddc21e3c220cc5da024b6dbe13c
    

    Replace 78ad9ddc21e3c220cc5da024b6dbe13c with your API key.

    Example Email Intelligence queries are in the right column.

    In the table below are email and postal addresses you can use to test the responses of the AtData API:

    Email Address Name Address
    demo@atdata.com Tower Data 33 Irving Pl Ste 4048, New York, NY 10003
    sample@atdata.com Caitlin Plackard 789 Chestnut St., San Francisco, CA 94123

    Response Overview

    {
      "age":"25-34",
      "gender":"Female",
      "interests":{
        "automotive":true,
        "books":true,
      },
      "eam":{
        "date_first_seen":"2017-11-16",
        "month_last_open":"2017-12",
        "velocity":0,
        "popularity":3,
        "longevity":2
      },
      "education":"Completed Graduate School",
      "occupation":"White Collar Worker",
      "household_income":"25k-35k",
      "marital_status":"Single",
      "presence_of_children":"No",
      "home_owner_status":"Rent",
      "life_stage_segment": "Career Building",
      "life_stage_group": "Taking Hold",
      "financial_segement": "Spontaneious Spenders",
      "financial_group": "City Spotlight",
    }
    

    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",
      "life_stage_segment": "City Life",
      "life_stage_group": "Working & Studying",
      "financial_segement": "Traditional Moderation",
      "financial_group": "Specific Savers",
      "rfm_offline_avg_days": 162,
      "rfm_online_avg_days": 81,
      "rfm_avg_dollars": 48,
      "rfm_last_order": "2021-11-27"
    }
    

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

    Field Values
    household_income Income of head of household by range: 0-15k, 15k-25k, 25k-35k, 35k-50k, 50k-75k, 75k-100k, 100k-150k, 150k-175k, 175k-200k, 200k-250k, 250k+
    net_worth The approximate net worth of the household: 0-5k, 5k-10k, 10k-25k, 25k-50k, 50k-100k, 100k-250k, 250k-500k, 500k-1mm, 1mm+
    home_market_value Market value of household's home: 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 The household owns or rents their home: Own, Rent
    length_of_residence Number of years household has 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 The marital status of the primary occupants of the household: Single, Married
    presence_of_children Indicates whether there's one or more children in the household: Yes, No
    education Indicates the highest known level of education completed in the household: Completed High School, Attended College, Completed College, Completed Graduate School, Attended Vocational/Technical School
    occupation The occupation of the primary person in the household: 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,
    rfm_offline_avg_days Recency, Frequency & Monetary Value - The average number of days between offline purchases for this household as an integer value.
    rfm_online_avg_days Recency, Frequency & Monetary Value - The average number of days between online purchases for this household as an integer value.
    rfm_avg_dollars Recency, Frequency & Monetary Value - The average dollar amount the household spends per order as an integer value.
    rfm_last_order Recency, Frequency & Monetary Value - The date of the last order made by the household in YYYY-MM-DD format.
    life_stage_segment 70 life-stage based household-level consumer segments based on demographic and consumer behavioral data: Summit Estates, Established Elite, Corporate Connected, Top Professionals, Active & Involved, Casual Comfort, Active Lifestyles, Solid Surroundings, Busy Schedules, Careers & Travel, Schools & Shopping, On the Go, Work & Play, Career Centered, Country Ways, Country Enthusiasts, Firmly Established, Climbing the Ladder, Country Comfort, Carving Out Time, Children First, Comfortable Cornerstones, Good Neighbors, Career Building, Clubs & Causes, Getting Established, Tenured Proprietors, Community Pillars, City Mixers, Out & About, Mid-Americana, Metro Mix, Urban Diversity, Outward Bound, Working & Active, Persistent & Productive, Firm Foundations, Occupational Mix, Setting Goals, Great Outdoors, Rural Adventure, Creative Variety, Work & Causes, Open Houses, Offices & Entertainment, Rural & Active, Rural Parents, Farm & Home, Home & Garden, Rural Community, Role Models, Stylish & Striving, Metro Strivers, Work & Outdoors, Community Life, Metro Active, Collegiate Crowd, Outdoor Fervor, Mobile Mixers, Rural & Mobile, City Life, Movies & Sports, Staying Home, Practical & Careful, Hobbies & Shopping, Helping Hands, First Steps, Staying Healthy, Productive Havens, Favorably Frugal
    life_stage_group 21 higher level aggregate life-stage groups that roll up life stage segments with similar characteristics: Starting Out, Taking Hold, Settling Down, Social Connectors, Busy Households, Working & Studying, Career Oriented, Large Households, Comfortable Independence, Rural-Metro Mix, Affluent Households, Comfortable Households, Working Households, Diverging Paths, Top Wealth, Living Well, Bargain Hunters, Thrifty and Active, Solid Prestige, Community Minded, Leisure Seekers
    financial_segment 54 segments based on consumers' financial propensities, grouping households by similar likelihood for financial behaviors, regardless of demographic characteristics: Involved Investors, Active Savers, Traditional Savers, Informed Control, Solid Investments, Hearth and Home, Online Financiers, Investing in Collections, Adventurous Investors, Comfortable Borrowers, Personal Service, Branded Influence, Asking Advice, Value Shoppers, Brand Variety, Online Automation, Online Learners, Trust Triumphs, Limited Risk Traditionalists, Thrill of the Ride, Learn and Prepare, Naturally Organized, Eye on the Economy, Daily Demands, Balance Vigilant, Comfort Zone, Online Managers, Quality Conscious, Traction for Today, In the Moment, Collectors Clubs, Quality over Price, Studied Purchasers, Deal Seekers, Worth the Risk, Online Influencers, Sophisticated Environmentalists, Budget Optimists, Spontaneous Spenders, Coupon Cutters, Fluent Advisors, Financial Freewheelers, Real Life Recommendations, Civic Centered, Prestige Seekers, Informed Shoppers, Technology Trenders, Future Fundamentals, Online Leaders, Online Connectors, Traditional Moderation, Work and Save, Temperate Technology, Independent Investors
    financial_group 13 higher level aggregate financial groups that roll up financial segments with similar characteristics: Market Watchers, Conservative Wealth, Specific Savers, Tried and True, Trendy Inclinations, Current Consumers, Rural Trust, City Spotlight, Career Conscious, Digital Financiers, Financial Futures, Stable Influentials, Conservatively Rural

    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

    Email Activity Metrics

    Example EAM Response

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

    provide information about the age and activity of an email address based on over a billion activity events AtData observes each month across its publisher network and client base. This data can be used to evaluate the legitimacy of an email address or compare its activity relative to other emails. To best confirm whether an email is active, take advantage of our Email Open data, which can tell you the last time we saw an email address open a commercial email message. 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 AtData's records. The value now will be returned if the email address is new to the AtData database.
    longevity 0-3 A score describing when AtData 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 6 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 AtData has received the address, from 0 (no sources in 12 months) to 10 (most sources).
    month_last_open YYYY-MM The year and month AtData 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 AtData has not encountered this email address before.
    1 AtData first encountered this email within the last month.
    2 AtData first encountered this email within the last year.
    3 AtData 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"
      }
    }
    

    AtData 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 Access denied. 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.

    EMAIL ACTIVITY METRICS

    Email Activity Metrics - Introduction

    AtData’s Email Activity Metrics (EAM) provide information about the age and activity of an email address based on over a billion activity events AtData observes each month across its publisher network and client base. This data can be used to evaluate the legitimacy of an email address or compare its activity relative to other emails. To best confirm whether an email is active, take advantage of our Email Open data, which can tell you the last time we saw an email address open a commercial email message.

    Try it for free.

    EAM API Endpoint

    Email Activity Metrics Endpoint

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

    The endpoint to obtain data on a single email is in the right column. It is the same endpoint as is used for Email Intelligence.

    Query Parameters

    The Email Activity Metrics API may be queried by plain or hashed email address.

    All calls must be authenticated with your API key.

    Email parameters

    email Example

    demo+email@atdata.com encodes to: demo%2Bemail%40atdata.com
    

    md5_email Example

    demo@atdata.com hashes to: 3cf1e81405a4bdf4f7e3a2453cd441c3
    

    sha1_email Example

    demo@atdata.com hashes to: 1d604932232d089ab1a1cad148f20d942db666a7
    

    The Email Activity Metrics 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.
    md5_email MD5 hashed email. The email must be lower case and stripped of white spaces before being hashed.
    sha1_email SHA-1 hashed email. The email must be lower case and stripped of white spaces before being hashed.

    Example

    Sample Query by Email Address

    https://api.atdata.com/v5/td?email=demo@atdata.com&api_key=78ad9ddc21e3c220cc5da024b6dbe13c
    

    Replace 78ad9ddc21e3c220cc5da024b6dbe13c with your API key.

    An example EAM query is in the right column.

    EAM Response Overview

    Response for known email

    {
      "eam":{
        "date_first_seen":"2012-02-24",
        "month_last_open":"2018-12",
        "velocity":0,
        "popularity":3,
        "longevity":3
      }
    }
    

    Response for unknown email

    {
      "eam":{
        "date_first_seen":"now",
        "velocity":0,
        "popularity":0,
        "longevity":0
      }
    }
    

    If your API key is configured with Email Activity Metrics, the API response will always contain an "eam" object in the response that looks like the example in the right column. The month_last_open field will only be present if we have seen that email open a message in the last 12 months and if your API key is configured for that field.

    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 AtData's records. The value now will be returned if the email address is new to the AtData database.
    longevity 0-3 A score describing when AtData 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 6 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 AtData has received the address, from 0 (no sources in 12 months) to 10 (most sources).
    month_last_open YYYY-MM The year and month AtData 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 AtData has not encountered this email address before.
    1 AtData first encountered this email within the last month.
    2 AtData first encountered this email within the last year.
    3 AtData first encountered this email over a year ago.

    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 Access denied. 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

    Bulk Email Intelligence - Introduction

    AtData’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 AtData API Key and give it a try.

    Bulk Intelligence Endpoint

    Bulk Email Intelligence Endpoint

    https://api.atdata.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.atdata.com/v5/ei/bulk?api_key=78ad9ddc21e3c220cc5da024b6dbe13c
    

    Replace 78ad9ddc21e3c220cc5da024b6dbe13c with your API key.

    Post Body

    [
      {"email":"sample@atdata.com","first":"Caitlin","last":"Plackard"},
      {"email":"unknown_email@domain.com"},
      {"email":"demo@atdata.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":"Female"},
      {},
      {"age":"65+","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"} in the JSON response, where XXX is based on our list of 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":"sample@atdata.com", "first":"Caitlin", "last":"Plackard"}, {"email":"unknown_email@domain.com"}]' https://api.atdata.com/v5/ei/bulk?api_key=78ad9ddc21e3c220cc5da024b6dbe13c
    

    Replace 78ad9ddc21e3c220cc5da024b6dbe13c with your API key.

    Curl Response

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

    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 5000 (e.g. 5001).

    LIST API

    List API - Introduction

    The AtData List API can be used to process up to 1,000,000 customer records for Email Validation, Email Intelligence or Identity Matching 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.atdata.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.atdata.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.atdata.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 If email address is in the file, the index of the column containing it, starting at 1.
    header header=true Used to indicate the presense of a header line with a value of true or false; default=false. Must be used for non-email fields.
    delimiter delimiter="," The character used to separate multiple columns within the file; default variable is tab (\t).
    report report=true For all services except validation, only produce a match report and do not purchase data.
    name name="abc.txt" File name, which must use one of these file extensions: .txt, .csv or .zip; default=myfile.csv.
    fields fields=age,gender A comma-separated list of the data fields you want returned. By default, all available fields are returned.
    callback_url callback_url=https://example.com/callback_url a valid webhook/callback url with a max length of 512 characters, that can accept POST requests with a JSON payload and uses https or http (https is strongly encouraged)

    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. You may also compress the file using zip to speed up the transfer of large files. If you submit a .zip file, it should only contain a single input file.

    If your file includes fields other than email address, use a header line in your first row to denote field data. See example CSV file format in the right column.

    Recognized header values are:

    Response

    Example Location Header

    Location: https://api.atdata.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.atdata.com/v5/list/4321
    

    Example Check List Request Using Curl

    $ curl -H 'api_key: 78ad9ddc21e3c220cc5da024b6dbe133' 'https://api.atdata.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.atdata.com/v5/list/{list_id} until your results are returned. Please wait 5 seconds between requests.

    See the example to the right.

    Setting a callback URL

    If you would like to automatically/programmatically be alerted when a list process is complete or in the case of a List API error, you can post a webhook/callback url to accept and receive a List API callback.

    The callback_url parameter requires a valid url with a max length of 512 characters, that can accept POST requests with a JSON payload and uses https or http (though https is highly recommended). The callback_url will be called once your file processing is complete or in the case of an error.

    Example Post Callback url Using Curl

    curl -X POST -H "api_key: 78ad9ddc21e3c220cc5da024b6dbe13c" -H "Content-Type:multipart/form-data" -F "file=@valid.csv" "https://api.atdata.com/v5/list?email_column=1&header=true&callback_url=<callback_url>”
    

    JSON payload example

    The JSON payload for the callback is in the same format as the check list status.

    See the example to the right.

    {
      "list_id": 11754,
      "name": "lista.csv",
      "status": "Results",
      "records": 145,
      "size_bytes": 3271,
      "created_at": "2023-08-16T10:39:40Z",
      "services": {
        "email_validation": {
          "input_count": 145,
          "completed_count": 145,
          "reporting": {
            "statuses": {
              "Valid": 0,
              "Invalid": 0,
              "Risky": 0,
              "Unknown": 145,
              "Unverifiable": 0,
              "Corrected": 0
            },
            "invalid_categories": {
              "Syntax Errors": 0,
              "Domain Errors": 0,
              "Mailbox Errors": 0,
              "Suppressions": 0
            },
            "domain_type": {
              "Disposable": 0,
              "Free ISP": 0,
              "Paid ISP": 0,
              "Wireless": 0,
              "Education": 0,
              "Government": 0,
              "Business": 0,
              "Non-profit": 0,
              "Parked": 0,
              "Privacy": 0
            },
            "role_accounts": 0,
            "status_codes": {
              "10": 0,
              "20": 0,
              "45": 0,
              "50": 0,
              "100": 0,
              "110": 0,
              "115": 0,
              "120": 0,
              "125": 0,
              "130": 0,
              "140": 0,
              "145": 0,
              "150": 0,
              "155": 0,
              "200": 0,
              "210": 0,
              "215": 0,
              "310": 0,
              "325": 0,
              "400": 0,
              "410": 0,
              "420": 0,
              "500": 0,
              "505": 0,
              "510": 0,
              "520": 0,
              "525": 0,
              "530": 0,
              "5": 145,
              "999": 0
            },
            "trap_hits": {
              "Trap Hits": 0
            }
          },
          "status": "Completed"
        }
      }
    }
    

    Responses

    Response - Processing

    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_intelligence": {
          "input_count": 1002,
          "completed_count": 700,
          "status": "Processing"
        }
      }
    }
    
    

    AtData 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 AtData numeric identifier for the list.
    name The name of the list.
    status The status of the list. See the table below for possible values.
    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.

    The table below shows the status values and meanings for the list overall.

    Attribute Description
    Pending The requested services have not started or are in progress.
    Processed At least one service has finished.
    Processing The results are being prepared.
    Results All services are complete and results can be retrieved.
    Cancelled The list was cancelled.
    Invalid The file did not have the proper format or header.
    Error A processing error has occurred.

    Individual services will use the following status values.

    Attribute Description
    Pending The service has not started.
    Processing The service is currently running.
    Completed The service has successfully completed.
    Cancelled The service was cancelled.
    Error The service failed and must be investigated or restarted.

    Reporting - Email Validation

    An example of reporting for "email_validation" in the List API.

    {
      "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,
        }
      }
    }
    

    Once a service has successfully completed, a "reporting" object for that service will be in the JSON response. See an example for Email Validation to the right.

    The reporting attributes and descriptions for Email Validation 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.

    Reporting - Alternate Email

    An example of reporting for "alternate_email" in the List API.

    { 
        "list_id": 14475, 
        "name": "myfile.txt", 
        "status": "Results", 
        "records": 800, 
        "size_bytes": 19168, 
        "created_at": "2024-01-30T19:22:37Z", 
        "services": { 
            "alternate_email_append": { 
                "input_count": 800, 
                "completed_count": 800, 
                "reporting": { 
                    "alternate_match_type": { 
                        "Individual match": 64, 
                        "Household match": 25, 
                        "2nd Individual match": 0, 
                        "2nd Household match": 0, 
                        "3rd Individual match": 0, 
                        "3rd Household match": 0, 
                        "4th Individual match": 0, 
                        "4th Household match": 0, 
                        "5th Individual match": 0, 
                        "5th Household match": 0 
                    } 
                }, 
                "status": "Completed" 
            } 
        } 
    } 
    

    For Alternate Email, the reporting section will show the number of emails matched based on match type.

    See the example to the right.

    Reporting - Email Append

    An example of reporting for "email_append" in the List API.

    {
      "list_id": 4321,
      "name": "customer_addresses.csv",
      "created_at": "2017-10-19T20:46:58Z",
      "status": "Results",
      "records": 1002,
      "size_bytes": 22709,
      "services": {
        "email_append": {
          "status": "Completed",
          "input_count": 1002,
          "completed_count": 1002,
          "reporting": {
            "email_match_type": {
              "Individual match": 200,
              "Household match": 50
            }
          }
        }
      }
    }
    

    For Email Append, the reporting section will show the number of emails matched based on match type.

    See the example to the right.

    Reporting - Email Intelligence

    An example of reporting for "email_intelligence" in the List API.

    {
       "list_id" : 4465,
       "name" : "emails.txt",
       "records" : 130,
       "status" : "Processed",
       "size_bytes" : 2786,
       "created_at" : "2019-07-24T20:47:25Z",
       "services" : {
          "email_intelligence" : {
             "status" : "Completed",
             "input_count" : 130,
             "completed_count" : 130,
             "reporting" : {
                "age" : {
                   "Total Count" : 26
                },
                "marital_status" : {
                   "Total Count" : 19
                },
                "household_income" : {
                   "Total Count" : 19
                },
                "home_owner_status" : {
                   "Total Count" : 19
                },
                "home_market_value" : {
                   "Total Count" : 19
                }
             }
          }
       }
    }
    

    For Email Intelligence, the reporting section will contain each field that was matched and the number of input records that matched to that field.

    See the example to the right.

    Purchase List Results

    Purchase POST URL

    https://api.atdata.com/v5/list/{list_id}/purchase
    

    Optional POST body specifying fields to purchase

    {
     "fields": ["gender",
                "postal_address"]
    }
    

    Optional POST body to purchase Individual email append matches

    {
       "options":{
          "email_append":{
             "match_type": "I"
          }
       }
    }
    

    Example curl call to purchase Individual and Household email matches

    curl -X POST -H "api_key: 78ad9ddc21e3c220cc5da024b6dbe133" -H "Content-Type: application/json" -d '{"options":{"email_append":{"match_type":"H"}}}' "https://api.atdata.com/v5/list/4321/purchase"
    

    By default, when using the List API, the service that your API key is configured for is automatically run to completion, and you will receive and be billed for the results. You can use the optional action=report parameter when submitting your list to only get a match report, without receiving data. This works for all of AtData's services except for Email Validation.

    If you want to purchase the results of a service after reviewing the match report, submit a HTTP POST request to the URL shown to the right.

    If you want to specify which of the match fields you wish to receive results on, you can list the fields you want to purchase in the body of the POST using the JSON format to the right. If you don't specify fields, all the fields that were matched will be purchased.

    For Email Append, you can also specify the type of match you wish to receive using the format on the right.

    Retrieve List Results

    GET URL

    https://api.atdata.com/v5/list/{list_id}/results
    

    Once a list status returns "Results", you can retrieve a 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 Results File

    $ curl -H "api_key: 78ad9ddc21e3c220cc5da024b6dbe133" -o my_file_4321.csv 'https://api.atdata.com/v5/list/4321/results'
    

    For example, to download the results and specify the file name using curl, add the -o flag followed by the desired filename. See the example in the right column.

    Curl Example Saving Results File with Default Name

    $ curl -H "api_key: 78ad9ddc21e3c220cc5da024b6dbe133" -OJ 'https://api.atdata.com/v5/list/4321/results'
    

    To download the results with curl with the filename given by InstantData, use -OJ flag. InstantData result file names use the format <list name>-<list id>-TowerData.<extension>. For example, if you submitted Newsletter.csv and it was assigned list ID 4321, the default result filename would be Newsletter-4321-TowerData.csv.

    Response and Results Format

    Example Header Response

    Content-Disposition:attachment; filename={filename}-{list_id}-TowerData.{extension} 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 the file containing your data.

    The results file will be in the same format as the input file you submitted, with additional fields appended to the end depending on the services run. If you submitted a .txt or .csv file, the results file will have the same extension. If you submitted a .zip file that contains a .txt or .csv file, the results will be zipped as well.

    The result file will contain a header row, regardless of whether one was on the input file.

    Email Validation results

    If your API key includes Email Validation, the fields in the table below will be appended to each record using the file's delimiter.

    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.

    Email Intelligence results

    If your API key includes Email Intelligence, each of the Intelligence fields that are configured for your API key will be added to each record using the file's delimiter. The fields will be appended even if no data was found.

    You may retrieve the following reports from the InstantData user interface:

    Email Append results

    If your API key includes Email Append, these two fields will be added to each record using the file's delimiter:

    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. Your query limit has been exceeded, or 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 AtData 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 AtData 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 AtData API license. This code is licensed under the Apache License which follows:

    Copyright 2022 AtData

    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 AtData 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 AtData 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 AtData 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 AtData'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 AtData'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 AtData's API; default = false.

    The queryByMd5(String md5Email) and queryBySha1(String sha1Email) methods query AtData'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 AtData'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 AtData'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 AtData 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('sample@atdata.com');
    > print "Gender is $response->{'gender'}\n";
    => Gender is Male
    
    > my $response = query_by_nap('Caitlin', 'Plackard', '789 Chestnut St',
                                  '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 AtData'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 AtData's API with the specified email. If $options is set to true the email address will be hashed to MD5 before querying AtData's API.

    The query_by_md5($md5_email) and query_by_sha1($sha1_email) methods query AtData'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 AtData'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 AtData 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 AtData API key in TowerDataApi.php prior to using the PHP 4 SDK.

    Query Options

    There’s several ways to query AtData'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 AtData'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 AtData'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 AtData'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 AtData'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 AtData 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 AtData API key in TowerDataApi.php prior to using the PHP 5 SDK.

    Query Options

    There’s several ways to query AtData'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 AtData'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 AtData'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 AtData'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 AtData'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 AtData'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 AtData's API with the specified email. If the hash_email option is set the email will be hashed before it's sent to AtData.

    The query_by_md5(self, md5_email) and query_by_sha1(self, sha1_email) methods query AtData'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 AtData'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 AtData'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 AtData'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 AtData'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 AtData'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 AtData'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 AtData's API with email and returns the email_validation object. Raise error if email_validation is not enabled.

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

    SUPPORT

    Contact AtData

    If you have questions or care to make suggestions please use the form or contact information here. We’re here to help so please don’t be shy about contacting us.

    Data Dictionary

    The AtData 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:

    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 AtData database.
    Longevity 0-3 A score when AtData first encountered the email address.
    Month Last Open yyyy-mm The year and month AtData 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 6 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 completed in the household: Completed High School, Attended College, Completed College, Completed Graduate School, Attended Vocational/Technical School
    Financial Segment 54 segments based on consumers' financial propensities, grouping households by similar likelihood for financial behaviors, regardless of demographic characteristics: Involved Investors, Active Savers, Traditional Savers, Informed Control, Solid Investments, Hearth and Home, Online Financiers, Investing in Collections, Adventurous Investors, Comfortable Borrowers, Personal Service, Branded Influence, Asking Advice, Value Shoppers, Brand Variety, Online Automation, Online Learners, Trust Triumphs, Limited Risk Traditionalists, Thrill of the Ride, Learn and Prepare, Naturally Organized, Eye on the Economy, Daily Demands, Balance Vigilant, Comfort Zone, Online Managers, Quality Conscious, Traction for Today, In the Moment, Collectors Clubs, Quality over Price, Studied Purchasers, Deal Seekers, Worth the Risk, Online Influencers, Sophisticated Environmentalists, Budget Optimists, Spontaneous Spenders, Coupon Cutters, Fluent Advisors, Financial Freewheelers, Real Life Recommendations, Civic Centered, Prestige Seekers, Informed Shoppers, Technology Trenders, Future Fundamentals, Online Leaders, Online Connectors, Traditional Moderation, Work and Save, Temperate Technology, Independent Investors
    Financial Group 13 higher level aggregate financial groups that roll up financial segments with similar characteristics: Market Watchers, Conservative Wealth, Specific Savers, Tried and True, Trendy Inclinations, Current Consumers, Rural Trust, City Spotlight, Career Conscious, Digital Financiers, Financial Futures, Stable Influentials, Conservatively Rural
    Home Market Value Market value of household's home: 1k-25k, 25k-50k, 50k-75k, 75k-100k, 100k-150k, 150k-200k, 200k-250k, 250k-300k, 300k-350k, 350k-500k, 500k-1mm, 1mm+
    Homeowner Status The household owns or rents their home: Own, Rent
    Household Income Income of household by range: 0-15k, 15k-25k, 25k-35k, 35k-50k, 50k-75k, 75k-100k, 100k-150k, 150k-175k, 175k-200k, 200k-250k, 250k+
    Life Stage Segment 70 life-stage based household-level consumer segments based on demographic and consumer behavioral data: Summit Estates, Established Elite, Corporate Connected, Top Professionals, Active & Involved, Casual Comfort, Active Lifestyles, Solid Surroundings, Busy Schedules, Careers & Travel, Schools & Shopping, On the Go, Work & Play, Career Centered, Country Ways, Country Enthusiasts, Firmly Established, Climbing the Ladder, Country Comfort, Carving Out Time, Children First, Comfortable Cornerstones, Good Neighbors, Career Building, Clubs & Causes, Getting Established, Tenured Proprietors, Community Pillars, City Mixers, Out & About, Mid-Americana, Metro Mix, Urban Diversity, Outward Bound, Working & Active, Persistent & Productive, Firm Foundations, Occupational Mix, Setting Goals, Great Outdoors, Rural Adventure, Creative Variety, Work & Causes, Open Houses, Offices & Entertainment, Rural & Active, Rural Parents, Farm & Home, Home & Garden, Rural Community, Role Models, Stylish & Striving, Metro Strivers, Work & Outdoors, Community Life, Metro Active, Collegiate Crowd, Outdoor Fervor, Mobile Mixers, Rural & Mobile, City Life, Movies & Sports, Staying Home, Practical & Careful, Hobbies & Shopping, Helping Hands, First Steps, Staying Healthy, Productive Havens, Favorably Frugal
    Life Stage Group 21 higher level aggregate life-stage groups that roll up life stage segments with similar characteristics: Starting Out, Taking Hold, Settling Down, Social Connectors, Busy Households, Working & Studying, Career Oriented, Large Households, Comfortable Independence, Rural-Metro Mix, Affluent Households, Comfortable Households, Working Households, Diverging Paths, Top Wealth, Living Well, Bargain Hunters, Thrifty and Active, Solid Prestige, Community Minded, Leisure Seekers
    Length of Residence Number of years household has 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 The marital status of the primary occupants of the household: Single, Married
    Net Worth The approximate net worth of the household: 0-5k, 5k-10k, 10k-25k, 25k-50k, 50k-100k, 100k-250k, 250k-500k, 500k-1mm, 1mm+
    Occupation The occupation of the primary person in the household: 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
    RFM Offline Average Days Recency, Frequency & Monetary Value - the average number of days between offline purchases for this household.
    RFM Online Average Days Recency, Frequency & Monetary Value - the average number of days between online purchases for this household.
    RFM Average Dollars Recency, Frequency & Monetary Value - the average dollar amount the household spends per order.
    RFM Last Order Recency, Frequency & Monetary Value - the date of the last order made by the household in YYYY-MM-DD format.

    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.

    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.
    Magazine Buyer true;(blank) Purchases of magazine subscriptions.
    Travel true;(blank) Interest in travel.

    Shopper type data

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

    Value definitions:

    Field Value Description
    Big Spender IBAM Individual makes big purchases, spending large sums of money.
    Deal Seeker IBAM Individual has shopped online using coupons and discount comparison sites.
    Luxury Shopper IBAM Individual has shopped online for high-end fashion items and luxury brands.