Introduction

DOTS Email Append is an XML web service that provides a contact’s associated email address.  By providing contact name and address, or name and postal code, DOTS Email Append provides the associated contact name and email address based on a certainty score. 
With Email Append, users append email addresses to existing contact information.  This information can be used to improve online applications or as supplemental information for existing opt in databases. 

Integration

Integration of DOTS Email Append into user applications is generally a straightforward process.  For common programming platforms, such as ASP, ASP.NET, ColdFusion, PHP, etc., Service Objects has sample code available online: 
https://www.serviceobjects.com/sample-code/
If the platform you are currently using is not available online in our sample code base, Service Objects will happily assist you in developing a solution to utilize our services. Email support@serviceobjects.com for more details.

Web Service Structure

Web services provide a standard interface to encapsulate tricky business logic.  They allow simple integration of applications via the web.  Service Objects has followed web services best practices and come up with some of its own standards to ensure that its web services are as easy to integrate, and as accessible as possible. 
The location of the WSDL, or Web Service Definition Language document, is here (This is also accessible via the “Service Definition” link on the web service page.):
https://trial.serviceobjects.com
Important Note!
SOAP is done via POST, only with special XML markup in the post-body.

The WSDL is an XML document that defines the interaction web service, meaning its inputs, outputs, operations, and the like. Most likely, you will have another tool read this WSDL and make the operations available to you in your application via some type of proxy class. Whenever your utilities or IDE asks for a WSDL path, you can provide this one. 
Every web service has operations that it offers to subscribers.  These operations, also called methods, contain different functionality and return different outputs.  DOTS Email Append offers the following operations: 
GetConsumerEmailByNameAndAddress – Uses the provided Contact Name and Address to provide an associated email address. 
GetConsumerEmailByNameAndPostalCodeUS – Uses the provided Contact Name and Postal Code to provide an associated email address. 
Each of these operations will be described in detail later in this document.

Request Types

DOTS Email Append is a public XML web service that supports SOAP(1.1 and 1.2), POST, and GET request methods.  A request type is just the type of web (HTTP) request used to interact with our web services.
GET – All of the input data is in the query string appended to the URL.  The response is simple XML.
POST – The input parameters are in the body of the request instead of the query string.  The response is simple XML.
SOAP – The input parameters are in an XML SOAP message contained within the body of the request.  The response is an XML SOAP message.

 

Analysis of Request Types

