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.

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

AtData's Legacy 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.

Email Validation API - TowerData's legacy email validation API.

AtData's Current API Solutions

The following links will take you to the new documentation site

SafeToSend API - AtData's SafeToSend Email Verification & Hygiene solution.
Identity Matching API - Use one point of contact to find an alternate point of contact.
Demographics API - Query demographic and behavioral data for a single email or postal address.
List API - Run files of up to 1,000,000 records through SafeToSend, Email Validation, Email Intelligence or Identity Matching.

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.

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.

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:

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

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

Email activity metrics data

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

Field	Value	Description
Date First Seen	`yyyy-mm-dd`	The date the email address first appeared in our records. The value `now` will be returned if the email address is new to the 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:

I = Interested. Activity in past year.
B = Bought. Has purchased these products.
A = Actively interested. Activity in last 90 days.
M = in Market. Shopping activity in last 30 days.

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.