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

SafeToSend API - AtData's SafeToSend Email Verification & Hygiene solution.
Email Validation API - TowerData's legacy email validation API.
Identity Matching API - Use one point of contact to find an alternate point of contact.
Email Intelligence API - Query demographic and behavioral data for a single email or postal address.
Email Activity Metrics API - Query email activity data for a single email address.
Bulk Email Intelligence API - Submit up to 5,000 Email Intelligence or Email Activity requests in a single query.
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.

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":"valid",
      "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. These emails will report with a "valid" status since they have passed the majority of our SafeToSend checks. 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.
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.
valid	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"
   }
}

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"
    ]
  }
}

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
   }
}

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

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

Match email address to alternate email address(es)
Match email address to postal address
Match postal address to email address

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.

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:

Demographics such as age, gender and income
Life stages and financial segments
Shopper types such as deal-seeker and luxury shopper

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:

Demographic data
Household data
Email Activity Metrics (EAM)
Name and Postal Address (Postal Append)

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.

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:

submit lists to AtData for processing
retrieve the processed results
check the status of lists and the services that are running on them or
alternatively, post a webhook/callback url to alert you that your list process is complete (or in case of an error)

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"

Multipart method: Set the Content-Type header to Content-Type: multipart/form-data and upload a text or compressed .zip file. This method is recommended as it's less likely to break when uploading large files.
Text/CSV method: Set Content-Type header to Content-Type: text/csv and upload a text file.

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)`.
action	action=report	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:

First name, first, fname
Last name, last, lname, surname
Full name - for combined first and last
Street, address, address 1
Street 2, address 2
City, town
State, region, province
Zip, postal code, plus4
Country
Email
MD5 - hash of a lower case email address
SHA1 - hash of a lower case email address

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

Return a HTTP Status Code 202.
Include a Location: header in the response that provides a URL that can be queried to check the status of a file.
Return a JSON body that contains the ID of the list on the AtData system and the number of bytes received.

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:

Match report - Reports the amount of data found for each field. Each row contains the field name, number of records matched and the match percent (e.g. Gender,687,80.0%).
Chart data - A .csv file showing the distribution of fields with standardized values. Each row contains field name, field value and record count (e.g. Gender,Male,43).
Chart PDF - A PDF containing charts showing the distribution of fields with standardized values.

Email Append results

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

Email address - The appended email address, if one was found.
Match type - Describes the level at which the email address was matched. "Individual" match means the email matches the full name and postal address. "Household" match means the email matched postal address and last name.

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.

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.