Returns parsed and validated address elements including Delivery Point Validation (DPV), Residential Delivery Indicator (RDI), and Suite data. GetBestMatches will attempt to validate the input address against a CASS approved engine, and make corrections where possible. Multiple address candidates may be returned if a definitive decision cannot be made by the service.

URL Endpoints

GetBestMatches Inputs

Name Type Description
BusinessName String Name of business associated with this address. Used to append Suite data.
Address String Address line of the address to validate.
For example, “123 Main Street”.
Address2 String This line is for address information that does not contribute to DPV coding an address. For example “C/O John Smith” does not help validate the address, but is still useful in delivery.
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/address-validation/

GetBestMatches Outputs

BestMatchesResponse

Name Type Values Description
Addresses Address[] Varies The corrected address candidates.
IsCASS String “true” or “false” Indicates if the unaltered input address is CASS certified. See “What is CASS?” below for more information.
Error Error Varies Error object indicating why the service could not return a result. See “Errors” below for more information.

Address

Name Type Values Description
Address1 String Varies The corrected address line 1.
Address2 String Varies The corrected address line 2.
City String Varies The corrected city name.
State String Varies The corrected state name.
Zip String Varies The corrected zip code + 4.
IsResidential String “true” or “false” Indicates if the address is for a residence.
String 1-4 Number that correlates to a DPV(Delivery Point Validation) result. An indicator displaying whether or not the address is recognized as deliverable by the USPS.
DPVDesc String Varies Explains DPV result.
DPVNotes String Varies Number that correlates to DPV notes description. Service Objects may add or change Note descriptions, but will never modify existing codes.
DPVNotesDesc String Varies Details about the DPV result. Service Objects may add or change Note descriptions, but will never modify existing codes.
Corrections String Varies Number that correlates to a Corrections Description. Service Objects may add or change Correction descriptions, but will never modify existing codes.
CorrectionsDesc String Varies Description of what was corrected in an address. Service Objects may add or change Correction descriptions, but will never modify existing codes.
String Varies

The post office delivery barcode digits.

Barcode Example: 931011445011

931011445011
Zip+4Deliver Point CodeChecksum Digit
CarrierRoute String 4 chars 4 chars: 1 for the route type, 3 for the route code. Identifies a group of addresses when prepended by 5-digit Zip.
CongressCode String Varies The congress code is the congressional district number.
CountyCode String Varies The county code of the given address.
CountyName String Varies The name of the county in which the given address lies.
FragmentHouse String Varies

The parsed house number of the given address.

123 in 123 North Main St West Apt A

FragmentPreDir String Varies

The parsed pre-directional of the address's street

North in 123 North Main St West Apt A

FragmentStreet String Varies

The parsed name of the street in the given address

Main in 123 North Main St West Apt A

FragmentSuffix String Varies

The parsed suffix of the street in the given address

St in 123 North Main St West Apt A

FragmentPostDir String Varies

The parsed post-directional of the address's street

West in 123 North Main St West Apt A

FragmentUnit String Varies The parsed unit type (e.g. “Apt” or “Ste”)
Fragment String Varies The parsed “Fragment” box, apartment or unit number.
FragmentPMBPrefix String Varies

The parsed type of the apartment, box, unit, etc

Apt in 123 North Main St West Apt A

FragmentPMBNumber String Varies

The parsed apartment, box, unit, etc. number of the given address.

123 in 123 North Main St West Apt A

Example Request URL and Response

To validate the address 136 West Canon Perdido St Ste D Santa Barbara, CA 93101, the JSON request URL can be formatted with query string parameters as follows:
The corresponding JSON response is:
Plain text
Copy to clipboard
Open code in new window
EnlighterJS 3 Syntax Highlighter
{
"Addresses": [
{
"Address1": "136 W Canon Perdido St STE D",
"Address2": "",
"City": "Santa Barbara",
"State": "CA",
"Zip": "93101-8207",
"IsResidential": "false",
"DPV": "1",
"DPVDesc": "Yes, the input record is a valid mailing address",
"DPVNotes": "24,26,28,39",
"DPVNotesDesc": "SuiteLink did not find Suite or Unit data to append to the address,The input address matched the ZIP+4 record,The input address matched the DPV record,Highrise apartment/office building address",
"Corrections": "",
"CorrectionsDesc": "",
"BarcodeDigits": "931018207766",
"CarrierRoute": "C008",
"CongressCode": "24",
"CountyCode": "083",
"CountyName": "Santa Barbara",
"FragmentHouse": "136",
"FragmentPreDir": "W",
"FragmentStreet": "Canon Perdido",
"FragmentSuffix": "St",
"FragmentPostDir": "",
"FragmentUnit": "STE",
"Fragment": "D",
"FragmentPMBPrefix": "",
"FragmentPMBNumber": ""
}
],
"IsCASS": true
}
{ "Addresses": [ { "Address1": "136 W Canon Perdido St STE D", "Address2": "", "City": "Santa Barbara", "State": "CA", "Zip": "93101-8207", "IsResidential": "false", "DPV": "1", "DPVDesc": "Yes, the input record is a valid mailing address", "DPVNotes": "24,26,28,39", "DPVNotesDesc": "SuiteLink did not find Suite or Unit data to append to the address,The input address matched the ZIP+4 record,The input address matched the DPV record,Highrise apartment/office building address", "Corrections": "", "CorrectionsDesc": "", "BarcodeDigits": "931018207766", "CarrierRoute": "C008", "CongressCode": "24", "CountyCode": "083", "CountyName": "Santa Barbara", "FragmentHouse": "136", "FragmentPreDir": "W", "FragmentStreet": "Canon Perdido", "FragmentSuffix": "St", "FragmentPostDir": "", "FragmentUnit": "STE", "Fragment": "D", "FragmentPMBPrefix": "", "FragmentPMBNumber": "" } ], "IsCASS": true }
{
  "Addresses": [
    {
      "Address1": "136 W Canon Perdido St STE D",
      "Address2": "",
      "City": "Santa Barbara",
      "State": "CA",
      "Zip": "93101-8207",
      "IsResidential": "false",
      "DPV": "1",
      "DPVDesc": "Yes, the input record is a valid mailing address",
      "DPVNotes": "24,26,28,39",
      "DPVNotesDesc": "SuiteLink did not find Suite or Unit data to append to the address,The input address matched the ZIP+4 record,The input address matched the DPV record,Highrise apartment/office building address",
      "Corrections": "",
      "CorrectionsDesc": "",
      "BarcodeDigits": "931018207766",
      "CarrierRoute": "C008",
      "CongressCode": "24",
      "CountyCode": "083",
      "CountyName": "Santa Barbara",
      "FragmentHouse": "136",
      "FragmentPreDir": "W",
      "FragmentStreet": "Canon Perdido",
      "FragmentSuffix": "St",
      "FragmentPostDir": "",
      "FragmentUnit": "STE",
      "Fragment": "D",
      "FragmentPMBPrefix": "",
      "FragmentPMBNumber": ""
    }
  ],
  "IsCASS": true
}

References