Posts Tagged ‘API Development’

US Address Validation Use Cases

Why do people use our DOTS Address Validation – US product? There are many reasons to choose our service that really depends on your business or project. At the highest level, our clients have a goal of gaining efficiency in their systems and want to reduce waste, fraud, and abuse. The next question becomes, how are we going to create efficiencies in our client’s systems?

The primary solutions Service Objects’ real-time APIs offer typically fall into one of these general use case categories: preventing lost deliveries, eliminating waste and fraud, standardizing for compliance, gaining insights into customers and prospects and optimizing marketing automation. These categories are relevant to the majority of our APIs, however, this blog will focus on Address Validation – US and give examples of how this service can be your solution.

Preventing lost deliveries (and delivering more)

Address Validation – US can help with lost deliveries, and in turn allow for the successful completion of more deliveries, by guaranteeing accurate validated addresses. We do this with our CASS certified address validation engine which employs the culmination of 20 years of experience. We make sure addresses exist and are complete by fixing addresses and returning codes that give you additional details and visibility into the addresses at hand.

For example, besides just telling you what was fixed, or telling you what address component is missing, we will provide insights into the address and let you know if it was found to be vacant, returning mail, general delivery, rural route or highway contract and many more, which you can find in our developer guides.

With this information, your organization can make smart decisions on how to handle addresses and reduce the costs of delivering, re-delivering, handling, lost materials, materials sent to the wrong addresses and the cost of damaging your reputation.

Eliminating fraud

Fraud can manifest itself in many ways, and it is always important to keep in touch with new ways that this kind of abuse is attempted. There are several ways Address Validation – US will help eliminate fraud.

Some fraud is attempted by creating duplicate orders in an effort to either get free samples or try to get multiple orders of something and in turn try to resell them. The people behind these efforts will try to circumvent processes by entering their data into a system multiple times, each time entering the data slightly differently. These differences may include a misspelling on purpose such as using ‘Summerland’ and ‘Summer Land’ for the city, or entering the wrong street suffix such as ‘ST’ instead of ‘RD,’ or using both in separate instances. The changes or variations are usually small enough to create multiple different addresses that end up being, in fact, the same address.

Sometimes deliveries are made to multiple forms of the same address. Alias street names can be completely different even though they are the same street, for example, Highway 28 and Allen Street are the same street. Whatever the address inputs were, if the underlying address is actually the same, we can identify these duplicates in two ways. First, we return a standardized address that eliminates the variation in addresses, and second, we return a barcode digit unique to the address that can also be used for de-duplication.

Besides altering addresses to get multiple deliveries, fraud can come into play when someone has stolen purchasing details and needs to receive the delivery of a fraudulent order at another location. In some cases, the perpetrator will use the address of a vacant lot or an address with no delivery and wait for the mail to arrive. With the notes (detailed in our developer guide) that we return in the service, those kinds of details can be identified and flagged for review. In any case, an area found to be problematic or suspicious can be detected and flagged as well.

For instance, if your organization is having trouble with deliveries in certain regions or territories, ensuring the address you have is valid and accurate can help you flag addresses appropriately by getting correct the address, city, county, state, district, building type, delivery type and so on, where leaving these items not validated could lead to potential fraud. The cost savings in making your process less prone to fraud can come in many forms such as saving on delivery, handling materials, producing materials and protecting your organization’s reputation.

Standardizing for compliance

Compliance is a huge issue for most businesses nowadays, and it can be costly to be out of compliance. In recent years, lawmakers in various countries including the US have enacted compliance laws with respect to the gathering, handling, and storage of personal information. Not being in compliance with these new regulations can have a huge impact on your organization in terms of financial penalties and reputation damage.

When a request is made to purge personal information, organizations need to be able to identify all of the personal data connected to this individual and be able to purge it with certainty. One way we can help is by making sure the data you have on an individual is valid, accurate and standardized. In this situation, all three of these are equally important.

Take standardization as an example, if the same address is entered into your system with several different variations when it comes time to purge the data some of the data may be missed based on differences in the address. These variations can come from typos on forms, a call center technician misinterpreting information conveyed over the phone, or even data digitized through processes such as OCR that scan hard copy documents to digitize them for processing by computer systems.

Our Address Validation – US product helps solve these problems. First, it performs the address validation so that you can be sure that the address you have is valid and accurate. Second, it standardizes the address so that organizations can rely on consistency, and they can use our barcode digits to identify duplicate addresses even when the original addresses had variations to them. (Of course, various people can live at a single address, so care has to be taken in properly identifying, individuals at an address and making sure the wrong records are not being purged.)

