In case you missed it, we recently released a new operation in our DOTS Address Validation 3 US web service. It’s called GetSecondaryNumbers, and we’re excited about how it can help our clients and their customers ensure that mail gets delivered to where it needs to be.
Provide a smooth checkout and delivery experience
GetSecondaryNumbers is able to take an address that is missing a valid secondary number (such as apartment, suite, floor, etc.) and spit out all the valid options for secondary numbers. One of the primary reasons we made this operation is to help some of our e-commerce customers provide a smooth checkout experience when an address is missing a valid apartment number.
In this article, we wanted to highlight the process of using this new operation in conjunction with our recommended operation for the service, GetBestMatches. In this tutorial we’ll be using C# as our language of choice, but the logic described here can be easily adapted to fit whatever your development language may be.
We will start out by assuming that we have a pretty simple checkout form that looks something like the following image:
In a typical scenario, the address would get sent to our services for validation. But what happens if the address is missing the unit number? Let’s take a look at our own office address (minus the proper suite number) as an example.
Let’s assume that our user would hit the “continue” button following this input, and then we can proceed to the backend to figure out how to use GetSecondaryNumbers.
To start, we will clean up the address inputs to remove any trailing white spaces, and then we’ll send them to the recommended operation for our services, GetBestMatches. To call our services in this case, we will use the C# class library we developed that utilizes our recommended best practices. If you would like to know more, I’d recommend reading up on them and/or heading to our sample code page to download them.
Next, we will check to see if an error was present in the response object. If it was, then you will want to relay the address information to the user, or whatever your preferred choice of dealing with the invalid addresses may be.
We will hide our address input information on the front end where the user entered the information, and then we will implement some checking and logic for each of the DPV codes that get returned from our service.
A quick refresher on DPV Codes
Since we’re interested in DPV codes 3 and 4, we’ll skip going into the logic for codes 1 and 2, but here are some general recommendations for how to deal with the first two codes:
- DPV 1 – Your client’s address is good to go! Feel free to proceed as expected with the checkout process.
- DPV 2 – Your client’s address is not a valid mailing address per the USPS. This might be a case where you can check an additional shipping service (such as FedEx, UPS, etc.) to see if they might deliver to this address.
Now let’s take a look on how we’ll call the GetSecondaryAddress call if a DPV of either 3 or 4 is returned.
In this case, we will take the validated address information that was returned from our GetBestMatches operation and run it through the GetSecondaryNumbers operation. If this operation returned a successful response, it would have a list of potential unit numbers for this address. In this case we will make a list of radio buttons visible on the user input form, and set the data source for that list of radio buttons as the list that came back from the GetSecondaryNumbers operation. For reference, here is what the front end looks like for the list of check boxes we are adding:
Note: we added “N/A” as a possible option in this example. Depending on how much you want to trust the input of your customers, you may or may not want to have this as an option. For example, if you are dealing primarily with businesses that receive a lot of mail and are adamant that their address doesn’t have a unit number, then it may be safe to omit one.
Deliverability ultimately depends on the mail carrier making the actual delivery, and they can often make an educated decision about where a particular piece of mail is supposed to go based on its name and address. If you have questions about the specifics of your implementation, let us know and we’d be happy to help make a recommendation that would best meet your need.
Now let’s go ahead and see what this would look like for a user of the form for our example address:
The user will then make a selection, and on the back end of the page this unit number can get appended to the validated input address. Note, if you want to include “N/A” as an option, you will likely want to include a check for this on the back end and leave the address as is.
What happens if your address receives a DPV 3 score?
Another thing to be aware of is that if your address received a DPV 3, that means there is an invalid unit number attached to it. If this is the case, you may want to remove that unit number before appending a valid one. This can be done with some similar logic, as shown below. This will replace the secondary unit text with a blank string.
After the user makes a selection for the proper unit number, we have a couple of options. We can either resubmit it to the GetBestMatches operation, or simply append the unit number to the existing validated address line. If you are leveraging fields like BarcodeDigits in our service, then you may want to resubmit for validation, as that value would change with the new valid suite number. If you are simply looking for the standardized deliverable address, then you can simply build out the new address line with the newly picked suite number. This is what we’ll do in the image below, as we display the full address with the new suite number back to the user.
And that’s it! You can certainly adapt your own logic and use case to the basic logic mentioned above. But please reach out to our support team if you have any questions on how to implement this. We’re always happy to help make recommendations on how to integrate our services.
