Whether it is to comply with GDPR, cleanse emails for a mailing campaign, or ensure that new users provide you with a deliverable email address, DOTS Email Validation 3 (EV3) is a powerful tool that will ensure the accuracy of your email addresses. Our email validation service is extremely popular with customers and data validation experts alike for a good reason: it has extremely robust capabilities, performing over 50 tests to determine the validity of an email address.

Part of the power of Email Validation lies in its depth of features. It has the power to correct common typos in domain addresses or syntax, detect fraudulent addresses and flag known spammers, among many other tests. But for most users, the most important thing it does is take the results of its validation tests and give you a simple, quantitative score for how valid your email address is.

Score	Description
0	Email is Good
1	Email is Probably Good
2	Unknown
3	Email is Probably Bad
4	Email is Bad

But what do these scores mean? Read on, and we’ll break it down for you.

How to Interpret your Email Validation scores

The Email Validation service returns a score that ranges from 0 to 4, representing how likely it is that an email address is valid. Lower numbers are better: a score of 0 indicates a good email address, and a score of 4 indicates a bad one. Simple enough, but what if the score we return is in between these two numbers? Since we run over 50 validation tests, there are a variety of reasons why a particular score is chosen, so let’s look at what these numbers really mean.

Score 0 – Email is good

We give a score of 0 to an email address that we have a lot of confidence in. This generally means that its SMTP server was good and that our service was successfully able to communicate with it. This score also means that we did not find the email address to contain any vulgar, garbage or bogus arrangement of characters.

In some cases where we return a zero score, we can even determine if the mailbox of an address is valid: for example, in the case of the address example@serviceobjects.com, this would mean that the “example” part of the email address was valid with the SMTP server. The validity of the mailbox can be viewed in the IsSMTPMailBoxGood response from the service as well.

Score 1 – Email is probably good

We give a score of 1 to email addresses that appear to be mostly good but may have some extenuating reasons for why we are hesitant to call it completely good. For example, email domains that are considered to implement greylisting techniques often receive a score of 1: this doesn’t necessarily call into the question the validity of the email address, but rather indicates that one may encounter greylisting behavior when trying to interact with this address.

(Greylisting, by the way, is when an email domain temporarily rejects incoming emails from unfamiliar senders. The logic of greylisting is that regular email servers will queue and reattempt delivery of your message, while bulk spammers won’t. However, delivery of your email may be delayed anywhere from minutes to days.)

Generally speaking, scores of 1 and 3 are relatively rare. Most emails will be able to be classified into a score of 0, 2 or 4.  Scores of 1 and 3 are reserved for cases where we are hesitant to call an email completely good or completely bad.

Score 2 – Unknown

A score of 2, in essence, indicates that the service was not able to make a definitive decision about whether or not an email address was valid. One of the most common reasons for this is when the mailbox for the email address is a “catch all domain” like yahoo.com, which will essentially receive any email that is sent to any mailbox at that domain. Even if the specific mailbox does not exist, the domain will still receive the email message. Another reason that may cause a score of 2 is greylisting by a mailbox domain.

Score 3 – Email is probably bad

These scores are for email addresses that are most likely bad but don’t fail enough of our validation tests to incur a completely bad score. Like emails with a score of 1, these are generally rarer than the other scores. Results that may move an email from a score of 2 to a score of 3 include getting a flag indicating that the email string contained bogus, vulgar or garbage characters. Email addresses with a score of 3 still may be deliverable, however.

Score 4 – Email is bad

If an email returns a score of 4, this means that it failed one of our more serious validation tests. For example, this email address may have had an invalid DNS, an invalid domain syntax, or the mail box simply does not exist.  If an email address fails one of these important tests our service will forgo all of the subsequent tests and return a score of 4.

How to use your scores

Generally, we recommend that clients consider emails with a score of 0 to 2 as “good” emails. However, you may want to use the additional results that Email Validation returns along with your own use case to determine the best emails to target. For example, if you want to be more conservative with your email campaigns then only sending emails to score 0 and 1 addresses may be the appropriate way to proceed. Conversely, if you would like to reach the broadest crowd possible, allowing emails with scores of 0 to 3 may be beneficial for your use case.

In a very real sense, DOTS Email Validation 3 serves as a consultant for your outbound email efforts: it provides you with data, but lets you make the final decision about who to send to. Understanding the scores we provide helps you use this data effectively – and in the process, get the most value out of your email contact assets.

Email and email validation technologies continue to evolve and it is increasingly important that businesses keep up with these changes to ensure they are protected and getting the most out of their email lists. Whether the intention is to verify emails for a mailing campaign, verify users when they sign up on a webpage or ensure that your data is compliant with privacy laws like the General Data Protection Regulation (GDPR), our DOTS Email Validation 3 service helps ensure your email data is accurate, valid, and up-to-date.

In our Applications Engineer department, we are proud of our product expertise and happy to work with you and make integration recommendations that best meet your needs. We have found that each use case and integration scenario is different and may require using different parts of the email validation service to achieve best results. We always recommend starting with a free API key and checking out our comprehensive and up-to-date developer guide for a strong understanding of everything our service can do. With that said, below are some of the most common discussions we have with our clients when integrating our Email Validation service.

Setting up Email Validation’s Web Service Call

Our recommended operation for the service is the ValidateEmailAddress operation. This method has four input fields; EmailAddress, AllowCorrections, Timeout and LicenseKey. The EmailAddress field should be the email address to be validated and the License key should be the trial or production key supplied by Service Objects (you can get yours here). The AllowCorrections and Timeout fields can be used to fine-tune the results from our email validation service.

The AllowCorrections field will essentially tell the service whether to attempt a correction on the email address if the original one is found to be invalid. This is helpful, especially for scenarios where the user mistypes their email address. This can also be set to “false” to weed out users that do not “strongly” type their email addresses.

The Timeout value uses a number in milliseconds. This value sets the maximum amount of time for our services to communicate with a mail server in a given request. One of the key features of our service is that it performs real-time SMTP communication with mail servers and part of this communication is waiting for the mail server to respond. So in short, the longer the timeout, the greater the validation accuracy will be. This will help turn the unknown email addresses (score 2; more on this below) into either good or bad emails. Most mail servers will respond very quickly to communication, but smaller or lesser known servers can take a bit of time to respond.