Our address validation service is a huge step in untangling this problem, but we should also point out that we have other validation services, To untangle data points even further our DOTS GeoPhone Plus service and others can help. The costs associated with being in compliance are minuscule to what they can be when dealing with litigation, data handling, and reputation issues.

Gaining insights into customers and prospects

Gaining insights into your customers and prospects from your data and having a more complete picture of your leads can give you many strategic advantages. As an example, imagine being on the phone with an engaged prospect, trying to relate to them by telling them about an experience you had in their home town, just to hear them say “I’m not sure what you’re talking about, I’m not from there.” That’s embarrassing! Getting this wrong can make you look contrived.

We can increase confidence when you are reaching out to contacts with valid accurate data, but we are also giving you an opportunity to hone in and paint a better, more complete picture. What congressional district they are in can give you insights into potential political leanings. Is their address residential? Is it a rural address? Do they live in an apartment? Is it a military address? We address these kinds of questions and help shape the relationships and outreach organizations have with their contacts. Moreover, delivery strategies can be tailored to be more efficient. For instance, depending on the insights provided, deliveries can be distributed to the appropriate delivery team or person, scheduled for the right times and/or charged the proper amount.

Having a complete picture allows you to be able to not only distribute leads accurately to the right teams but also allows you to create unique territories that in turn match your strengths as a sales team. Leads can be distributed loosely or tightly. The human resource cost in handling leads and gaining insights into your customers and prospects can be tremendous, as are the costs in trying to correct the data manually. Service Objects is here to help you out with greatly reducing that burden.

Optimizing marketing automation

Just as creating smart sales territories are important for lead distribution, they are just as important in marketing territories. When distributing marketing materials, it can be important that they are tailored and are sensitive to the target audience and location. It is also important to deliver materials to addresses that exist so that you can reach as many people as possible, and make your campaign a success with a minimum of waste. Employing Address Validation – US as part of your solution can help minimize costs such as human resources, corrections, time, and delivery and re-delivery, as well as the implied costs to your reputation.

This is far from an all-inclusive list of use case categories. We have 23 other validation services besides Address Validation – US. Just imagine the possibilities when you pair this service with our other validation and data enrichment services like:

Depending on your organization, one or more of these can be part of your solution in gaining maximum efficiency and reducing waste, fraud and abuse.

API Integration: How Much Time to Set Aside

The question of ”how long does it take for someone to integrate your API?’ has come up a lot lately in various situations. In this article, I wanted to paint a better picture of what that looks like.

There are a mix of factors that should be considered for your integration, including available resources, what solution you are plugging the API into, and whether you have someone who can do the work of the integration. For example, where you want to plug in our API will have a direct impact on the resources you are going to need when integrating. Do you need someone who knows Java or .net, or do you need someone familiar with Salesforce or Marketo?

If you need to integrate an API into code, then you or your resources should have at least a familiarity of the programming language currently deployed in your solution. However, if you need to inject our API into a platform such as Salesforce or Marketo, then you may be looking at perhaps a marketing technologist or more admin skill level person that can handle more of a plug and play scenario that involves adjusting settings.

Depending on what you are integrating with, there are three main types of personas you can group people into, each of which require different amounts of time and assistance in getting an integration project done. In any case, however, these people will all need to have a good degree of knowledge about the surrounding process and business rules that will need to be implemented.

Let’s look at each of these three groups:

Group 1: The super knowledgeable

This person has done this before many times over and is going to need little help with the integration. They may just want to look at our development guide so they can see the endpoints they need to hook up to and the format and field names coming back from the web service API. For setting up the call to the API, this person is going to need little more than 20 minutes.

Group 2: Strong coder or strong platform admin

This person doesn’t call APIs that often, but has done it before. In this category the person will be integrating into code, plugging into a platform, or both. They will have a few questions about the API and may request a guide or overview to help them with integrating into a platform. We have materials that will help with both code and plugging into many platforms which they will want to look through. This person is going to need closer to a couple of hours to get our API integrated into their system.

Group 3: Relatively new to coding or platform administration

This person has never really dealt with APIs before. This situation is more of a grey area because it depends on how hands-on the person is. These people will generally need more guidance and may even need professional services to accomplish the job. The time it will take in this category will depend on this person’s inclination to learn something new.

We have many resources to help show someone like this how to integrate our services, and this will make the process much smoother. For example, we have sample code for web forms that can be dropped into several scenarios and can also be repurposed to fit most applications. Someone with very little experience calling web APIs should be able to navigate our documentation and get rolling in a day.

