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.
-
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. |
-
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. |
-
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. |
-
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.
|
| 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.