GET is the easiest method to implement by hand because you just set up the URL and query string.  It is also easy to debug because you can test the URL + query string in a web browser and see the output.
POST is probably the best method to implement by hand because you do not have to know the specifics of SOAP, and is a little cleaner than passing input parameters in the query string via GET.
SOAP is the best method if you are using a platform that supports SOAP.  In many programming environments you can call the service’s WSDL file (https://trial.serviceobjects.com) to create a proxy class to help you interact with the web service.  In this case you only have to create an instance of the proxy and use its methods.  This completely abstracts the programmer from any complications like sending/receiving web requests/responses as well as any XML parsing.  This is typically available in newer environments like PHP version 5, ColdFusion version 8, .NET, etc.  Older languages like PHP version 4 and ColdFusion version 5 will require the use of GET or POST.

 

XML Parsing

If you are not using an environment that provides a proxy class for you to use, then you will have to parse XML.  If you do have a proxy, then it uses an XML parser behind the scenes for you.  Although XML parsing can be done without a parser, most programming environments provide easy access to several standard ones.  We strongly recommend that you take advantage of an XML parser.  These parsers may take a few more minutes to integrate if the developer is not familiar with them, but will give your application an added level of security against improper parsing.  Without them it is very difficult, even for skilled programmers to write robust code that can handle all cases of XML properly.  Because we have very consistent XML you could get away without this extra precaution, but we suggest you use an XML parser anyway to ensure your application is of the highest quality.

Operation Definitions

This section defines the input, output and behavior of the operations in DOTS Email Append.

GetConsumerEmailByNameAndAddress

Uses the provided Contact Name and Address to return an associated email address.

GetConsumerEmailByNameAndAddress Inputs

Name Type Description
FirstName String The First Name of the contact to return an associated email address.
LastName String The Last Name of the contact to return an associated email address.
Address String The Street Address of the contact to return an associated email address.
State String The State of the contact to return an associated email address.
PostalCode String The Postal Code of the contact to return an associated email address.
LicenseKey String Your license key to use the service. 
Sign up for a free trial key at
www.serviceobjects.com.

GetConsumerEmailByNameAndAddress Outputs

If no errors are encountered an EAInfoResult element will be returned with the following information.  If there is an error, an Error object will be returned (explained in next section).
Name Type Description
FirstName String The First Name of the contact matching the supplied input.
LastName String The Last Name of the contact matching the supplied input.
Email String The Email Address of the contact matching the supplied input.
Certainty String The Overall Score of the contact matching the supplied input.
Corrections String The Corrections that were scored against of the contact. See Corrections Table for a list of corrections made.

GetConsumerEmailByNameAndPostalCodeUS

Uses the provided Name and Postal Code to provide an associated email address.

GetConsumerEmailAppendByNameAndPostalCodeUS Inputs

Name Type Description
FirstName String The First Name of the contact to return an associated email address.
LastName String The Last Name of the contact to return an associated email address.
Postal Code String The 9 digit Postal Code of the contact to return the associated email address.
LicenseKey String Your license key to use the service. 
Sign up for a free trial key at
www.serviceobjects.com.

GetConsumerEmailByNameAndPostalCodeUS Outputs

 

If no errors are encountered an EAInfoResult element will be returned with the following information.  If there is an error, an Error object will be returned (explained in next section).
Name Type Description
FirstName String The First Name of the contact matching the supplied input.
LastName String The Last Name of the contact matching the supplied input.
Email String The Email Address of the contact matching the supplied input.
Certainty String The Overall Score of the contact matching the supplied input.
Corrections String The Corrections that were scored against of the contact. See Corrections Table for a list of corrections made.

Corrections

 

DOTS Email Append uses a proprietary scoring system to test a match between an input contact and a contact stored in our database. The scoring system judges a contact’s match based on the following criteria (First Name, Last Name, Nick Name, Street Number, Street Name, Unit Type and Unit Number). If any of the criteria are not a perfect match then the scoring system will take a deduction from a perfect score. For any deduction that is taken, a correction code is output to show which corrections were made.
The scoring system currently does not return scores which fall below 60 as these have failed multiple tests. It is up to you to determine whether contacts which fall between the 60 – 90 point score are suitable for your needs.

 

Examples Cases

Score Description
85-100 Minor Correction on (First and/or Last Name) or Address.
Example: Single misspelled character in Name
80-90 Correction on Address or Name.
Example: Multiple misspellings
60-80 Major Correction on Name or Address.
Example: First Initial and Last Name only provided, or missing unit type and missing unit number

Correction Code List

Correction Code Description
1 First Name of the input contact was not a perfect match to a result first name. A scoring deduction was taken
2 Last Name of the input contact was not a perfect match to a result last name. A scoring deduction was taken.
3 A First Name match was found using a nick name of the input first name. A scoring deduction was taken.
4 Street Number of the input contact was not a perfect match to a result street number. A scoring deduction was taken.
5 Street Name of the input contact was not a perfect match to a result street name. A scoring deduction was taken.
6 Unit Type of the input contact was not a perfect match to a result unit type. A scoring deduction was taken.
7 Unit Number of the input contact was not a perfect match to a result unit number. A scoring deduction was taken.

Errors

 

Generally, an error is anything that happens during a run of DOTS Email Append that causes the service to fail.

 

There are four error types described below. 

 

Error Types

Type TypeCode Billable Standard for all Gen2 Web Services
Authorization 1 No Yes
User Input 2 Yes No
Service Objects Fatal 3 No Yes
Domain Specific 4 Yes No

Error type 1: Authorization

 

These are standard to all Generation 2 DOTS Web Services.
DescCode Description
0 Unknown authorization error.
1 Please provide a valid license key for this web service.
2 The daily allowable number of transactions for this license key has been exceeded.
3 The monthly allowable number of transactions for this license key has been exceeded.
4 The total allowable number of transactions for this license key has been exceeded.
5 There are not enough transactions available.  Check your daily/monthly transaction limits.
6 This license key has not yet been activated.
7 This license key has expired.
8 Your license key does not work on this service.

Error type 2: User Input

 

These errors occur as a result of bad input.  DOTS Email Append requires all three inputs to be present in order for a proper validation to take place.
DescCode Description
2 Please enter a value for license key value.
2 Please enter a First Name.
2 Please enter a Last Name.
2 Please enter a valid Street Address
2 Please enter a valid 9 digit Postal Code.
2 Please enter a valid City and State or Postal Code

Error type 3: Service Objects Fatal

 

The Desc will always be the same and the DescCode has no meaning.  This is standard to all Generation 2 DOTS Web Services.  This signals an issue within the application, or a Network/Connectivity issue.
DescCode Description
1 Unhandled error.  Please contact Service Objects.

Error type 4: Domain Specific

DescCode Description
3 No Listings Found.

Conclusion

 

We also provide a RESTful interface! For more information on how to use our RESTful interface go here DOTS Email Append – REST

We welcome your feedback! Please do not hesitate to let us know what you think of our web services, documentation, or customer support.
www.serviceobjects.com