Email Validation Scoring

There are a lot of different results returned in the Email Validation service and the best use case depends on your business logic and what you are hoping to achieve with the service. Arguably, the first return you will want to look at would be the score value that is returned, below are the scores and a brief description.

Score	Description
0	Email is Good
1	Email is Probably Good
2	Unknown
3	Email is Probably Bad
4	Email is Bad

Generally, we recommend that our clients accept emails with a score of 0, 1 or 2 as “good” emails. If you want to be more conservative with email campaigns then only including emails with scores of 0 or 1 would be the way to go. This may not be the best option if you are validating users that fill in a form on your webpage, as many popular catch-all domains (e.g. yahoo, hotmail, etc.), will return an Unknown (2) score from the service. Conversely, considering good emails as scores from 0 to 3 would be an option if you want the highest volume of possible good emails.

Warning Codes

The Email Validation service also returns Warning and Note codes for each email that is validated. Generally speaking, the Warning codes help define what is detrimental to the email score. Warning flags like Bot, Vulgar, Garbage and DisposableEmail are obvious indicators of a bad email address. But a warning flag like “KnownGreylister” indicates that the mail server is known to use greylisting techniques but this doesn’t necessarily mean the email address is bad. If you are sending an email campaign through MailChimp, Marketo or similar platforms, then you may experience temporary bounce backs on email addresses with the KnowGreylister flag, as those email domains will give a temporary reject message due to unfamiliar mail servers.

There are over 20 Warning codes that our Email Validation service can return, see the table below for the complete list and a brief description of each.

Code	Warning Name	Description
0	UnrecognizedTLD	Indicates if the top-level-domain is not recognized by ICANN.
1	InvalidSyntax	Indicates if the email is syntactically invalid.
2	InvalidDomainSpecificSyntax	Indicates if email is syntactically invalid for the given domain.
3	InvalidDNS	Indicates if the domain is unregistered or it does not have at least one MX or A record configured to relay email.
4	NoMXRecords	Indicates that the registered DNS does not have an MX record.
5	Established	Indicates that the email address is known to be in bulk marketing lists.
6	Alias	Indicates if the email address is believed to be an alias address.
7	Bogus	Indicates if the email address is believed to be a bogus email. For example, asdf@asdf.com.
8	BogusSMSAddress	Indicates if the email address is believed to be a bogus SMS domain address.
9	Garbage	Indicates if the email address is believed to contain garbage-like keyboard strokes and/or garbage-like characters.
10	Vulgar	Indicates if vulgar words or content are found in the email address.
11	MailBoxIsFull	Indicates if the mailbox is currently full and unable to receive any new messages.
12	MailboxIsBusy	Indicates if the mailbox is reported by the hosting mail server as being busy and unable to currently accept new messages.
13	DisposableEmail	Indicates if the email address is believed to be disposable. Disposable email address are generally only valid for a short period of time before they are disposed and are then no longer valid.
14	SpamTrap	Indicates if the mailbox is believed to be a spam trap.
15	KnownSpammer	Indicates if the email address is known to have participated in spam-like activities.
16	BlacklistedDomain	Indicates if the domain was found to be in one or more blacklists.
17	KnownComplainer	Indicates if the email address has been identified as a known complainer of receiving unsolicited mail.
18	KnownGreylister	Indicates if the mail server is known to commonly use greylisting techniques. This means that if your mail server is communicating with this domain for the first time or if you are sending bulk messages or messages in high frequency then you may be greylisted by them and experience temporary bounce backs.
19	OptInRequired	Indicates if the mail server requires opting-in to send and receive messages.
20	IsWhiteListOnly	Indicates if the mail server only relays messages for users that are whitelisted.
21	ConnectionRefused	Indicates if the mail server refuses to accept an SMTP connection.
22	Email is Bad - Subsequent checks halted.	Indicates that the email address failed a critical check, such as SMTP verification.
23	Bot	Indicates that the email address has been reported as being a known bot.

Note Codes

Notes from Email Validation typically provide additional information about an email domain and can be leveraged to intelligently target specific email addresses. For example, if you have an email sign up form and you want to limit the sign-ups to business emails, then you might want to want to look for email addresses with the BuisnessAddress note flag, which would indicate that the email is likely associated with a business. Or maybe you want to identify country based email addresses? Then it may be wise to filter out emails that receive the CCTLD note code as these will indicate emails that have a Top-Level Domain (i.e. .com of example@serviceobjects.com) that is associated with a specific country.  In addition, we recently rolled out a new feature that can detect the geographic location of the email’s mail server.

Other Note Codes you may want to pay attention to are those indicating the service had trouble connecting to the mail server.  While these notes don’t indicate that an email is bad, they do reflect simulated interactions with mail servers and may indicate trouble contacting customers via email campaign or through typical email delivery. You can see the complete list of Note Codes and their descriptions below.

Code	Note	Description
0	CCTLD	Indicates if the top-level-domain (tld) represents a specific country. For example ".us" implies United States.
1	Free	Indicates if the domain of the email is a public-register domain, where users can sign up for email accounts for free.
2	SMSDomain	Indicates if the domain is a known Mail-to-SMS Gateway.
3	Role	Indicates if the email address appears to be a role that is designed to be anonymously managed by one or more persons.
4	BusinessAddress	Indicates if the email address appears to be work related.
5	GreyListed	Indicates if the mail server responded with a known greylist tactic.
6	MailServerTemporarilyUnavailable	Indicates that the mail server may be temporarily unavailable or too busy to respond.
7	ServerConnectTimeout	Indicates that a connection to the recipient mail server could not be established.
8	MailBoxTimeout	Indicates that the connection to the mail server timed out when trying to verify the email address.
9	TemporaryReject	Indicates that the email address was temporarily rejected by the mail server. This is also known as a soft-bounce and the rejection is not permanent. There are many reasons for why a mail server may respond with a temporary reject. The mailbox or server may be busy, unavailable, or using a greylist. When a mail server does this it typically wants you to wait at least 15 minutes and then try again later.
10	SlowMailServer	Indicates that the host mail server is known to communicate slowly and that real-time verification of an email address may not be possible unless adequate time is provided. In some cases a timeout time of 90 seconds or more may be necessary to verify email addresses with these mail servers.
11	Varies (Example: JP)	Countries: The ISO2 country code for the country where the mail server(s) is located. If mail servers are found in more than one country, then all country ISO2 codes will be represented in a pipe-delimited list. ***In BETA
12	Varies (Example: OS|TY)	Region: The region in the country where the mail server(s) is located. The region is commonly returned as a two-character abbreviation. If mail servers are found in more than one region then the value will be a pipe-delimited list of the regions. ***In BETA
13	Varies (Example: Osaka|Tokyo)	Localities: The name of the locality where the mail sever(s) is located in. If mail servers are found in more than one locality then the value will be a pipe-delimited list of all the localities. ***In BETA
14	Varies (Example: 543-0062 | 102-0082)	PostCodes: The post code of where the mail server(s) is located. If multiple post codes are found, then the value will be a pipe-delimited list. ***In BETA

