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

JSON

https://trial.serviceobjects.com/AV3/api.svc/GetSecondaryNumbersJson?Address={ADDRESS}&City={CITY}&State={STATE}&PostalCode={POSTALCODE}&LicenseKey={LICENSEKEY}

XML

https://trial.serviceobjects.com/AV3/api.svc/GetSecondaryNumbers?Address={ADDRESS}&City={CITY}&State={STATE}&PostalCode={POSTALCODE}&LicenseKey={LICENSEKEY}

GetSecondaryNumbers Inputs

Name	Type	Description
Address	String	Address line of the address to validate. For example, "123 Main Street".
City	String	The 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.
State	String	The 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.
PostalCode	String	The 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*	String	Your 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

Name	Type	Values	Description
Address1	String	Varies	The corrected address line 1.
City	String	Varies	The corrected city name.
State	String	Varies	The corrected state name.
Zip	String	Varies	The corrected zip code + 4.
TotalCount	String	Varies	The total number of secondary numbers found for the input address.
SecondaryNumbers	String[]	Varies	A list of possible secondary numbers for the input address.
Error	Error	Varies	Error 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:

3	The apartment or rural route box number is not valid, although the house number or rural route is valid
4	The 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 Field	Value
Address	27 E Cota St
City	Santa Barbara
State	CA
PostalCode	93101

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37

<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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

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

Page tree

URL Endpoints

GetSecondaryNumbers Inputs

GetSecondaryNumbers Outputs

Typical Example Workflow

References

Page tree

AV3 - GetSecondaryNumbers

URL Endpoints

GetSecondaryNumbers Inputs

GetSecondaryNumbers Outputs

Typical Example Workflow

References