Service Objects’ Blog

Thoughts on Data Quality and Contact Validation

Email *


Posts Tagged ‘Integration’

Service Objects ColdFusion Integration Tutorial

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 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 and the backup endpoint should be pointed to

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

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


Service Objects’ Application Engineers: Helping You Get Up and Running From Day 1

At Service Objects, one of our Core Values is Customer Service Above All. As part of this commitment, our Application Engineers are always available to answer any technical questions from prospects and customers. Whether users are beginning their initial investigation or need help with integration and deployment, our Engineers are standing by. While we continually make our services as easy to integrate as possible, we’d like to touch on a few common topics that are particularly helpful for users just getting started.

Network Issues

Are you are experiencing networking issues while making requests to our web services? It is a very common problem to face where outbound requests are being limited by your firewall and a simple rule update can solve the issue. When matters extend beyond simple rule changes, we are more than happy to schedule a meeting between our networking team and yours to get to the root cause and solve the issue.

Understanding the Service Outputs

Another common question revolves around the service outputs, such as how they should look and how they can be interpreted. From a high level, it is easy to understand what the service can provide but when it comes down to parsing the outputs, it can sometimes be a bit trickier. Luckily there are sets of documentation for every service and each of their operations. Our developer guides are the first place to check if you are having trouble understanding how individual fields can be interpreted and applied to your business logic. Every output has a description that provides insight into what that field means. Beyond the documentation, our Application Engineering team is available via multiple channels to answer your questions, including r email, live chat, and phone.

 Making the Move from Development to Production

Eventually everyone who moves from a being a trial user to a production user undergoes the same steps. Luckily for our customers, moving code from development to production is as easy as changing two items.

  • The first step is swapping out a trial license key to a production key.
  • The second step is to point your web service calls from our trial environment to our production environment. Our trial environment mirrors the exact outputs that you will find in production so no other code changes are necessary.

We understand that, even though we say it is easy, making the move to production can be daunting. That is why we are committed to providing your business with 24/7/365 technical support. We want the process to go as smoothly as possible and members of our team are standing by to help at a moment’s notice.

We have highlighted only a few broad cases that we have handled throughout our 16 years of providing genuine, accurate, and up-to-date data validation. Many technical questions are unique and our goal is to tackle them head on. If a question arises during your initial investigation, integration, move to production, or beyond, please don’t hesitate to contact us.

API Integration: Where We Stand

Applications programming interfaces or APIs continues to be one of the hottest trends in applications development, growing in usage by nearly 800% between 2010 and 2016 according to a recent 2017 survey from API integration vendor, Cloud Elements. Understandably, this growth is fueling an increased demand for API integration, in areas ranging from standardized protocols to authentication and security.

API integration is a subject near and dear to our hearts at Service Objects, given how many of our clients integrate our data quality capabilities into their application environments. Using these survey results as a base, let’s look at where we stand on key API integration issues.

Web service communications protocols

This year’s survey results bring to mind the old song, “A Little Bit of Soap” – because even though the web services arena has become dominated by representational state transfer (REST) interfaces, used by 83% of respondents, a substantial 15% still use the legacy Simple Object Access Protocol (SOAP) – a figure corroborated by the experiences of our own integrators.

This is why Service Objects supports both REST and SOAP among most if not all services. We want our APIs to be flexible enough for all needs, we want them to work for a broad spectrum of clients, and we want the client to be able to choose what they want, whether it is SOAP or REST, XML or JSON.  And there are valid arguments for both in our environment.

SOAP is widely viewed as being more cumbersome to implement versus REST, however tools like C# in Visual Studio can do most of the hard work of SOAP for you. Conversely, REST – being URL http/get focused – does carry a higher risk of creating broken requests if care is not taken.  Addresses, being a key component in many of our services, often contain URL-breaking special characters.  SOAP inherently protects these values, while REST on a GET call does not properly encode the values and could create broken URLs. For many clients, it is less about preference and more about tools available.

Webhooks: The new kid on the block

Webhooks is the new approach that everyone wants, but few have implemented yet. Based on posting messages to a URL in response to an event, it represents a straightforward and modular approach versus polling for data. Citing figures from Wufoo, the survey notes that over 80% of developers would prefer this approach to polling. We agree that webhooks are an important trend for the future, and we have already created custom ones for several leading marketing automation platforms, with more in the works.

Ease of integration

In a world where both applications and interfaces continue to proliferate, there is growing pressure toward easier integration between tools: using figures cited from SmartBear’s State of the APIs Report 2016, Cloud Elements notes that this is a key issue for a substantial 39% of respondents.