Our Email Validation service is robust, multi-featured and constantly under refinement. Don’t hesitate to schedule an integration call with our Applications Engineering team with any integration or best practices questions, we are glad to help.

DOTS Lead Validation International is easily our most robust and valuable service. This service improves the quality of your leads by correcting or eliminating unreliable contact record data while providing you with an overall quality score, so you can make informed business decisions. This service cross-references prospects’ name, address, phone, email, and IP address to ensure the lead information is genuine, accurate and up-to-date.

The quality of each of these data points is analyzed and scored separately and also combined to provide a weighted composite score for the overall lead quality and certainty. These individual and composite scores are included in the fifty-plus outputs the service provides, allowing you to tailor business logic to meet your needs.

Lead Validation International can be used like our other services; as a real-time API, as a cloud connector for major CRMs and marketing automation platforms, or as an FTP service. If none of these work for you, you can send us your list and we will validate and correct the leads for you.

Customizing Lead Validation International to Meet Your Needs

Even if you are missing some of the contact record data points (e.g., email, phone, address, name, or IP) that the service uses to validate leads, our service can be customized to use the data you do have, correct any issues with it and provide certainty scores. To customize our service to work with your available data, we suggest using the variable, TestType. There are a number different test types that address common variations of available data points and the needs of our clients. These test types can be further configured to meet the specific needs of your application and business. If you are not sure about what test type you should use, please don’t hesitate to reach out, we will gladly help with best recommendations. We are committed to making sure you receive the full benefit and power of our Lead Validation International service, and if none of the available test types meet your needs, we are happy to create custom ones that will.

Interpreting API Responses

Interpreting the response from our API is an important first step in determining the best ways to use the service and how the resulting validated data can benefit your business. There are only three “required” inputs to Lead Validation International: Country, TestType, and LicenseKey. If all three of these inputs are provided, Lead Validation International will attempt to process all the lead information that is present. If the required inputs are not provided, here are some of the errors you might encounter:

1. Error Code 1 – Authorization Codes

These errors indicate there is something wrong with the license key and we recommend that you double check you are using the correct key. One of the most common causes for this type of error is using a test key in a live environment (or vice-versa). Fortunately, this type of error is simple to detect and correct. In the test environment, the request URL should start with “https://trial.serviceobjects…” and be used with the test key sent to you. Production keys and URLs are different and issued only to customers. For other errors, please do not hesitate to reach out to us to help troubleshoot.

Error Description Code	Error Description	Additional Description
1	Please provide a valid license key for this web service.	There was no license key submitted to the service. Often, this occurs when the URL encoding has not occurred correctly.
2	The daily allowable number of transactions for this license key has been exceeded.	This does not apply to all keys, but some have a daily maximum transactions limit.
3	The monthly allowable number of transactions for this license key has been exceeded.	Some keys have a monthly maximum. You will encounter this value if you pass the monthly maximum.
4	The total allowable number of transactions for this license key has been exceeded.	The overall amount of transactions has been exceeded.

 

2. Error Code 2 – User Input 

Something is wrong with the inputs. Either necessary fields were left blank, or the inputs entered are too long.

Error Description Code	Error Description	Additional Description
1	That does not appear to be a valid TestType.	The given test type was either blank or an invalid test type. Please contact us to help assist with a test type that would suit your needs.
2	The Country input is missing.	There was no value in the Country field of the input. This is a required field that allows the service to cross reference different data points.

 

3. Error Code 3 – Fatal Errors 

This unlikely error indicates that the web service is behaving in an unexpected way. If you see this error in a production environment, please notify Service Objects at once.

Error Description Code	Error Description	Additional Description
1	Unhandled error. Please contact Service Objects.	Like it says, please contact Service Objects immediately and let us know what inputs you used to create this error.

 

4. Error Code 4 – Domain Specific 

Some of our other services return Domain Specific errors which indicate the validity or lack thereof of the information sent to the service. Lead Validation International works a bit differently since it is a composite service and cross-checks data points to provide an overall score for the lead. Currently, there are no Domain Specific errors in our Lead Validation International service.

Validated International Lead Outputs

If everything is working as expected, the service will return over fifty outputs including validated and corrected data, quality scores and any additional notes that might be helpful. The table below shows the most common outputs and a brief description of what they mean.

