Returns parsed and validated address elements along with a list of potential secondary numbers for a given input address. The operation can be leveraged in conjunction with the GetBestMatches operation to find secondary numbers for input data that has either missing or incorrect unit information. For an example workflow please see the Workflow section below.

URL Endpoints

GetSecondaryNumbers Inputs

NameTypeDescription
AddressStringAddress line of the address to validate.  
For example, “123 Main Street”.
CityStringThe 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.
StateStringThe 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.
PostalCodeStringThe 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*StringYour license key to use the service.  
Sign up for a free trial key at https://www.serviceobjects.com/products/address-geocoding/usps-address-validation

GetSecondaryNumbers Outputs

SecondaryNumbersResponse

NameTypevaulesDescription
Address1StringVariesThe corrected address line 1.
CityStringVariesThe corrected city name.
StateStringVariesThe corrected state name.
ZipStringVariesThe corrected zip code + 4.
TotalCountStringVariesThe total number of secondary numbers found for the input address.
SecondaryNumbersString[]VariesA list of possible secondary numbers for the input address.
ErrorErrorVariesError object indicating why the service could not return a result. See “Errors” below for more information.

Typical Example Workflow

1) Validate an address using the recommended GetBestMatches operation.

2) If GetBestMatches returns a DPV 3 or 4:

3The apartment or rural route box number is not valid, although the house number or rural route is valid
4The input record is a valid mailing address, but is missing the apartment or rural route box number

3) Get a list of potential secondary numbers using the GetSecondaryNumbers operation.

The example below helps to illustrate how GetBestMatches and GetSecondaryNumbers tie together. The input “Address” field is missing the unit information for the office building.

Input fieldValue
Address27 E Cota St
CitySanta Barbara
StateCA
PostalCode93101

GetBestMatches XML Response – DPV 4 – The input record is a valid mailing address, but missing the apartment or rural route box number

<BestMatchesResponse xmlns="http://www.serviceobjects.com" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<Addresses>
<Address>
<Address1>27 E Cota St</Address1>
<Address2/>
<City>Santa Barbara</City>
<State>CA</State>
<Zip>93101-7603</Zip>
<IsResidential>false</IsResidential>
<DPV>4</DPV>
<DPVDesc>The input record is a valid mailing address, but is missing the apartment or rural route box number</DPVDesc>
<DPVNotes>11,22,26,39</DPVNotes>
<DPVNotesDesc>
Default ZIP+4 record used to certify the address,Address exists but mail is being returned,The input address matched the ZIP+4 record,Highrise apartment/office building address
</DPVNotesDesc>
<Corrections/>
<CorrectionsDesc/>
<BarcodeDigits>931017603992</BarcodeDigits>
<CarrierRoute>C006</CarrierRoute>
<CongressCode>24</CongressCode>
<CountyCode>083</CountyCode>
<CountyName>Santa Barbara</CountyName>
<FragmentHouse>27</FragmentHouse>
<FragmentPreDir>E</FragmentPreDir>
<FragmentStreet>Cota</FragmentStreet>
<FragmentSuffix>St</FragmentSuffix>
<FragmentPostDir/>
<FragmentUnit/>
<Fragment/>
<FragmentPMBPrefix/>
<FragmentPMBNumber/>
</Address>
</Addresses>
<IsCASS>true</IsCASS>
</BestMatchesResponse>

GetSecondaryNumbers – 9 different suite options found

<SecondaryNumbersResponse xmlns="http://www.serviceobjects.com" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
<Address1>27 E Cota St</Address1>
<City>Santa Barbara</City>
<State>CA</State>
<Zip>93101</Zip>
<SecondaryNumbers>
<string>STE 100</string>
<string>STE 101</string>
<string>STE 200</string>
<string>STE 201</string>
<string>STE 401</string>
<string>STE 500</string>
<string>STE 501</string>
<string>STE 502</string>
<string>STE 503</string>
</SecondaryNumbers>
<TotalCount>9</TotalCount>
</SecondaryNumbersResponse>

References