Customizing these estimates to your situation

There will certainly be other groups beyond the categories I have simplified here. So, if you find that you don’t fit into one of these specifically, you can still use them as a guide for evaluating the time it will generally take to integrate our API services. As you can see, the amount of time involved is typically very short.

Another part of the integration, not to be forgotten, is more about implementing your business logic and what you do with your data before you send it to our API for validation, as well as when the results come back.

We can give you recommendations and best practices based on what we have seen in the industry as to how certain situations are typically handled, so you can have a good idea for how to set up your solution. The time it takes to do this end of the implementation is a lot more variable and is based on the complexities of what solution(s) you are trying to achieve. We here to work through the process with you by providing our cutting-edge solutions along with our recommendations.

How we can help

Here is a link to a search of our blogs that will display various documents on integration along with several tutorials. If you can’t find something you need, let us know and we’ll do our best to put it together. Along with this, I have additional links to our developer guides, sample code and quick look-ups. We work to make every integration as smooth as possible and will go a long way to help, including offering our professional services to get you across the finish line. Let us know what we can do to help make your implementation a success.

Swagger/Open API Added to Developer’s Guides

If you have poked around our Developer’s Guides recently, you may have noticed some changes and upgrades. We have introduced some stylistic changes that make these guides easier on the eye, but we’re also really excited about some changes that make it a breeze for developers to get up and running with our APIs and become their own data validation experts in no time! Specifically, we have integrated an Open API/Swagger specification form directly into these Developer’s Guides.

Open API/Swagger

If you are not familiar with Open API/Swagger, you should be! Open API provides a standardized framework that allows API developers to describe and outline the behavior of their API in a machine-readable way. From this description, Open API can then provide a user interface that allows other developers to quickly and efficiently determine how an API is expected to perform. It even allows users to quickly test example inputs to the API to see how it responds.

This user interface and the information it offers allows developers to easily and quickly integrate our APIs into their applications. This enables developers to have our APIs up and running in their applications in no time.

‘Try the API’ and ‘Service Reference’

Each of our Developer’s Guides will have two new nested pages. The one with the title “Try The API” will have our recommended operation for each service, and the “Service Reference” page will list all of the operations and methods available for each service. For 99% of use cases, we recommend using the operation listed in the “Try The API” page, as it generally meets the needs of our customers’ most common scenarios.

However, depending on the service used, there may be cases where other operations may suit your needs better. This is where the Service Reference page comes into play, with a list of the additional operations available for the service you are interested in.

Check out examples of both on our Address Validation – US Developer Guide:

Try the API:

Service Reference:

Note: If you don’t see these pages in your service of choice, don’t worry: we are rolling out updates to Developer’s Guide pages daily. And if you need something right away, please contact us and we can create something for you quickly.

The API Economy: What Does it Mean for You?

The 2010s have been the decade of the fill-in-the-blank economy: for example, the gig economy (where people are increasingly contractors instead of employees), the sharing economy (where Uber and AirBnB put you in other people’s cars and homes), and even the hipster economy (don’t ask). Lately we can add a new one to the list: the API economy.

Many of you reading this already know what an API is – but just in case, it stands for Application Programming Interface. Its formal definition from Wikipedia is “a set of subroutine definitions, communication protocols, and tools for building software … a set of clearly defined methods of communication among various components.”

In plain English, APIs are interfaces linking your software and data to other people’s software and data. In this blog, we are going to look at why they have become so important – and more importantly, what they can do for you.

The impact of APIs

Why are APIs being seen as an economic phenomenon? Because they are dramatically changing the way software is being produced – and more importantly, how it is consumed.

First, APIs dramatically extend the reach and capabilities of your software environment. Here at Service Objects, for example, we can put the entire United States Post Office into the address entry fields of your marketing automation software to validate and complete addresses – or even fix ones that are horribly wrong. We can link your prospects or customers to US Census data for demographic analyses. We can tell you which email addresses in your contact list are known spam traps. And much more.

Second, APIs are fueling the next generation of inexpensive, cloud-based computing. Remember the days when implementing tools such as CRM and ERP required months of planning, and seemingly a cast of thousands? For many businesses, those days eventually gave way to easy-to-install browser-based applications with their own user interfaces. Today, the next step has often been towards “headless” capabilities: specific web services with no UI that can be easily plugged into your own business computing environment via APIs.

