Thinking about moving from AV3 to AV4? Here’s why it’s worth it. AV4 introduces an OpenAPI Specification, a major upgrade from AV3. This means you’ll save significant development time, as AV4 can automatically generate client libraries, models, and serialization/deserialization code—making your applications easier to develop and maintain.
AV4 also delivers more precise address validation, with additional resolution levels by using the latest USPS data, curated datasets, and advanced validation techniques.
In AV3, the lack of an OpenAPI specification required developers to manually create classes for response objects and handle JSON/XML parsing—an error-prone and time-consuming process, especially when API structures changed. Now, with AV4’s OpenAPI Specification, you can use tools like Connected Services in Visual Studio to automatically generate the required classes and methods. This automation makes development faster, more efficient, and keeps your code up-to-date effortlessly. Here’s how AV4 can streamline your workflow:Step-by-Step Guide to Upgrading from AV3 to AV4
1. Prepare Your Development Environment
Ensure you have the latest version of Visual Studio installed because it provides up to date support for Connected Services and OpenAPI.
2. Remove AV3 References
Before integrating AV4, clean up any references to AV3 in your project such as removing any manually created classes related to AV3 response objects, delete any custom serialization/deserialization code used for AV3 and uninstall any NuGet packages specific to AV3. Be sure to preserve code you have around the input you are using for AV3. These will be reused later as inputs for AV4.
3. Add AV4 via Connected Services
Right-click on your project in Solution Explorer. Select “Add” > “Connected Service…”. In the Connected Services dialog, choose “OpenAPI (Swagger) Service”. Enter the AV4 OpenAPI specification URL https://strial.serviceobjects.com/AV4/openapi/v1/AV4.json. Here we are pulling it from our trial site but when going live you’ll want to make sure you have the latest and greatest from https://sws.serviceobjects.com/AV4/openapi/v1/AV4.json. We keep the trial and production endpoints updated and matching each other but best practice would be to use the production version. In the case of failover, sws can be replaced with our failover endpoint swsbackup and that would look like this https://swsbackup.serviceobjects.com/AV4/openapi/v1/AV4.json. After that configure the namespace and other settings as needed, for the namespace I usually just use AV4. Click “Finish” to generate the client code. As mentioned earlier the benefit of using the OpenAPI specification with Connected Services is the automatically generated strongly-typed client classes, simplifies API calls with minimal boilerplate code and it keeps client code up-to-date with the API specification. C# or Visual Studio is not the only technology to take advantage of OpenAPI specifications but also in Java using Eclipse or IntelliJ IDEA and many more.
4. Update Your Code to Use AV4
First create an HttpClient. In C# it is best to use the using construct around creating an HttpClient so that if you are processing many records you do not run into errors caused by open connections. Add the base address to the HttpClient and create an AV4 object. Your code should like similar to this:
This pretty much contains the bulk of what you need to make the call to the API. The part I want to focus on are the inputs to the service because this is where you can reuse the inputs you used for AV3. First though, you’ll want to determine which mode you want to operate in, modes 1, 2 or 3. The recommended mode would be mode 3 where you not only get the latest and greatest in terms of data sets and underlying algorithms but you also get to take advantage of additional input values if you have them such as the phone number and or name of the person at the address you are trying to validate. Using the inputs can help with messy addresses or hard to find addresses. Mode 1, however, most close works like AV3 but with additional algorithm updates and data. So, determine the mode you want to operate in and set that as the first variable. You could also use any mode at any time if your data doesn’t conform one way or another. From there supply the inputs you used to call AV3 next. After that the API takes in name values, phone number, options and the license key called AuthID. Options and FullName are two fields that are not yet in use but will be utilized in a future update. As for the AuthID, store that value the same way you stored your AV3 license key. It is recommended to put the AuthID in a config file or another storage location that does not compromise it to the outside world. Another thing to point out is that we are using the await decorator which will stop execution for the method until the operation completes. But what it also does is that it returns an API Exception containing the ProblemDetails object when an error occurs. Without the await operate the ProblemDetails object is wrapped in the AggregateExeption.
5. Update your code to use the AV4 results.
But first, if there were any exceptions in the call to the API you’ll want to catch them in try/catch blocks.
Here is where I suggest you inspect the error and determine if a failover call is needed. We highly encourage our clients to implement failover to help ensure five 9’s of up-time. This is what you’ll be replacing from AV3 if you already were implementing failover:
So now we’ll be getting the values back out of the ValidateAddressResponse object that holds the results of the address validation. Here’s where things start to change a lot with the two services. With AV3 you really just needed to identify if you had an error response and if not what the DPV score was to determine how the address validated. AV4 is different. When the response comes back, you’ll need to take a look at the status and if that is OK then you’ll start digging deeper. For reference, this is what part of the payload looks like:
Just because status say OK, doesn’t mean you’re good to go and you have a validated address. In this case we but not because of the status. Here are a couple of things to consider. Addresses is an array meaning more then one address can be returned, just like AV3, meaning when an address cannot fully be validated you can get multiple addresses come back. The top address is usually the best address but it does not necessarily need to be the case. The value you want to inspect for address validation being good is the validationType field. AddressGood means the address validated and judging by the addressNotes with DPV 1, that address validated and is good. To learn more about how the various fields can be used please read through this blog [Jonas’ deep dive blog for AV4]. ValidationType can vary depending on the level the address matched at. If the address didn’t match except at the city/state/ZIP level then a different valiationType would be returned.
In the case of moving from AV3 to AV4, to access the fields you needed in AV3 you’ll want to capture the address of the index that corresponds to the address you want to use and then grab the fields you need. Hopefully with AV3 you were already saving all the data we returned to you from the API, saving this data from AV4 is equally important. The address data points can be pulled in from the response object like this, for example:
Here, you’ll just want to make sure you map your existing AV3 output variables to the corresponding AV4 output variables. Once you have that set you should be back online with AV4.
