Here at Service Objects, we have a team of engineers standing by to help you get the most out of our data validation services. Our goal is to understand your business needs and use the expert knowledge we have gained from over 15 years in the data validation business, to help meet these needs. We provide in-depth developer guides and offer complimentary technical consultation to help your developers leverage our services in the most efficient and productive manner possible. We also want to make sure that you understand the full power and utility of our services and the best ways to integrate them. Understanding how our services work and what they return makes integration simpler and ensures you are using them optimally.
Before we get started, it is important to know that many of our services have multiple operations. These operations have been created to meet different business needs within the services’ overall purpose. For example, DOTS Address Validation 3 has eight different operations, from full address validation and correction to parsing address elements into fragments. At first, it might seem overwhelming to discern which operation is right for your needs, but once the differences are understood, we can choose the best operation to meet them. For our example, we will use the recommended operation, GetBestMatches, for Address Validation 3 as this satisfies most of our customers’ address validation needs. So, let’s dive in.
More inputs = better address verification
Because humans are not perfect, the data coming into the service can vary wildly in terms of format. Address Validation 3 takes these varying inputs, standardizes them, and then verifies the address. It also cross-references the optional input, BusinessName, with the address data provided to return the most accurate result. Address Validation 3 uses either Postal Code or City and State inputs to complete its analysis. Ultimately, the more inputs you can provide, the more cross-referencing can be performed, and the address can be corrected and validated to the highest accuracy possible.
Below are the input fields from our recommended operation, GetBestMatches. Some sections can be understood by their name alone, and others may require reading the description to get a better understanding of what they offer.
GetBestMatches inputs
| Name | Type | Description |
| BusinessName | String | Name of business associated with this address. Used to append Suite data. |
| Address | String | Address line of the address to validate. For example, “123 Main Street”. |
| Address2 | String | This line is for address information that does not contribute to DPV coding an address. For example,”C/O John Smith” does not help validate the address, but is still useful in delivery. |
| City | String | The city of the address to validate. For example, “New York.” The city isn’t required, but if one is not provided, the Zip code is required. |
| State | String | The state of the address to validate. For example, “NY.” This does not need to be contracted; full state names will work as well. The state isn’t required, but if one is not provided, the Zip code is required. |
| PostalCode | String | The zip code of the address to validate. A zip code isn’t required, but if one is not provided, the City and State are required. |
| LicenseKey* | String | Your license key to use the service. Sign up for a free trial key at https://www.serviceobjects.com/address-validation |
Usually, your inputs are largely fixed based on the data you are collecting, but the outputs can vary based on the operation being used. Understanding the outputs available and how you want to use them ensures you are leveraging the service to its fullest extent. Below is a table showing the available output fields from our recommended operation, GetBestMatches. As you will see, some sections can be understood by their Name alone, while others may require further description to better understanding what they return. These descriptions are provided in the Description field.
GetBestMatches outputs
| Name | Type | Values | Description |
| Addresses | Address[] | Varies | The corrected address candidates. |
| IsCASS | String | “true” or “false” | Indicates if the unaltered input address is CASS certified. See “What is CASS?” below for more information. |
| Error | Error | Varies | Error object indicating why the service could not return a result. See “Errors” below for more information. |
Address
| Name | Type | Values | Description |
| Address1 | String | Varies | The corrected address line 1. |
| Address2 | String | Varies | The corrected address line 2. |
| City | String | Varies | The corrected city name. |
| State | String | Varies | The corrected state name. |
| Zip | String | Varies | The corrected zip code + 4. |
| IsResidential | String | “true” or “false” | Indicates if the address is for a residence. |
| DPV* | String | 1-4 | Number that correlates to a DPV (Delivery Point Validation) result. An indicator displaying whether or not the address is recognized as deliverable by the USPS. |
| DPVDesc* | String | Varies | Explains DPV result. |
| DPVNotes* | String | Varies | Number that correlates to DPV notes description. Service Objects may add or change Note descriptions, but will never modify existing codes. |
| DPVNotesDesc* | String | Varies | Details about the DPV result. Service Objects may add or change Note descriptions, but will never modify existing codes. |
| Corrections* | String | Varies | Number that correlates to a Corrections Description. Service Objects may add or change Correction descriptions, but will never modify existing codes. |
| CorrectionsDesc* | String | Varies | Description of what was corrected in an address. Service Objects may add or change Correction descriptions, but will never modify existing codes. |
| BarcodeDigits | String | Varies | The post office delivery barcode digits. |
| CarrierRoute | String | 4 chars | 4 chars: 1 for the route type, 3 for the route code. Identifies a group of addresses when prepended by 5-digit Zip. |
| CongressCode | String | Varies | The congress code is the congressional district number. |
| CountyCode | String | Varies | The county code of the given address. |
| CountyName | String | Varies | The name of the county in which the given address lies. |
| FragmentHouse | String | Varies | The parsed house number of the given address. |
| FragmentPreDir | String | Varies | The parsed pre-directional of the address’s street. “North” in “North Main St West.” |
| FragmentStreet | String | Varies | The parsed name of the street in the given address. “Main” in “North Main St West.” |
| FragmentSuffix | String | Varies | The parsed suffix of the street in the given address. “St” in “North Main St West.” |
| FragmentPostDir | String | Varies | The parsed post-directional of the address’s street. “West” in “North Main St West.” |
| FragmentUnit | String | Varies | The parsed unit type (e.g. “Apt” or “Ste”) |
| Fragment | String | Varies | The parsed “Fragment” box, apartment, or unit number. Same as FragmentPMBNumber. |
| FragmentPMBPrefix | String | Varies | The parsed type of the apartment, box, unit, etc. For example, “APT” or “BOX.” |
| FragmentPMBNumber | String | Varies | The parsed apartment, box, unit, etc. number of the given address. |
Effective address validation begins with painless integration
Integrating your applications with Service Objects should be as painless as possible. Our developer guides show the many different services and operations we offer while providing sample code in most of the major programming languages. And if we don’t have what you need, just ask, it is what we are here for.
Some common questions we see about address validation
Due to the broad nature of our products, the consultations we have with our clients vary depending on need. For beginners, we recommend starting with our online guide, Getting Started with Service Objects. This reference manual includes information about each of our individual services and can help guide you through your Address Validation 3 integration.
While our knowledge extends beyond the FAQ section in our developer guides, the technical questions we receive cover many topics, from 3rd party plugins to concurrency and multi-threaded applications, failover configurations, and response parsing/interpretation.
Below are some questions that we have received while helping clients integrate with our Address Validation 3 service. The inquiries arise from common business requirements and may even help answer questions you have about your integration.
Q: How will I know if an address that is validated is deliverable?
A: Delivery Point Validation (DPV) – The DPV codes are extremely useful in determining the deliverability of your address. They are broken down into four different codes:
| DPV Code | Description |
| 1 | Yes, the input record is a valid mailing address |
| 2 | No, the input record is not in the DPV database of valid mailing addresses |
| 3 | The apartment or rural route box number is not valid, although the house number or rural route is valid |
| 4 | The input record is a valid mailing address but is missing the apartment or rural route box number |
General workflows revolve around accepting address with DPV Code 1s and discarding DPV Code 2s. The DPV Code 1 will indicate that if you sent mail to the address via the United States Postal Service, it would be delivered. DPV Code 2 means the address was deemed not deliverable, and mail would not successfully arrive at that address. DPV Codes 3 and 4 are both indicators that some piece of information was missing on the input, and you will want to create business logic to determine how these cases are handled. For cases like this, we find that many clients will prompt their end user for a corrected house number of apartment/suite/rural route box number, possibly in real-time.
Q: How do I ensure my service requests are successfully processed?
A: Implementing Failover Logic – All of our sample code highlights our recommended best practices and procedures. We show how to code for service outages at our primary data centers, and how to failover to our backup servers. With that said, we guarantee a 99.999% uptime, ensuring the web services are available to you at all times. With proper failover logic in place, failing to get back validated data is a non-issue.
Q: I have validated all of my records, but now I want to remove duplicates. Is there an easy way to do this?
A: BarcodeDigits – This little nugget of gold hiding in plain sight. From a programmer’s point of view, the barcode is a perfect primary key for an address. The barcode digit is a unique identifier for a premise. You can use this field instead of doing difficult string comparisons against individual address fragments.
Q: We do direct mailings to the addresses we collect, but the shipping company places a character limit on the address fields. Can we use the Address Validation 3 service to adhere to the shipping company’s limitation?
A: Fragments – When an address is validated it is also broken up into its component parts. The parts can be used to get around shipping label limitations by piecing back together the address how you need it. For example, an address label could be constructed like the following:
Line 1: FragmentHouse + FragmentPreDir + FragmentStreet + FragmentSuffix + FragmentPostDir
Line 2: FragmentUnit + Fragment + FragmentPMBPrefix + FragmentPMBNumber
Q: I am getting an error back from the service and need help to interpret it. Also, where is my validated address?
A: Errors – Errors come back as their own object in code or parent object in XML/JSON. Digging into the error object fields will help you understand what went wrong with your call to the service, or why your inputs were not valid. If you receive an error object back from the Address Validation 3 service, you can immediately assume that you will not be receiving a validated address. Errors are broken into four categories:
- Authorization – This type of error revolves around an issue with your license key. Sometimes the wrong key is being used for the service, or you may have exhausted your purchased transactions. If this happens, please reach out to our customer care (or call 800.694.6269) team to resolve the issue.
- User Input – These occur when the input data is incorrect. Often, this error happens because a field is missing or a parameter name is misspelled.
- Service Objects Fatal – Very rarely, if ever, will you see this type of error. Chances are we have already been made aware of the issue from our 24/7/365 monitoring services. However, please let us know if you encounter one by sending an email to support@serviceobjects.com. We support our services 24/7/365 and guarantee 99.999% uptime with our financially backed Master Service Level Agreement.
- Domain Specific – This indicates that the service ran to completion, but the data was not valid. Each of the individual errors within the domain-specific category will help you to understand what part of the address was deemed invalid.
These are just a few tips to help you with your integration of Address Validation 3. If you would like further clarification on any of the fields or have questions about how a service will work to fit your needs, please don’t hesitate to reach out to our support team.