The other key benefit of APIs is that they are upgradeable component technology. At Service Objects, we are constantly adding new capabilities to our services, with no change in programming required from our users on the front end. This flexibility and ability to evolve quickly has changed the game for business applications today.

Putting APIs to work for you

Most Service Objects’ services are designed to plug in to your applications environment, including marketing and sales force automation platforms and CRMs. We also offer other options, ranging from batch list processing to a PC desktop app and done-for-you data cleaning services, but we are first and foremost an API company – and we devote a lot of our efforts to API resources and ease of integration, so you can seamlessly put these services to work in your platform.

This starts with an architecture that is designed API-first, beginning with our request and response interfaces. We support REST, SOAP, GET and POST requests over HTTP/S outputting in JSON and XML formats.

For example, here is a sample web URL request from our flagship DOTS Address Validation – US 3 service, together with the response fields returned in JSON.

API compatibility

Our API web services are compatible with all major programming languages, including Java, PHP, Ruby on Rails, C#, Python, and much more. To help developers integrate our services quickly, we have extensive documentation along with over 200 pieces of sample code to help with your integration. We are developers ourselves, and we live and breathe API integration. And we are always more than happy to help your implementation go smoothly or troubleshoot issues, with an industry-leading support team that is always on call.

Where we are headed

According to IBM, “’API Economy’ is a general term related to the use of ‘business APIs’ to positively affect the company.“ This is truly the rationale for the growth of APIs, particularly economic benefits such as lower development costs and greater capabilities. And at a deeper level, it speaks to how software capabilities are increasingly becoming component parts of streamlined platforms.

Nowadays the label “API Economy” is far from an overstatement, with the use of APIs growing more than 10,000% over the last decade. We are always working hard to stay ahead of the curve and bring more and more data quality capabilities that can be easily integrated into your business platforms.

To try out any of our 24 data validation APIs, visit our web site to request your free trial key.

Hand manipulating gears

Choosing a Web API: REST, Remote Procedural Call or Hybrid

REST is a popular architectural style that has been the go-to design for web-based APIs for years. The style has defining constraints, but it is not a protocol and there is no official standard. REST is like the pirate’s code in the Pirates of the Caribbean movie franchise, in that REST “is more what you would call guidelines than actual rules.” As such, not everyone follows the guidelines exactly or interprets them the same way.

This can lead to some confusion and debate as to what is and is not considered RESTful. At the same time, one can look at this flexibility as an opportunity to pick and choose what will work best for their needs. In this article, we briefly discuss some web API design options and explore some of their strengths and shortcomings.

What REST is – and isn’t

For some, REST simply means using a service that is not SOAP. SOAP is another widely used protocol, but some stay away from it due to its complexity and the extra overhead that it requires. You would be hard pressed to find a REST-related article where SOAP is not mentioned. You will likely find comments about how great REST is because REST uses JSON and SOAP uses XML.

People often mistakenly think that REST is defined by the JSON language format, and when they say they want a RESTful service what they really mean is they want a service that supports JSON. REST is not as simple as that, and it is not confined to any one language format: it is an architectural style and not a specific protocol. Conversely, JSON is not exclusive to REST, as JSON is also available in Remote Procedural Call (RPC) APIs.

So, with that out of the way, the rest of this article will assume that the reader is familiar with the general style of REST. If you wish to learn about REST in more detail then feel free to read the dissertation it was based on – or if you’re not into heavy reading, check out the REST wiki.

Comparing three web API options

Now, let’s look at three different approaches you can use for web APIs:

  • REST – Representational State Transfer (REST) web APIs are “resource” oriented. RESTful APIs synergize well with CRUD applications and other forms of data resource management and manipulation.
  • RPC – Remote Procedural Call (RPC) web APIs are “action” oriented. They enable the user to call a remote method to complete an action as though it were local. This is similar to importing and using the methods from a local library API.
  • Hybrid – Hybrid designed web APIs incorporate both the RESTful style and RPC-based design methods. Some RESTful APIs will include RPC design to add action methods where strictly RESTful resource-oriented methods are not appropriate.

Since REST is resource oriented it is also useful for resource discovery. For example, if a Service Objects client was interested in all the cities or ZIP codes for a state then a RESTful API for discovering those resources and drilling into them for details would be ideal. This approach will also work well for suggestion and IntelliSense applications where several queries to find an address would be acceptable.

By comparison, users looking for address validation could find that having to make several queries would be cumbersome – especially if their data is incomplete or partially invalid. Most of our users do not always have complete data, and lean on us heavily to parse through and correct any garbage or mistakes to fill in the gaps and return an intuitive and standardized response.