Return Value	Description
OverallCertainty	This is the total lead score. It represents how likely it is that the given lead is valid. 100 is the best score, and 0 is the worst.
OverallQuality	There are only three different values that can be returned for this field: Reject, Review or Accept. This is a quick and easy flag that can be used to identify the overall quality of the lead. If necessary, separate reject, review, and accept flags can be developed internally.
LeadType	Provides a classification that helps flag the type of lead given. Values will be Residential, Business, or Unknown.
LeadCountry	The country associated with the given lead. It is presented in ISO2 format.
NoteCodes	These will be an enumerated list of the overall codes associated with the lead. These note nodes will provide further information about the quality of the lead and the different data points that did or did not match up. As a general rule, NoteCodes that are lower than 100 are marks against a lead and notes higher than 100 are data points that indicate cross data matching in the lead.
NoteDesc	These will be the descriptions that are associated with the NoteCodes.
NameScore	This is the first of the different component scores that Lead Validation International provides. Along with an overall certainty score, Lead Validation International will provide a score for each of the different pieces of information given as inputs. This field ranges from 0 to 100 and indicates the probability that the given data name is valid.
NameQuality	Values will be Reject, Review or Accept. A quick and easy flag to accept or reject the name portion of the lead.
FirstName	The first name without diacritic (i.e., accented) characters.
LastName	The parsed out last name of the lead.
FirstNameClean	The first name without diacritic (i.e., accented) characters.
NameNoteCodes	An enumerated list of note codes that provide further information on the quality of the name.
NameNoteDesc	The text-based descriptions associated with the codes in the previous field.
AddressScore	The overall score of the address portion of the lead. It ranges from 0 to 100.
AddressQuality	A simple reject, review or accept flag indicating the quality of the address portion.
Address1	The validated Address1 line of the input address.
Address2	The validated Address2 line of the input address.
Address3	The validated Address3 line of the input address.
Address4	The validated Address4 line of the input address.
Address5	The validated Address5 line of the input address.
AddressLocality	The locality associated with the given input address. This is typically the City of the address.
AddressAdminArea	The Administrative Area associated with the input address. Typically corresponds to the State or province of an address.
AddressPostalCode	Validated postal code of the input address.
AddressCountry	Validated country associated with the input address.
AddressResolutionLevel	The resolution level to which the input address could be resolved. This will give some information on whether there is DPV, premise, or other data available for an address.
AddressNoteCodes	An enumerated list of codes that provide more information on the quality of an address.
AddressNoteDesc	Descriptive notes that correspond to the note codes for this field.
EmailScore	A score between 0 and 100 that ranks the validity of the given email address.
EmailQuality	A reject, review or accept flag that gives a simple flag on the quality of the input email address.
EmailCorrected	A True or False flag that indicates whether or not the input email address was corrected.
EmailNoteCodes	An enumerated list of codes that provide more information about the quality of the email address.
EmailNoteDesc	Descriptive notes that correspond to the note codes.
IPAddressScore	A score between 0 and 100 representing the validity of the given IP address.
IPAddressQuality	A simple reject, review and accept flag that will highlight the validity of the IP address portion of the lead.
IPCountry	The country associated with the IP Address.
IPLocality	The locality associated with the IP Address.
IPAdminArea	The Administrative area associated with the IP Address.
IPNoteCodes	An enumerated list of note codes that provide additional information about the quality of the IP address.
IPNoteDesc	Descriptive notes that correspond to the note codes.
Phone1Score	A simple reject, review, or accept flag that that indicates the quality of the given phone number.
Phone1Quality	A Simple reject, review or accept flag that that indicates the quality of the given phone number.
Phone1Locality	The Locality associated with the Phone1 field.
Phone1AdminArea	The Admin Area associated with the Phone1 field.
Phone1Country	The Country associated with the Phone1 field.
Phone1NoteCodes	An enumerated list of note codes that provide additional information about the quality of the Phone Number.
Phone1NoteDesc	Descriptive notes that correspond to the codes in the previous fields.
Phone2Score	A score between 0 and 100 that indicates the validity of the phone number in the Phone2 field.
Phone2Locality	A simple reject, review or accept flag that that indicates the quality of the given phone number.
Phone2Locality	The Locality associated with the Phone2 field.
Phone2AdminArea	The Admin Area associated with the Phone2 field.
Phone2Country	The Country associated with the Phone2 field.
Phone2NoteCodes	An enumerated list of note codes that provide additional information about the quality of the Phone Number.
Phone2NoteDesc	Descriptive notes that correspond to the codes in the previous fields.
PhoneContact	A Phone Contact Object. We will list this below.
InformationComponents	An array of information components. These are key-value pairs that can allow us to additional outputs and features to Lead Validation in the future.

 

When available, Lead Validation International can return the contact name and address information associated with the phone number.

Name	Name associated with the phone number.
Address	Address associated with the phone number.
City	City associated with the phone number.
State	State associated with the phone number.
Zip	Zip Code associated with the input address.
Type	Indicates the phone contact type. Returns can be Residential, Business or Unknown.

 

Hopefully, this quick primer is the first step to developing a better understanding of our Lead Validation International service and how it can be applied to your needs. Please reach out to us with any questions, and we will gladly provide recommendations, integration assistance or any other help you may need.

DOTS Address Validation 3 is one of our most popular services – for good reason! This service is robust and good at what it does. Our powerful CASS certified engine provides our customers with quick and efficient address validation. Because of the complexities associated with DOTS Address Validation 3, there can be lingering questions about what certain fields mean or even how to use it. I am one of the integration specialists here at Service Objects, and I am here to help demystify some of the key features that DOTS Address Validation 3 boasts.

DOTS Address Validation 3 Use Cases

One of the most popular ways to use DOTS Address Validation 3 is to put it directly in a web form where the user enters their address. In this case, an address can be sent to our services, verified, cleansed, and validated before it is used for shipping purposes or before it is put into a database. Based on the DPV code that our service returns, we can also indicate whether an address is missing secondary unit information (i.e., like an apartment or suite number), or if the given secondary unit information isn’t considered valid by the USPS. This DPV value can be used to relay information back to a customer to correct or add the right Secondary unit number.

If you don’t have the ability to call an API from a web form, another use case could be to collect the addresses that you acquire and submit them in bulk with an FTPS set up. Our processes will determine when a file has been uploaded and will process the records and then spit out a file with the validated data that you can use to upload back into your database

If you have a large existing database of uncleansed addresses, you are in luck! We offer large list processing that will allow you to cleanse existing databases. We are experts at running large quantities of data quickly, so we’re happy to process these lists for you to clean up your existing database.

Responses

Knowing how an API works is essential to integrating it and to using its response. One thing to note about DOTS Address Validation 3 is that if an address is invalid, then it will return an error object in the response. In other words, if DOTS Address Validation 3 returns an error, it means the address couldn’t be validated. If an address is valid or partially valid (more on that later) then it returns the address information. There are different errors the service can return that will help you troubleshoot what is occurring with the API call and determine so you can correctly handle each type of error that comes back.

 

1. Error Code 1 – Authorization Codes

These errors indicate that something was wrong with the license key. These errors are not billable. You may also need to reach out to Service Objects if you encounter these errors in a production environment.

Error Desc Code	Error Description	Additional Desc
1	Please provide a valid license key for this web service	There was no license key submitted to the service. Oftentimes this occurs when the URL encoding hasn’t occurred correctly.
2	The daily allowable number of transactions for this license key has been exceeded.	This doesn’t apply to all keys, but some have a daily maximum transactions
3	The monthly allowable number of transactions for this license key has been exceeded.	Some keys have a monthly maximum. You will encounter this value if you pass the monthly maximum
4	The total allowable number of transactions for this license key has been exceeded	The overall amount of transactions has been exceeded.

 

