Legacy Standard to Core - Explanation and possible code changes

Smarty Tech Support Team here!

Here is some information to help you when moving from the US Address Verification Legacy Standard to the Core subscription.

First, the only possible code change that you will need to make is to call your new subscription license. You can obtain your new subscription license on the “Subscriptions” page on your Smarty.com account.

In your API call, you will need to add your license value. For most subscriptions, this will be done by adding the following parameter:

license=us-core-cloud

However, some subscriptions may use a different license value. You can find the correct license value on the Subscriptions page of your Smarty Account.

US Address Verification: Core Edition vs. Standard Edition

It’s important to note that the US Core Edition features an improved US Street Address API. The API's matching capabilities have been enhanced so that it can find valid matches for a larger percentage of your input addresses.

There are two ways the US Core Edition finds more matches:

1. The enhanced US Street Address API recognizes 20 million non-USPS addresses.
   Examples of non-USPS addresses are:
   • 115 Timbers Club Ct Snowmass Village CO 81615
   • 1 Bangor St Houlton ME 04730
2. The enhanced US Street Address API handles messier input.
   For example, it finds matches for these input addresses:
   • 3021 3021 I-35 UNIT110 round rock tx 78664 → 3021 S Interstate 35 Ste 110 Round Rock TX 78664-8303
   • 3205 tinbeabrook da charlotte nc → 3205 Timberbrook Dr Charlotte NC 28208-2995
   • 3025 nestrella tucson 85705 → 3025 N Estrella Ave Tucson AZ 85705-5106
   • 19205 6 penny monument co → 19205 Sixpenny Ln Monument CO 80132-2852

Does the enhanced US Street Address API have any new output fields?

Yes. The output from the enhanced US Street Address API is the same as from our original version of the API, except it includes one new output field in the "Analysis" section. The new field is called "enhanced_match." When enhanced matching is used for an address, this output field will contain additional information about the result.

The current possible values found in “enhanced_match” are:

• (blank) — Enhanced matching wasn’t performed. This is only an option that will populate when you are working in strict or invalid match modes and won’t populate otherwise.
• none — Enhanced matching was performed, but no address match was found.
• non-postal-match — Enhanced matching was performed, and a match was found within additional, non-postal address data (data that is not in USPS but is still valid).
• postal-match — Enhanced matching was performed, and a match was found within the postal address data.
• missing-secondary — The address should have a secondary indicator (e.g., apartment number or unit number, etc.), but none was found in the input.
• unknown-secondary — The provided secondary information didn’t match a known secondary indicator within the address data.

How to use the enhanced US Street Address API

There are 2 requirements that you must follow to perform a successful call to the US Street Address API:

1. You must have an active license that includes the enhanced matching capabilities in your account. These include the "US Core License, Cloud Access" and "US Rooftop Geocoding License, Cloud Access."
2. The query string of the HTTP request must include two additional parameters:
   1. license=us-core-cloud (or another valid license as dictated by your subscription)
      AND
   2. match=enhanced (In the case of a POST request, the license parameter still goes in the query string, but the match parameter is submitted with each address in the body of the request)

If you’re currently using match=strict (which is the default setting if you don’t specify a match parameter), and you do want to change to match=enhanced, you will want to implement code changes to handle when an address is invalid. Here’s some generic logic we have put together to help you code for an invalid address when you change from match=strict to match=enhanced.

Here is the suggested logic for interpreting the "Analysis" section of the US Street Address API:

1. Check the dpv_match_code field.
   1. If the value is Y, that means that the address is real and present in the USPS data. To make sure the address is actually deliverable by the USPS, ensure that the dpv_vacant field has a value of N, and make sure there’s NOT a dpv_footnote of R7. The presence of dpv_footnote R7 indicates the address is real, but is NOT considered street deliverable by the USPS.
      What this means is that the recipients at an R7 address typically pick up their mail at the local post office instead of driving the package or mailpiece 50+ miles out of the delivery route.
   2. If the dpv_match_code is D, the address is real and the primary portion of the address is in the USPS data, but according to the USPS, the address is missing an apartment or suite number
      You may want to reach out to the end user and check if they forgot an apartment or suite number.
   3. If the dpv_match_code is S, the address is real and the primary portion of the address is in the USPS data, but the apartment or suite number that was submitted isn’t recognized by the USPS. You will want to check the dpv_footnotes to find out if an apartment or suite number is necessary for USPS delivery. If you see “dpv_footnote” CC, an apartment or suite number isn’t needed, and the address is deliverable without the incorrect secondary.
      However, if you see dpv_footnote C1, then a different, valid apartment or suite number is necessary for USPS delivery. You may want to reach out to the end user and have them double-check the apartment or suite number.
   4. If the dpv_match_code is N, or if the dpv_match_code is absent entirely from the output, then the address isn’t present in the USPS data. It isn’t deliverable by the USPS.
2. Check the enhanced_match output field.
   1. If the field includes none, or if the field is entirely absent from the output, the address isn’t a real address, or at least it isn’t present in any of the address data we have (USPS data nor non-USPS data).
   2. If the field includes non-postal-match, the address is real but not valid for USPS delivery. The address is probably deliverable by UPS, FedEx., or other non-USPS carriers.
   3. If the field includes missing-secondary, the address should have an apartment or suite number, but none was included in the input by the user. You may want to reach out to the end user and check if they forgot to include an apartment or suite number.
   4. If the field includes unknown-secondary, the apartment or suite number included in the input was not recognized by our system. You may want to contact the end user and have them double-check the apartment or suite number.

Sum me up, Smarty!

A good result will look like this:

• dpv_footnote=AABB...
• dpv_match_code=Y
• enhanced_match=postal_match, or non_postal_match

A result requiring changes might look something like:

• dpv_footnote= AABBCC, AAC1, AAN1
• dpv_match_code=D,S
• enhanced_match includes=missing_secondary

A bad result will look like this:

• dpv_footnote=A1, AAM3
• dpv_match_code=N
• enhanced_match=none

Need more help?

We hope this guide makes your transition from the Legacy Standard edition to the Core edition as smooth as possible. If you run into any issues or have questions about updating your code, interpreting results, or working with enhanced matching, don’t hesitate to reach out. Our Smarty Support Team is always ready to help you troubleshoot and succeed.

👉 Contact us at support@smarty.com or through the support portal in your Smarty Dashboard.