RESTful example: Address Validation

Let’s briefly explore what creating a RESTful address validation service would look like. We’ll start by coming up with a way for the user to submit an address for validation.

For this exercise, the theoretical service will be hosted on the following domain and path.


Path format: /AddressValidation/{State}/{City}/{ZIP}/{AddressLine1}/{AddressLine2}

The above format lends itself more to address discovery and would be better suited with a /FindAddress path name; however, this application’s primary job is validation and not discovery so let’s continue.

Let’s test the service using the Service Objects office address as an example.

Path example: /AddressValidation/CA/Santa Barbara/93101/27 E. Cota St #500/

Unfortunately, the above example will fail to validate correctly due to the pound/hashtag (#) character. We know that the # symbol is a special URL character and that it is used as a fragment identifier. Commonly referred to as anchor in HTML. Its inclusion means that the URL path is prematurely terminated at the # symbol.

In this case, the API can respond in a few ways. It can return an HTTP Status code of 400 (Bad Request), but that isn’t too helpful to the user. It can also accept the request, but since the service is unable to see anything past the # symbol, the full address will not be validated. This is problematic, not only because the full address is not being validated, but what would be an acceptable response from the service? Validating the address as-is would be misleading to the user, and the service itself is unaware that parts of the address are missing. In the end, for this example, it would be best for the service to return the 400 status code for safety.

Now let’s try a different path format:

Path format: /AddressValidation/{State}/{City}/{ZIP}/{AddressLine1}/{UnitNumber}/{AddressLine2}

Path example: /AddressValidation/CA/Santa Barbara/93101/27 E. Cota St/500/

The above path format and example work, but it requires the user to parse out the apartment number from the address beforehand, and it is still susceptible to malformed requests due to special URL characters.

As we have just demonstrated, the path parameter approach has some shortcomings. More details and examples are available in a past tutorial. Fortunately, REST is not limited to one way of making requests; however, depending on one’s interpretation this is where this service and many others start to deviate from RESTful guidelines.

Foregoing the path parameter approach entirely, we could use query string parameters or POST requests.

Query string example: /AddressValidation?AddressLine1=27 E. Cota St #500&AddressLine2=&City=Santa Barbara&State=CA&PostalCode=93101

In the above example, the query string parameters can be URL encoded, and there is no fear that the full address will not be passed in. There is also the option to use POST, but using POST instead of GET to read a resource is generally not done as it goes against REST guidelines. However, it is not uncommon to see many services use POST in ways outside of the REST guidelines.

For presentation sake, let’s continue with our example using POST and JSON.

JSON POST request: 

A strictly RESTful response would be as simple as an HTTP 200 status code with a response like this:

If we provided an invalid address, for example by changing the suite number from 500 to 5,000 which does not exist, the RESTful response would then potentially return an HTTP status code of 404 with an output of:

The above output examples are too simplistic and not informative enough. The service could return a status description of “Address Not Found”, but the user is still left with very little information to work with. Our users rely on our services to not just validate their data but to also help inform them on how to proceed with using their data.

Following the RESTful style guidelines, the output could also contain an Address ID that can be used to reference the address and list details for it.

This RESTful style is not quite user friendly in that it requires the user to perform two queries: one to verify the address, and another to retrieve details for it. A big part of the problem stems from REST being “resource” oriented whereas Validation and Verification services are “action” oriented; therefore, lending themselves more towards the RPC-based design.

That’s not to say that the RESTful service cannot be made more user friendly. A hybrid approach can be taken, and the service could be expanded to be more informative by adding parameters to retrieve additional data so that only one request query is needed.


However, using an RPC-based design and forcing it to try and conform to the RESTful style doesn’t necessarily lead to a better user experience.

Why flexibility is important

REST, RPC and hybrid designs each have their own merits and uses. It’s important to choose a design that works best for the given situation. That’s why Service Objects chooses a hybrid approach for our services that leans more toward the RPC-based design, since it suits the action-oriented usage. With validation services there are often many gray areas and edge cases to deal with that work best with custom action-based verb commands.

In a RESTful style, custom verb commands are to be avoided, and some would argue that any use of them would, strictly speaking, not be REST. However, many services do make use of both in a hybrid approach and even Google’s API Design Guide states that , “both RPC APIs and HTTP REST APIs are needed for various reasons, and ideally, an API platform should provide best support for all types of APIs.” So, whether you want to use HTTP GET, POST or SOAP with XML or JSON, the Service Objects DOTS Web Services have you covered.