2. Error Code 2 – User Input

Something was wrong with the inputs. Either necessary fields were blank, or the inputs were too long.

Error Desc Code	Error Description	Additional Desc
1	Address and Address2 fields were too long. Together, they must be 100 characters or less.	The input fields were too long
2	Address field was too long, must be 100 characters or less.	The input fields were too long
3	Please input a street address.	There was no Address1 or Address2 values entered
4	Please input either zip code or both city and state.	The service needs either a zip code or both city and state to perform a successful validation.

 

3. Error Code 3 – Fatal Errors

These errors indicate that a Service Objects web service is behaving in a way that it should not. If you ever see this error in a production environment, please notify Service Objects immediately.

Desc Code	Error Description	Additional Desc
1	Unhandled error. Please contact Service Objects.	Like it says, please contact Service Objects immediately and let us know what inputs you used to create this error.

 

4. Error Code 4 – Domain Specific

These errors occur when something has gone wrong with the validation process; usually, an invalid address. There are also more specific messages for each error you can use to help decipher the reason for the failed address validation.

Desc Code	Error Description	Additional Desc
1	Address not found	Major issue with the address that doesn’t fit known USPS special case scenarios.
3	Multiple addresses match	Several address candidates were found that are equally likely given the input. Ex: “1 Main St” matches “1 E Main St” and “1 W Main St”.
5	Please enter a valid address number.
7	Street not found	Street name not found for the general area (city/state or zip)
8	Street number or box number out of range	Street name found in the area, but the given primary number is not valid for that street
12	Internal error.	Returned when an unexpected error occurs while processing address, or for special address cases. This error isn’t likely to appear
14	City not found	City name not found for given state or postal code
15	State not found	State abbreviation not found. The input state didn’t seem to be a valid state.
17	Address not found but the region has General Delivery service	Given address not found, but the region provided matches a known area that only provides General Delivery services. Mail sent to “General Delivery” with the recipient’s name may get delivered to the recipient.
21	Unable to parse address.	Indicates that the input could not be parsed into address fragments.

Non-Error Response

If there wasn’t an error returned, that’s good news! It means your request has resulted in validated address information. Below is a list of all the values recommended for a GetBestMatches operation. If you are using an operation other than GetBestMatches, then some of these values may not apply. Another thing to be aware of regarding GetBestMatches is the possibility it will return multiple addresses if the input address is vague. For example, when directional information should have been included but was not. In that case, the service will return multiple addresses and let the user navigate the ambiguity.

Return Value	Description
Address1	This is the standardized Address1 line of the address. This along with City, State, and Postal Code are where you will find the verified and standardized address components
Address2	The USPS doesn’t consider the Address2 field to be necessary for mailing purposes. If there is any valid Secondary Unit information sent in the Address2 input our system will pick it up and append it at the end of the Address1 field. If there is any extraneous information in the input Address2 field (i.e. “c/o John Smith” etc.) we’ll try to maintain it in the Address2 field.
City	The validated city for the given input address.
State	The corrected and validated state name.
Zip	The validated and corrected Zip + 4 for the given address.
IsResidential	A “TRUE” or “FALSE” flag will be given to indicate whether the input address is considered to be residential
DPV	A value between 1 and 4. This is arguably the most important values to look at when determining what to do with an input address. The DPV value will essentially indicate the total validity of an address. Your use case may vary but here is an example of how to deal with different DPV values when a customer may be entering address information on a web form. DPV 1 – The Address is in the USPS database and is considered to be a valid mailing address. DPV 2 – The address is not in the USPS database. This means that this address may exist, but the USPS simply does not deliver to it. Perhaps try using an alternate mail delivery company to deliver something to this address. DPV 3 – The given secondary unit information on the address is invalid, ask the user to double check the given Secondary Unit information and try again. DPV 4 – The service and subsequently the DOTS Address Validation 3 service expects a Secondary Unit (i.e., apt, unit, suite etc.) but none was provided. Perhaps ask the customer if they are missing the required unit information.
DPVDesc	The text value that explains the DPV result
DPVNotes	Numerical notes that indicate different pieces of information about a particular address. Some of the notes can be things like: Post Office Box address, Firm or Business address, Address exists but is vacant, Military APO/FPO address etc. For a full list of these codes please visit our developer guides.
DPVNotesDesc	The text descriptions that are associated with the values in the DPVNotes field
Corrections	An enumerated list of codes that indicate certain corrections were made to the input address. I.e., City corrected, state correction etc. For a full list of Correction codes, please visit our developer’s guide.
CorrectionsDesc	The text descriptions for the codes provided in the corrections field.
BarcodeDigits	This is a value that the USPS uses to sort mail. Each deliverable address has a unique barcode digit value. A benefit of this is that users can utilize this value to dedupe records in a database. Meaning if you have several different records with the same Barcode Digit, then you can clean up your database.
CarrierRoute	A 4-character string that highlights the carrier route the USPS uses to for this address.
CongressCode	This is congress code that is associated with the congressional district number in which the address is located
CountyName	The name of the county in which the address resides.
FragmentHouse	This is the parsed-out house number for an address. i.e., 123 of 123 W Main St N. The rest of these values are typically used to reconstruct an address that has been validated. Most customers who use these values use them to reassemble an address into different fragments for cases where an application might have character limitations.
FragmentPreDir	The parsed pre-directional of the address’s street. “W” of 123 W Main St N.
FragmentStreet	The parsed-out street name. “Main” of 123 W Main St N.
FragmentSuffix	The parsed-out suffix of the street. “St” of 123 W Main St N.
FragmentPostDir	The parsed-out directional fragment of the address. “N” of 123 W Main St N.
FragmentUnit	The parsed-out unit designator of the input address. Can be values like APT, STE, UNIT etc.
Fragment	The parsed-out unit number of the secondary unit designator. “4” of Unit 4
FragmentPMBPrefix	The parsed type of personal mailbox designator. This will likely be “PMB” or “Box”. Some addresses have personal mailboxes to which mail can be delivered.
FragmentPMBNumber	The parsed-out number from the PMB designator. 4 of PMB 4.

 