This is a primary motivation for us as well, because Service Objects’ entire business model revolves around having easy-to-integrate APIs that a client can get up and running rapidly. We address this issue on two fronts. The first is through tools and education: we create sample code for all major languages, how-to documents, videos and blogs, design reference guides and webhooks for various CRM and marketing automation platforms. The second is a focus on rapid onboarding, using multiple methods for clients to connect with us (including API, batch, DataTumbler, and lookups) to allow easy access while APIs are being integrated.

Security and Authentication

We mentioned above that ease of integration was a key issue among survey respondents – however, this was their second-biggest concern. Their first? Security and authentication. Although there is a move toward multi-factor and delegated authentication strategies, we use API keys as our primary security.

Why? The nature of Service Objects’ applications lend themselves well to using API keys for security because no client data is stored. Rather, each transaction is “one and done” in our system, once our APIs perform validation on the provided data, it is immediately purged from our system and of course, Service Objects supports and promotes SSL over HTTPS for even greater protection.  In the worst-case scenario, a fraudster that gains someone’s key could do transactions on someone else’s behalf, but they would never have access to the client’s data and certainly would not be able to connect the dots between the client and their data.

Overall, there are two clear trends in the API world – explosive growth, and increasing moves toward unified interfaces and ease of implementation. And for the business community, this latter trend can’t come soon enough. In the meantime, you can count on Service Objects to stay on top of the rapidly evolving API environment.

Testing Through Batches or Integration: At Service Objects, It’s Your Choice

More times than not, you have to buy something to really try it.  At Service Objects, we think it makes more sense to try before you buy.  We are confident that our service will exceed expectations and are happy to have prospects try our services before they spend any money on them.  We have been doing this from the day we opened our doors.  With Service Objects, you can sign up for a free trial key for any of our services and do all your testing before spending a single cent.  You can learn about the multiple ways to test drive our services from our blog, “Taking Service Objects for a Test Drive.” Today, however, I am focusing on batch testing and trial integration.

Having someone go through their best explanations to convey purpose or functionality can be worthwhile but, as the saying goes, a picture is worth a thousand words.  If you want to know how our services work, the best way to see them is simply try them out for yourself.  With minimal effort, we can run a test batch for you and have it turned around within a couple hours…even less time in most cases.  Another way we encourage prospects to test is by directly integrating our API services into their systems.  That way you see exactly how the services behave and get a better feel for our sub-second response times.  The difference between a test batch and testing through direct integration is the test batch will show the results and the test through integration will demonstrate how the system behaved to deliver results.


Test batches are great.  They give you an opportunity to see the results from the service first hand, including all the different fields we return.  Our Account Executives are happy to review the results in detail and you always have the support of the Applications Engineering team to help you along.  With test batches, you can quickly see that a lot of information is returned regardless of the service you are interested in.  Most find it is far more information than expected and often clients find that the additional information helps them solve other problems beyond their initial purpose.  Another aspect that becomes clearer is the meaning of the fields. You get to see the fields in their natural environment and obtain a better understanding than the strict academic definitions.  Lastly, it is important to see how your own data fairs through the service and far more powerful to show how your data can be improved rather than just discussing it conceptually.  That is where our clients get really excited about our services.


Testing through integration is a solid way to gain an understanding of how the service behaves and its results.  It is a great way to get a feel for the responses that come back and how long it takes.  More importantly, you can identify and fix issues in your process long before you start paying for the service.  Plus, our support team is here to assist you through any part of the integration process.  Our services are built to be straightforward and simple to integrate, with most developers completing them in a short period of time.  Regardless, we are always here to help.  Although we highly recommend prospects run their own records through the service, we also provide sample data to help you get started.  The important part is you have a chance to try the service in its environment before making a commitment.

Going forward with either of these approaches will quickly demonstrate how valuable our services are. Even more powerful is when you combine the two testing procedures with your own data for the best understanding of how they will behave together.

With all that said, if you’re still unsure how to best begin, just give us a call at 805-963-1700 or sign up for a free trial key and we’ll help you get started.

Introducing Service Objects New Open API

Service Objects is committed to constantly improving the experience our clients and prospective clients have with our data quality solutions. This desire to ensure a great experience has led us to revamp and redesign our lookup pages. These pages are easy to use and give all the information necessary for integrating and using our API in your application. This blog presents some of the key features.

Sample Inputs

One request we often receive is a quick sample lookup that will show our customers and prospects what to expect when calling our API. We are implementing just that in our new lookup pages.

In the example below, we are using our Lead Validation International lookup page. If the “Good Lead” or “Bad lead” link is selected, sample inputs will be filled into the appropriate fields. For this example we’ve selected, “Good Lead.”