This covers most of the basics of DOTS Address Validation 3. As I mentioned, because of the robust capabilities of our CASS certified engine and the comprehensive nature of DOTS Address Validation 3’s data input fields, users are sometimes confused about how to use certain fields or how DOTS Address Validation 3 can be used or integrated. If you want to learn more about how DOTS Address Validation 3, please don’t hesitate to reach out to us! We’d be happy to answer any follow-up questions you may have and make recommendations on how to interpret and use the results from the service.

You know what it is like when that new phone doesn’t get a dial tone, or your router isn’t getting an internet signal. In much the same way, connectivity issues are an annoying but common part of implementing web services in your applications software. Whether it is navigating your system’s firewalls, moving from development to production environments, or simply dealing with calling out to an API, few things are as frustrating as troubleshooting a piece of code that should be working but isn’t.

We are here to help. The Applications Engineering team here at Service Objects understands the full range of connection issues, and after 15-plus years in business we’ve seen it all. Between the sample code we’ve written and the support we provide our customers, chances are that we can help you get your application up and running as quickly as possible with the Service Objects’ API of your choice. But first let’s look at some of the most common issues we’ve seen, and how you can troubleshoot them.

Monitoring Tools

Tools like Wireshark and Fiddler can be invaluable when debugging a connection to a web service.  These tools allow you to see all the different network connections that your system is making, and can also allow you to view the information that is being sent to the service.  This can be helpful for cases where you want to see what exactly is being sent to our services. Often these tools can highlight malformed requests, blocks by your firewall or any other odd behavior that is getting in the way of receiving valuable data from one of our APIs.

Firewalls, IP Addresses and Connection Issues

Another issue we see quite frequently is a connection issue when moving a website or application from development to production.  If this happens, and you experience issues connecting to our services, a couple of quick checks can get you pointed in the right direction to debug your application.

First, check if your firewall needs to have IP addresses whitelisted. If it does, reach out to us at support@serviceobjects.com and we will be happy to provide the most up-to-date set of IP addresses that our services utilize. Still having a tough time connecting to our services? Check through a command prompt on the server in question to ensure you can ping our primary (ws.serviceobjects.com) and backup (wsbackup.serviceobjects.com) endpoints. After that, you can perform a trace route to our endpoints to determine if there is any packet loss between your system and ours.

Failover and Service Downtime

A frequent question that we receive about connectivity to our services is what to do if the Service Objects’ API is unreachable.

First, understand that this should normally be an extremely rare event. Our SLA guarantees “five 9” availability, meaning that our services will be available 99.999% of the time. The equates to less than 5 minutes service downtime per year or around 26 seconds of downtime per month. We have several data centers around the country to help provide redundancy to ensure that your data keeps on getting validated in the event that our primary servers are down.

In addition to this, we recommend that you implement a failover call to our web services. What this means is that if our primary endpoint at ws.serviceobjects.com is down or working unexpectedly, your application should call our backup endpoint at wsbackup.serviceobjects.com.  Below is an example of what failover configuration would look like while calling our AV3 service and using C# syntax.

Contacting Service Objects Tech Support

Finally, whether you are just beginning to troubleshoot or are at the end of your rope, don’t hesitate to reach out to us! We can assist you in tracking down issues you are encountering.  It always helps if you can provide any relevant information about the problem you are encountering, such as the error message received, inputs that are causing the error, or time that the issue started. This information will help us isolate whether your problem is an issue with our services or an issue on your end.

Whatever your connectivity issues are, Service Objects support is here to help you. We are always happy to speak with you by phone, do a live screen sharing session with you, share tips or troubleshooting steps by email, or help in any way we can. Don’t hesitate to reach out to us anytime, and best of success with your connections!

Whenever I am in the process of making a new purchase, I do quite a bit of research before I buy. There are many reasons I do the research. I like to know all the technical details and features; satisfy my desire to be as frugal as possible; ensure my money is well spent; and know that I get the best product available at the best price. I know that many other consumers and businesses share the desire to maximize the value of their investment.

We all want to have confidence that we will benefit from our purchases. This is especially true for businesses that are considering purchasing data validation solutions. Throwing some money at cheap solutions or tools can save a business up front, but the direct and indirect costs will grow on an exponential basis when the inferior solution doesn’t work as intended, breaks down, can’t be fixed for a long while, or is unexpectedly unavailable.

Since 2001, Service Objects has prided ourselves on having the best solutions available that provide a full suite of features and benefits. We make sure that we protect your investment in data validation.  Below are just some of the reasons why we have the best service available.

Top Notch Availability

We stand by our commitment to have our services available whenever they are needed. That’s why we have implemented the industry’s only financially backed Service Level Agreement. That means that we promise to have our services provide an uptime of 99.999% availability.  We measure this percentage of availability on a monthly basis. Achieving 99.999% uptime over a month means that our services won’t be down for more than 30 seconds. We implement failovers, backups and many other things to help ensure that we meet this uptime availability.  If we do not, then our customers are eligible to receive service credit based on the unavailability provided.

Fanatic Customer Support

Customer support excellence is one our core values. We have a capable and eager team of people whose goal is to provide the best support available. Whether it’s a question about your account, maximizing the value of the results from our APIs, or any other customer service issues, we are standing by to help in any way that we can.

24/7 Emergency Support

We understand that when your business is experiencing technical issues it can impact your customers. So along with our traditional support, we also offer after hours support options for any issues that may occur during non-traditional office hours. No matter what time it is, we’ll assist with whatever issue you are encountering.  Simply call our office line and follow the prompts to the access the emergency support line.

Custom Solutions

One of the things that we pride ourselves on is the ability to be flexible with the solutions that we provide. On many occasions, we have implemented product improvements that have arisen when customers tell us what new features they are looking for. Service Objects prides ourselves on being flexible enough to pivot to the needs that our customers have. If you have some custom need, just ask! We’d be happy to look into the feasibility of your request.

Here at Service Objects, we are dedicated to helping our clients integrate our data quality services as quickly as possible. One of the ways we help is educating our clients on the best ways to integrate our services with whatever application they may be using. One such application where our tools are simple to implement is Salesforce.

Salesforce is, among other things, a powerful, extensible and customizable CRM. One of the advantages of Salesforce’s extensibility is that users can set up triggers to make external API calls. This is great for Service Objects’ customers, as it allows APIs calls to any our DOTS web services and helps ensure their contact data in Salesforce is corrected and verified.

In the video below, we will demonstrate how to set up a trigger that will call our DOTS Address Validation 3 service whenever a contact is added to our list of contacts.

See full transcript below.

Hello, and welcome to Service Objects video tutorial series. For today’s tutorial we’ll be setting up a trigger and a class in Salesforce that will call out to our DOTS Address Validation 3 web service. If you don’t already know, Salesforce is an extremely powerful, extensible and customizable CRM. One of the great things that we like about Salesforce here at Service Objects is the ability to call out to APIs so that the data going into your CRM can be validated and verified before it gets entered. This means that you can call out to any of our APIs from Salesforce. You can use this video as an overview for how to integrate any of the service, but for this specific example we’ll be using DOTS Address Validation 3.

To participate in this tutorial, you need the following items. A Service Objects web service key, whether that is a trial key or a production key. You can sign up for a free trial key at www.serviceobjects.com. You will need a developer account in Salesforce. You will also need a working knowledge of Salesforce and Apex, which is the native programming language inside Salesforce. We will go ahead and get started.

To start off, one of the first things we’ll need to do is add the Service Objects endpoint into the list of allowed endpoints that Salesforce is allowed to contact within your developer platform. To do this, you can navigate here and type in remote site settings, or remote, and the remote site settings field will pop up. Here, you’ll see a list of all the websites that your Salesforce platform is allowed to contact. In my account here you can see I have ws.serviceobjects.com and wsbackup.serviceobjects.com. To add a new site, you’ll go and select new remote site. Give an appropriate name, and you will type in the URL here. You can see for this example I’m going to type in trial.serviceobjects.com which will only work if you have a trial license key. If you have a production key, you want to add ws.serviceobjects.com and wsbackup.serviceobjects.com as those will be the two primary URLs that you will be hitting with your production Service Objects account.

This trial.serviceobjects.com URL will only work with trial license keys. Click save and new or just save. You see here if we go back to our remote site settings, you can see that trial.serviceobjects.com was successfully added to our remote site settings. Now that we have successfully added the Service Objects endpoint, we’ll want to add some custom objects in our contact field that will hold some of the values that are returned by our DOTS Address Validation 3 web service. To do that, we’ll scroll down and go to customize. In our example we’re using the contacts field, but you can add custom fields to whatever field is most appropriate for your application, and we’ll select add custom field to contacts. Once we are here, we will scroll down and scroll to this contact custom fields and relationship. You can see here I have several custom fields here already defined. I have a DPV, mostly DPV information and error information, which our field set will parse out from our Address Validation 3 response.

We’ll add another field here for the sake of example. For this field we’re going to add the Is Residential Flag that comes back from the Address Validation 3 service. For this we’ll select text, select next, and here we’re going to go ahead and enter an appropriate field name, which I have in my clipboard. We’re going to call it DotsAddrVal_IsResidential. If you hover over this little “i,” it will say this is the label. This is the label to be used on displays, pages layouts, reports, and list views. This will be a more of a pretty type display. You’ll want to name it something more appropriate and something that will work better in your workflow, but for our example we’re just going to name it this.

For length, we’re going to do length of 15, and for the field name we’re just going to call it AddrValIsResidential. This is the internal field name here. When you’re calling an internal field name, you’ll have to add a double underscore and C in the Apex class. We’ll see an example of that in the next piece of code that we’re going to add. We’ll select next. You’ll select the appropriate field level security here. Next again, and go ahead and click save. To add the actual code that will call out to our Address Validation 3 web service, we’ll scroll down here, go to develop Apex classes. I have already added the class to my developer console, but just for the sake of example, I’ll go ahead and delete it and re-add it. I already have the code in a text editor, so I’m just going to copy and paste that, and just go over the code and explain some key points of it.

Now that I have my code copy and pasted in, I’ll walk through some key elements of it. In the sample code that we have, we have some extra commented out information here that gives you some resources like the product page, the developer guide. You can download this sample code along with this tutorial so you don’t have to pause the video and type it out and everything. The first thing we do is substantiate some of the HTTP request objects in this call WS by ID method. We’ll pull back the contact that’s just been added, and so we’ll pull back all these fields. Mailing street, mailing city, postal code, and state as well as the custom DPV and error information fields that we’ve entered into Salesforce. To call an internal field, an internal custom field that you’ve created in Salesforce, you’ll need to add this double underscore C at the end of it. We can see that we’ve done that here and other place where we reference these objects in the code.

Here, you can see we set the endpoint of the request to the trial URL endpoint, and this will point to the GetBestMatches JSON operation, so this will return a JSON formatted output. We’ve URL encoded all of the address information here. As you can see with this EncodingUtil.urlEncode. We’ll encode it to the UTF-8 standard. Another thing to note here is that you’ll have to put in your license key in this field here. Right now we just have it as a generic WS72 XXX, etc, but you’ll want to put in your specific license key. Here, we’ll send a request to the service, and if the response back is null, then that means there was something wrong with the primary endpoint, so we’ll come back here and check out our backup endpoint. For this example, it’s pointing to the same URL, the same trial endpoint. If you have a production key, you will want to point this primary URL to ws.serviceobjects.com, and this backup URL to ws.backup.serviceobjects.com. You’ll want to be sure to change both the license keys to whatever your license key is.

After that failover configuration, we’ll see here we checked the status code. If it’s equal to 200, we’ll go into processing the response from the service. Create some internal address fields here, and we’ll initialize the error response here to none, which would indicate that no error was returned from the service. What this does is it traverses through the JSON response of the service, and it finds the appropriate field. For this case we’ll see if it finds address1, it will set our initial address field to the address1 that was returned from the service. That will be the standardize and validated address information that is returned. We do that with all the fields that are pertinent to us. The DPV and DPV description, DPV notes description, as well as the IsResidential and error fields down here.

Here, you can see if we get a DPV score equal to 1. That indicates that the address is mailable, it is deliverable, and it is considered good by the USPS. This is the L-statement for the 200 code check here. If the 200 code wasn’t right, then we’ll say put the error description as this generic error message. At the end of this, we’ll update the list of contacts, so we’ll go ahead and click save. Now that we have our TestUtil class made here, we’ll go ahead and scroll down, select Apex triggers. To add a new trigger, we’ll select developer console, select file, new, trigger. For a name, we’ll simply call it Test Trigger.