We implemented this option so that users can get a quick idea of what types of inputs our services accept and what type of outputs the service will return. The form simply needs a license or trial key and it will return the validated data.

All Operations and Methods

Another benefit of these new pages is that they concisely and easily display all the methods available for an API along with all the potential HTTP methods that can be used to interact with the service.

If you want a JSON or XML response, select the appropriate GET operation and you will have everything you need to make a successful request to the service. If you want to make a POST request to the service, simply select the post operation and it will detail all that you need to have your data validated in your method of choice.

Detailed Requests and Responses

Arguably the most important pieces for a developer looking to integrate with an API would be to know how to make a request to the service, and what type of response to expect. These new lookup pages provide that information in a very easy way as shown below.


After making a sample request, you will see the URL used to fetch the validated data, the actual response from the web service, and the response headers that the service provides. These are all vital pieces of information that will have you up and running in no time. The new pages also list what type of response object will be returned from the service. This can be seen below the response body and headers.

Additional Resources

The page also offers up extra pieces of information that will assist with integration. The link to our developer guides, WSDL (for SOAP integrations) and host paths can be found on the page as well. These resources will help you have your application up and running as quickly as possible.

Feel free to sign up for a Service Objects trial key to test with our new look up pages!

Follow This Checklist to Ensure a Smooth API Integration

There can be a lot of “i’s” to dot and “t’s” to cross when integrating with any API.  Here at Service Objects, we certainly recognize there can be a lot on the to-do list when starting an integration project. Integrating with our APIs is pretty straight forward, but we have developed a quick checklist that will ensure it is as easy as possible to follow our best practices.