We’ll go down here and select the contact object. We have the little bit of code right here. I have the actual code in a text editor that will call the service, so I’ll just copy that in. Now that I have this copied, you can see here that whenever a contact is added, or before it’s inserted rather, it will call the class that we made which was called WS by ID, and it will send the contact to it. To save this, just simply go to file and save. Hit refresh. We can see we now have a test trigger here. Now, to add a contact and to test out our new trigger, we’ll simply go up here, select contacts. In recent contacts, you can see here we don’t have any, so let’s go ahead and add one. We’ll add in a fake person by the name of Jane Doe. Go down here to the mailing street information, and we’ll enter in an address. For this example, we’re just going to use our Service Objects office address. We’ll put some typos in there so you can see the standardization and validation that the Service Objects web service does.

We’ll do 27 East Coat. That’s suite number 500. We’ll do Sant Barb for Santa Barbara and CA and 93101. We’ll go ahead and save the contact. You can see here that we still have the old values here, and that’s because the Salesforce doesn’t immediately call the outside APIs. It cues it up a little bit, but if we go and select Jane Doe again, we can see that now we have a standardize address here. In our DPV description, we have a message that indicates, “Yes, this record is a valid mailing address.” For this DPV score, we get a score of one. We can find the “Is Residential,” says false, meaning this is a business address. Again here, we see that the validated address, we see the USPS standardize version of the address which is 27 East Cota Street, Suite 500, as well as the validated city and zip-plus four information.

This concludes our tutorial for how to add a trigger and a class that will call out to our Service Objects web service. If you have any questions or any requests to other tutorials, please feel free to let us know at support@serviceobjects.com. We’ll be happy to accommodate.

 

Customer Service Above All.  It is one of our core values here at Service Objects.  Recently, we’ve received several requests for a list of the unique zip codes throughout the US and Canada.  By leveraging our existing services, we’ve made this happen.  We are now offering both the US and Canada list as a free downloadable resource.

So why is Service Objects providing this data? Our goal is to provide the best data cleansing solutions possible for our clients. Part of this means using our existing data to provide our users with the data they need. While other data providers might charge for this type of information, we’ve decided to make it freely available for anyone’s use. These files can be used for several purposes, such as pre-populating a list of cities and states for a form where a user needs to enter address information. The County and State FIPS information is widely used in census and demographic data or could be used to uniquely identify States and counties within a database.  Additionally, the given time zone information can be used to determine appropriate times to place calls to a customer.

Where to Download

allows you to access a .zip file containing two CSV records.  One CSV contains the US information, the other is for Canada.  The files indicate the month and year the records were created. Toward the middle of each month, the data in each record will be updated to account for any changes in US and Canadian postal codes.

What Other Information is in the Files?

Both files will have postal codes, states (or provinces for Canada) and time zone information.  The Canadian zip code file will be much larger in size with over 800K records. This is due to Canadian Postal Codes generally being much smaller than US Postal codes. Where a US postal code can sometimes encompass multiple cities or counties, a Canadian postal code can be the size of a couple city blocks or in some cases a single high-rise building.

The US file has information for all United States postal codes including its territories. This file will also include the county that the zip code lies in. There will be County and State FIPS numbers for each of the records to help with processing that information as well.  The US file will be considerably smaller than the Canadian file at only 41K records.

In making these files freely accessible, our hope is to make the integration and business logic easier for our users. If you’d like to discuss your particular contact data validation needs, feel free to contact us!

As part of our commitment to making our data quality solutions easy to integrate, our Application Engineering team has developed a series of tutorials on how to integrate our services.  The series highlights various programming languages, with this tutorial exploring the “how-to’s” of applying our services using ColdFusion.

ColdFusion is a scripting language that has been around since 1995. It was created to make development of CGI scripts easier and faster.  ColdFusion has unique aspects, including use of its native ColdFusion Markup Language (CMFL for short) to allow HTML style tags for programming with systems. Like most things in the tech world, it can draw a lot of polarized opinions, where some are ardent supporters, and others, less than enthusiastic fans. If you fall in the supporter camp, and want to learn how to call a web service with ColdFusion, that is where our experts can step in and help.

To get started you will need a ColdFusion IDE (we’re using ColdFusion Builder 3) and a Service Objects’ License key. We’re using one for DOTS Lead Validation but you can follow along with your service of choice.

Project Setup

The first step is to launch your IDE and select an appropriate workspace for your project. Next, we will create a new project.

Select next for a blank template and then click next again.  On the following screen give your project an appropriate name and click finish.

Congratulations! You created a brand new ColdFusion project. Now it’s time to add some code. For starters, we’ll want to add a form and elements to initialize our form inputs so that we can create a sample page to input data to send to our web service. This likely won’t be what you will want to do in a live environment, but this is for demonstration purposes.

The DOTS Lead Validation service that we’re using has quite a few inputs so this may take a while. Once you are finished it should look like the following:

Making the Web Service Call

The next bit of code that we will add is to make the actual HTTP GET call to the Service Objects’ web service. Let’s use the CFML tags to make the actual web service call.

After the code makes the call to the trial.serviceobjects.com endpoint, we perform a failover check in the code. This failover check and the try catch blocks that it is nested in will help ensure that your integration of our web service will continue to work uninterrupted in the event that the primary web service is unavailable or not responding correctly.

The primary endpoint should be pointing to ws.serviceobjects.com and the backup endpoint should be pointed to wsbackup.serviceobjects.com.

Displaying the Results

Now that you have successfully called the web service, you will obviously want to do something with the results. For demonstration purposes we will simply display the results to the user.  You can use the code snippet below to display.

If you are having trouble figuring out how a particular output is mapped in the ColdFusion response, then you can use the <cfdump var=””> tag to dump the outputs onto the screen. This should allow for easy troubleshooting.

Now that our CFML is all set up, lets see an example input and output from the service. Below is sample lead information that you might encounter:

And here is some of the response that DOTS Lead Validation will return:

The DOTS Lead Validation service can return a multitude of information about your lead.  To download a trial key for any of our 23 contact validation solutions, please visit https://www.serviceobjects.com/products

P.S.  Here is the full ColdFusion script page in case you need it to get up and running.