Failover, Failover, Failover
Service Objects prides ourselves as having 99.999% server uptime. However, in the unlikely event that we do experience an issue with one of our servers, implementing a failover configuration is arguably the most important aspect of integrating with any of our APIs. Proper failover configuration will ensure that your application continues to operate unhindered in an event that the primary Service Objects web server is unavailable or not responding as expected. Below is an example (using C# syntax) of proper failover configuration.

The example above is for our DOTS Address Validation 3 – US service, but this scenario will be relatively similar for our other services. The main thing to note is that the primary call is pointed towards and the backup call within the catch statement is pointed to  In the event that the primary web server is unresponsive, producing strange errors or behaving abnormally, then the backup URL will be called and your application will continue to function as expected.  Another important item to note is that proper failover will check the web service for an error response with a TypeCode of 3. This indicates that a fatal error has occurred in the web service and that the backup URL should be called. If you are using one of our older services, then the error object that service will return may be different (there will be only “Number” and “Desc” fields present in the Error object) and you will need to check for a Number value of 4 to indicate a fatal error.

URL Encoding

Properly encoding the URL you are using is also an item you will want to place on your to-do list for integration. If you are using a path parameter to access our services, then you’ll need to use what’s called RFC3986 encoding to encode your URLs. If you are using query string parameters to hit our services, then you can use the RFC3986 encoding or the older RCF2396 encoding. What do both of those RFC standards mean? Well in short, if you are using a query string URL, spaces can be acceptably replaced with “+” in the URL. If you’re using a path parameter URL, then spaces will have to be encoded with its hex equivalent %20. Using the RFC3986 standard encoding is generally the safer bet since it is the most accepted and newest.

Logging (we’re not talking cutting down trees)

We also highly recommend implementing some code that will log the requests and responses that our services provide. For the sake of customer privacy, we do not log information on our end. Logging can be a big help when troubleshooting your code. It can also be a big help to us if you ever need technical support. Since we do not log customer requests, it is very helpful for us to have the exact inputs or URL used when contacting our services. This will allow us to provide the stellar customer support that comes with integrating with a Service Objects’ API. If you do run into any issues, please send us your request and response as this will help us get to the bottom of whatever issue you are encountering as quickly as possible.

Null or Nothing Strings
Our output structure for most of our services is consistent and won’t change without notice.  For the most part, our structure will stay the same and we’ll return the elements in our output structure as blank strings as opposed to null objects. That being said, we still highly recommend that your application performs null checks before using the response or any of the nested elements from our service. Even though the output structure for our services is very consistent, appropriately null checking our response can save you and your application a lot of headaches if something unexpected occurs.

URLs, IP Addresses and Whitelisting
Some clients or prospects will ask us if they can access our web services by IP address or whitelist the IP address in their firewall. Well, you certainly can, but we highly recommend whitelisting or hitting our web service by the domain URL. Most modern firewalls will support whitelisting domains by names and we highly recommend utilizing this. The reason being that IP addresses can and will change. We have a lot of backups and redundancy set up in our web services that will go unnoticed if you are accessing the service via a domain. If you absolutely need to hit our service by IP address or whitelist them like that, please reach out to our support team and we will be happy to make recommendations on best practices and provide you the information you will need.

Use Cases
If you are curious to know if you are understanding the results correctly or want to know if you are using the right operation to get the functionality you want, our developer guides can help provide more clarity about certain inputs and outputs from the service of choice.

As discussed, integrating with any API can bring up a lot of questions. If this list didn’t cover your questions or particular use case, please feel free to send your requests or questions to and we will be happy to help you get up and running with any of our 24 data validation APIs.

What Does API Really Mean?

API stands for Application Program Interface. It is a way for software to communicate with each other based on specific inputs and outputs. API’s are everywhere, nearly any application in existence can use them. One API can even utilize one or more other API’s as well. What an API is has been defined and explained in any number of Google search results. What I want to talk about is what an API really is.

It is a way to reuse existing code. Writing reusable code is often a high consideration when developers write code. If you are going to need a specific functionality over and over again, why recreate the wheel? Well, that is just what APIs help developers avoid, as well as making code more understandable and enabling them to be more productive, resulting in saved time and money.

The interchangeable nature of API’s makes switching one API out for another relatively simple. The cost of improving complex segments of code is almost as simple as unplugging a broken toaster and plugging in a new one.

The beauty of APIs is that they allow your organization’s developers to do what they do best. They don’t need to be an expert in everything. Often organizations can be sent on wild goose chases trying to figure out solutions that they are not experts in. At Service Objects, we want your business to continue being an expert at what you do and let us be your expert in the field of contact validation. Why attempt to do the heavy lifting of trying to solve a problem that is not in your wheel house? Without spending an enormous amount of time and money, there is little chance that you will be able to reproduce the code that another API can give you out of the box.

At Service Objects, we have been developing our services since 2001, so when someone is purchasing any of our 23 APIs, they are using over 16 years of cumulative knowledge and expertise. And on top of that, we are going to keep learning and improving on our services so that our customers don’t have to. What this means is that your organization can be using the best code available in your applications and leverage the best practices we have developed without being an expert in the field of data validation.

For more information, or to obtain a free trial key for any of Service Objects’ Data Validation APIs, click here.

C# Integration Tutorial Using DOTS Email Validation

Watch this video and hear Service Objects’ Application Engineer, Dylan, as he presents a 22 minute step-by-step tutorial on how to integrate an API using C#. In order to participate in this tutorial, you will need the following :

  1. A basic knowledge of C# and object-oriented programming.
  2. Visual Studio or some other IDE.

Any DOTS Validation Product Key. You can get free trial keys at

In this tutorial, we have selected the DOTS Email Validation web service.  This service performs real-time checks on email addresses to determine if they are genuine, accurate and up-to-date. The service performs over 50 tests on an email address to determine whether or not it can receive email.  If you are interested in a different service, you can still follow along in this tutorial with your service of choice. The process will be the same, but the outputs, inputs, and objects that we’ll be dealing with in the integration video will be slightly modified.


Demonstrating JavaScript and NuGet with DOTS Address Validation 3

In this demonstration I am going to show you how to implement our DOTS Address Validation 3 web service with JavaScript and no Asp.Net markup tags using Visual Studio. We are going to create a form for address inputs, similar to what you would see on a checkout page, which will call our API to validate the address. Although, we could call the web service directly from JavaScript, we would then be forced to expose our license key. So we will use an aspx.cs page to handle our call to the service API, keeping our license key safe from prying eyes. In this demonstration, I will also show you how to add the NuGet version of DOTS Address Validation 3 to the project so that you are always using our best practices and speeding up your integration.

First, create a new empty web site, which I am going to call, cSharpJavascriptAjax. Then I am going to add a new html page called, Addressvalidation.html.

Next, we are going to add the markup for the form. Add the following code in between the body tag.

This form was designed using the table structure for the layout. You will likely want to create the layout using divs, which is more appropriate. Here is what the page looks like in the browser.

To speed things up a bit, I am going to include jQuery in the header so we can utilize some of the short cut functions. Of course, all of this can be done in pure JavaScript.

For the action we will take when the Complete button is clicked, we will create the submit function. This will take in all the values from the form, call the web service and then display the response to the screen. I added an alert and left the URL blank, this will allow for a quick test to make sure what we have is working. Later we will update the failure and success sections as well. For now, they will simply display an alert for testing.

First, let’s start by making sure we are getting all the inputs into the submit function and are getting all the inputs back. I am going to display an alert with DataValue variable so we can see what we have.

Good, now that we know that is working, we will need to make the call to the web service. Like I mentioned before, we could call the service directly but using JavaScript would make the license key visible. So we are going to leverage for security by creating and empty aspx page and add a method to the aspx.cs page to handle the call. Let’s go ahead and add the aspx/aspx.cs page to the project and call it, ServiceObjectsAPIHandler.

Here is our empty aspx.cs page, where we will be adding our function. It will go below the Page_Load method.

Let’s call the method, CallDOTSAddressValidation3_GBM. There are two things to notice with the signature for this method. We decorate the method with the WebMethod attribute so that our new method can be exposed as a web service method. And, we declare it as static because of the stateless nature of the static methods. An instance of a class does not need to be declared.

To test things out, for now we will just take one string input and return it to the Ajax call where we will display it. In order to do this, we will need to adjust our DataValue call in the script on the html page.

We will also need to add the URL and method to the Ajax call.

I also adjusted the alerts so we can see the success or fail.

Great! That worked! Now, let’s write up the code in the aspx.cs page to make the call to the service. We could grab some sample code from the web site and walk through it, but we have documentation and tutorials already on how to do that. Instead, I am going to take a short cut and grab what I need from NuGet. We offer NuGet packages for most of our services, which include best practices such as failover configurations and speeding up the integration time.

To do this, we will need to open up the NuGet Package Manager in Visual Studio under the Tools menu option. When browsing for our services, you can type “Serviceobjects”. You should see a list of available Service Objects NuGet packages to choose from.

Select DOTSAddressValidation3US, you will be prompted to select the project you want to install it under. Select the project and then click install.

Once the installation is complete, a ReadMe file will automatically open that will contain a lot of information about the service. You will also notice a few things were added to your project. First, a DLL for DOTSAddressValidation3US was added to the bin folder and was referenced in your project.

Next, an AV3LicenseKey app setting was added to your web.config file with the value “WSXX-XXXX-XXXX”. You will need to substitute this value for the key you received from Service Objects.

Also in the web.config you will see several endpoints were added. These will be used in the pre-packaged code to determine how to call the service based on your key.

Now that we have the NuGet package added to the project, we can use it. Next is the code that will use the DOTSAddressValidation3US DLL by loading it up with the input parameters, making the call to the service, then working with the response and finally sending the data back out to our JavaScript.

First we get the license key from the web configs file.

Then we make the call to the service. You will notice that we throw in a Boolean parameter at the end of the call to GetBestMatches for live or trial. This is an indicator that will tell the underlying process which endpoints to use. A mismatch between your license key and this Boolean flag will cause the call to the service to fail.

After we make the call to the service, we will process the response and send the data back to the JavaScript. If there is an error, we will return the error details. Otherwise, we will return a serialized version of the response object. Note that you can also just deal with the response completely here or completely in JavaScript. I mixed it up so you can see a bit of both.

Now we will turn our attention back to the JavaScript and update our submit function. All we really have to deal with now is the response from the aspx method call. Here is the portion of the Ajax call implementing that.

Success or failure here does not mean that the address is good or not. It is really just a success or failure of the call to the aspx web method. On failure, we simply make an alert stating something went wrong. On success, we examine the response value, determine if the address was good or not and display the appropriate response. Here is the whole submit function.


Here is a good address.


And here is a bad address.


In the submit function, we did the most basic check to see if an address was good or not.

But many more data points from the response can be used to make any number of conclusions about an address. One thing you will notice is that AddressResponse.Addresses is an array. A check to see if multiple addresses are returned can be valuable because in certain situations more than one address may be returned. One example is when an East and a West street address are equally valid responses to an input address. In this case you may want to display both addresses and let the user determine which to use. You may want to evaluate the individual address fragments or the corrections that were made to the address.

The data points associated to the DOTS Address Validation US 3 service can be found on our development guide page for the service.

The following is commented out code that I added to the submit method for easy access to the various output data points.

And here is the same thing but for the Error object in the aspx page.

I hope this walk-thru was helpful in demonstrating how to implement our DOTS Address Validation 3 web service with JavaScript and no Asp.Net markup tags using Visual Studio. If you have any question, please feel free to contact Service Objects for support.

Service Objects is the industry leader in real-time contact validation services.

Service Objects has verified over 2.8 billion contact records for clients from various industries including retail, technology, government, communications, leisure, utilities, and finance. Since 2001, thousands of businesses and developers have used our APIs to validate transactions to reduce fraud, increase conversions, and enhance incoming leads, Web orders, and customer lists. READ MORE