Address Verify Quick Start

Address Verify validates and cleanses address data against reference datasets, correcting errors and standardizing formats to ensure accurate deliveries.

Coverage

Global: Address verification for 250+ countries and territories
Certified datasets: Includes CASS (US) and PAF (UK) certified postal data
Geocoding: Latitude/longitude coordinates and reverse geocoding capabilities
Transliteration: International address conversion for cross-border operations

Available Endpoints

Address Verify provides one primary API endpoint:

International Batch Cleanse - Verify and cleanse addresses globally in single or batch mode

Getting Started

Create an API key if you don’t have one
Structure your address data using the input fields that match your data format
Make your first request using the endpoint documentation above

Here’s an example request for the International Batch Cleanse endpoint:

curl --request POST \
  --url https://api.addressy.com/Cleansing/International/Batch/v1.10/json6.ws \
  --header 'Content-Type: application/json' \
  --data '{
  "Key": "<string>",
  "GeoCode": false,
  "Addresses": [
    {
      "Latitude": "",
      "Longitude": "",
      "Address": "",
      "Address1": "",
      "Address2": "",
      "Address3": "",
      "Address4": "",
      "Address5": "",
      "Address6": "",
      "Address7": "",
      "Address8": "",
      "DeliveryAddress": "",
      "DeliveryAddress1": "",
      "DeliveryAddress2": "",
      "DeliveryAddress3": "",
      "DeliveryAddress4": "",
      "DeliveryAddress5": "",
      "DeliveryAddress6": "",
      "DeliveryAddress7": "",
      "DeliveryAddress8": "",
      "Id": "",
      "SuperAdministrativeArea": "",
      "AdministrativeArea": "",
      "SubAdministrativeArea": "",
      "Locality": "",
      "DependentLocality": "",
      "DoubleDependentLocality": "",
      "Thoroughfare": "",
      "DependentThoroughfare": "",
      "Building": "",
      "Premise": "",
      "SubBuilding": "",
      "SubBuildingFloor": "",
      "PostalCode": "",
      "Organization": "",
      "PostBox": "",
      "Country": "",
      "Contact": "",
      "Function": "",
      "Department": ""
    }
  ],
  "Options": {
    "ServerOptions": {
      "CassAvcEnable": "YES",
      "CassUrbFirst": "YES",
      "CassZipFields": "YES",
      "CassCityAbbreviation": "YES",
      "MaxResults": "",
      "MinimumMatchscore": "0",
      "MinimumVerificationLevel": "0",
      "AddressLineSeparator": "<br>",
      "MinimumSimilarity": "70",
      "SuppressAddressFields": "",
      "SuppressAdditionFields": "",
      "SuppressFields": "",
      "CombinedSearchMethods": "YES",
      "MinimumGeoAccuracyLevel": "0",
      "MaximumGeoDistance": "-1",
      "OutputScript": "Latn",
      "OutputCasing": "Title",
      "EnhancedCountryTool": "ON",
      "CertifiedCountryList": "",
      "DefaultCountry": "",
      "CountryFields": "Country",
      "FieldNameWeight": "",
      "ForceCountry": "",
      "MatchScoreAbsoluteThreshold": "60",
      "MatchScoreThresholdFactor": "95",
      "OutputAddressFormat": "YES",
      "TransliterationIgnoreFields": "ID,ISO3166-2,ISO3166-3,_L,Latitude,Longitude,GeoAccuracy,GeoDistance,AVC",
      "ToolInfo": "YES",
      "UseSymbolicTransliteration": "YES",
      "DuplicateHandlingMask": "",
      "NativeAddressLineReverse": "",
      "SimpleParse": "YES",
      "ReturnVerifiedFieldsOnly": "No",
      "FieldStatus": "true",
      "IgnoreUnmatched": "YES",
      "MinimumPostcode": "0",
      "SuppressUnmatched": "ON",
      "OutputSortType": "Alphabetical",
      "RangeDecompose": "Match",
      "PreferPrimaryValidAlias": "YES",
      "ReferenceDatasetCacheSize": "5"
    },
    "Version": false,
    "Certify": false,
    "Enhance": false,
    "Process": "Verify"
  }
}'

What Address Verify Returns

Address Verify provides:

Verified and standardized address in multiple formats (mailing format, delivery format, structured components)
Address Verification Code (AVC) indicating verification level and match quality
Address Quality Index (AQI) for simplified quality assessment
Geocoding data (latitude/longitude) when available
Corrected postal codes and administrative areas

Response should be in the following format:

[
  {
    "Input": {
      "Address1": "123 Main St",
      "Locality": "Boston",
      "AdministrativeArea": "MA",
      "PostalCode": "02129",
      "Country": "USA"
    },
    "Matches": [
      {
        "Latitude": "42.379796",
        "Longitude": "-71.063420",
        "GeoAccuracy": "P1",
        "GeoDistance": "0",
        "Address": "123 Main St<br>Boston MA 02129-3533",
        "Address1": "123 Main St",
        "Address2": "Boston MA 02129-3533",
        "DeliveryAddress": "123 Main St",
        "DeliveryAddress1": "123 Main St",
        "SuperAdministrativeArea": "",
        "AdministrativeArea": "MA",
        "SubAdministrativeArea": "Suffolk",
        "Locality": "Boston",
        "DependentLocality": "",
        "DoubleDependentLocality": "",
        "Thoroughfare": "Main St",
        "DependentThoroughfare": "",
        "Building": "",
        "Premise": "123",
        "SubBuilding": "",
        "PostalCode": "02129-3533",
        "Organization": "",
        "PostBox": "",
        "CountryName": "United States",
        "ISO3166-2": "US",
        "ISO3166-3": "USA",
        "ISO3166-N": "840",
        "PostalCodePrimary": "02129",
        "PostalCodeSecondary": "3533",
        "AVC": "V44-I44-P7-100",
        "AQI": "A",
        "Sequence": "1",
        "MatchRuleLabel": "Rlhng",
        "HyphenClass": "C"
      }
    ]
  }
]

And you can use this information below to interpret the response fields:

Response Fields

Geocoding Data

Field	Type	Description
`Latitude`	string	WGS 84 latitude in decimal degrees format
`Longitude`	string	WGS 84 longitude in decimal degrees format
`GeoAccuracy`	string	Geocoding accuracy code indicating precision level
`GeoDistance`	string	Radius of accuracy in meters, indicating likely maximum distance between geocode and physical location

Formatted Address Output

Field	Type	Description
`Address`	string	Complete mailing address with line breaks (`<br>`). Correctly formatted for mailing in the relevant country
`Address1` - `Address8`	string	Individual address lines, correctly formatted for mailing in the relevant country
`DeliveryAddress`	string	Full address minus Organization, Locality, AdministrativeArea hierarchy, and PostalCode hierarchy fields
`DeliveryAddress1` - `DeliveryAddress8`	string	Individual lines contained within the DeliveryAddress field

Address Components

Field	Type	Description
`Premise`	string	Alphanumeric code identifying an individual location (commonly house or building number)
`Building`	string	Descriptive name identifying an individual location, should one exist
`SubBuilding`	string	Secondary identifiers for a particular delivery point (e.g., “FLAT 1” or “SUITE 212”)
`SubBuildingFloor`	string	Parsed floor information including label and numeric (e.g., “L7” or “Fl 12”)
`Thoroughfare`	string	Most common street or block data element within a country (e.g., USA Street)
`DependentThoroughfare`	string	Dependent street or block data element (e.g., UK Dependent Street)
`Locality`	string	Most common population center data element (e.g., USA City, Canadian Municipality)
`DependentLocality`	string	Smaller population center dependent on Locality field (e.g., Turkish Neighborhood)
`DoubleDependentLocality`	string	Smallest population center dependent on both Locality and DependentLocality (e.g., UK Village)
`AdministrativeArea`	string	Most common geographic data element within a country (e.g., USA State, Canadian Province)
`SubAdministrativeArea`	string	Smallest geographic data element (e.g., USA County)
`SuperAdministrativeArea`	string	Largest geographic data element within a country
`PostalCode`	string	Complete postal code for the delivery point
`PostalCodePrimary`	string	Primary postal code (e.g., USA ZIP, Canadian Postcode, Indian PINcode)
`PostalCodeSecondary`	string	Secondary postal code information (e.g., USA ZIP+4)

Organization and Contact

Field	Type	Description
`Organization`	string	Business name associated with the delivery point
`Contact`	string	Contact name information
`Function`	string	Function or job title information
`Department`	string	Organizational department information
`PostBox`	string	Post box for the delivery point, should one exist

Country Information

Field	Type	Description
`CountryName`	string	ISO 3166 official country name
`ISO3166-2`	string	Two-character ISO country code
`ISO3166-3`	string	Three-character ISO country code
`ISO3166-N`	string	Three-digit numeric ISO country code

Verification Indicators

Field	Type	Description
`AVC`	string	Address Verification Code. Four-part code showing verification status, match level, parsing quality, and matchscore. Format: V44-I44-P7-100. See AVC documentation
`AQI`	string	Address Quality Index. Simplified quality indicator (A through F). Use AVC for detailed decision-making
`Sequence`	string	Order of addresses from input when multiple addresses are included in a single request (e.g., “7” represents the 7th address)
`MatchRuleLabel`	string	Internal matching rule applied during verification
`HyphenClass`	string	Hyphenation classification for the address
`Unmatched`	string	Information in input address fields unable to be parsed to a particular address field

Address Formatting (Optional)

Field	Type	Description
`AddressFormat`	string	Fields used to construct the Address field (when OutputAddressFormat server option is “Yes”)
`DeliveryAddressFormat`	string	Fields used to construct the DeliveryAddress field (when OutputAddressFormat server option is “Yes”)

Understanding the AVC:

Verification Status (1st character): V=Verified, P=Partially verified, A=Ambiguous, R=Reverted, U=Unverified
Match Level (2nd-3rd characters): 0=None through 5=Delivery point (higher is more granular)
Parsing Quality (middle section): How well the input was parsed
Matchscore (final number): Percentage match between input and reference (100=perfect match, no changes needed)

Note: This quickstart covers the most commonly used fields. Address Verify returns many additional country-specific and certification-specific fields (CASS, PAF, etc.). See the full API documentation for complete field reference.

Input Fields

Address Verify accepts multiple input formats. Use the fields that match your data structure:

Unstructured Input

Field	Type	Description
`Address`	string	Complete address in a single field (e.g., “123 Main St Boston MA 02129”)
`Country`	string	Country name or ISO code (recommended to separate from Address)

Structured Input

Field	Type	Description
`Address1`	string	Street address line 1
`Address2`	string	Street address line 2
`Locality`	string	City or town
`AdministrativeArea`	string	State, province, or region
`PostalCode`	string	Postal or ZIP code
`Country`	string	Country name or ISO code

Additional Input Options

Field	Type	Description
`Organization`	string	Company or organization name
`Building`	string	Building name
`SubBuilding`	string	Apartment, suite, or unit
`Premise`	string	House or building number
`Thoroughfare`	string	Street name
`SuperAdministrativeArea`	string	Region above administrative area

Tip: For best results, use structured input with address components separated when possible. If data is unstructured, pass the complete address in Address1 and always separate the country into the Country field.

Error Response Fields

When an error occurs, the API returns an error response with the following structure:

Field	Type	Description
`Error`	string	The error ID
`Description`	string	A description of the error
`Cause`	string	The cause of the error
`Resolution`	string	Actions to resolve the error

Common Error Codes

Status Code	Meaning	Common Causes
400	Bad Request	Invalid parameters, malformed JSON, missing required fields
401	Unauthorized	Invalid or missing API key
403	Forbidden	API key doesn’t have permission for Address Verify, or daily limit exceeded
500	Internal Server Error	Server-side issue, temporary service disruption

Tip: Check the Resolution field for specific steps to fix the error. For more details on error responses, see International Batch Cleanse in API documentation.

Note: Address Verify corrects and standardizes addresses but does not validate whether an address is currently occupied or deliverable in real-time. It matches against reference datasets which may not reflect the most recent changes.

Try Address Verify

Test Address Verify using the International Batch Cleanse Playground to make your first request.

FAQ

How can Address Verify help me understand if an address is good or not?

Address Verify returns an AVC (Address Verification Code) that provides detailed information about address quality:

Verification level: How granularly the address matched (from broad Administrative Area to specific Delivery Point)
Parsing quality: How well the input address could be separated into components
Postal code accuracy: How precisely the postal code was verified
Matchscore: How much the address changed during verification (100 = no changes needed)

The AVC helps you decide whether to accept the verified address based on your requirements. For example, direct mail campaigns might require a matchscore of 95+, while other applications might accept 80+. Different countries support different verification levels—some validate to delivery point, others only to administrative area. See Country Data Coverage for details.

Which fields should I pass my address into to ensure the best match rate?

Address Verify handles addresses formatted in two main ways:

Complete address in a single field: Pass the entire address in Address1. Quick to implement but may reduce parsing accuracy
Address data divided into multiple fields: Separate known elements (city, postal code) into specific fields, and group mixed information together. Recommended for best results

We recommend the structured approach when possible: use Address1 for street information, then populate Locality, AdministrativeArea, PostalCode, and Country separately. This gives the verification engine more context and improves match rates.Always separate the Country field when possible, even in unstructured requests.

Should I use the AVC or AQI?

Use the AVC (Address Verification Code) for decision-making. While both codes describe address quality, they serve different purposes:

AVC: Detailed proprietary code showing verification level, parsing quality, and matchscore. Use this to decide whether to accept a verified address
AQI: Simplified quality indicator (A through F) providing a high-level view. Useful for reporting but not recommended for acceptance decisions

When deciding whether to accept a verified address, consider both:

How granular the verification was (from the AVC match level)
How much the address changed (from the AVC matchscore)

The AVC provides all this information in one code. See Address Verification Code documentation for full details.

How do Address Capture and Address Verify work together?

Address Capture and Address Verify complement each other in the user journey:

Address Capture: Real-time type-ahead search providing verified addresses as users type
Address Verify: Validation and cleansing for manually entered or edited addresses

Example workflow for ecommerce checkout:

User starts typing in address field, Address Capture provides verified suggestions
If user selects from suggestions, then address is already verified
If user manually enters or edits address, then Address Verify processes and cleanses it
Use the AVC from Verify to decide whether to accept the address or prompt for corrections

This combination ensures all addresses are verified regardless of how they’re entered. Contact your account manager or Loqate support to learn more about using both products together.

Overview

Location Solutions

Data Validation

Resources

Address Verify Quick Start

Coverage

Available Endpoints

Getting Started

What Address Verify Returns

Geocoding Data

Formatted Address Output

Address Components

Organization and Contact

Country Information

Verification Indicators

Address Formatting (Optional)

Unstructured Input

Structured Input

Additional Input Options

Common Error Codes

Try Address Verify

FAQ

Overview

Location Solutions

Data Validation

Resources

​Coverage

​Available Endpoints

​Getting Started

​What Address Verify Returns

​Geocoding Data

​Formatted Address Output

​Address Components

​Organization and Contact

​Country Information

​Verification Indicators

​Address Formatting (Optional)

​Unstructured Input

​Structured Input

​Additional Input Options

​Common Error Codes

​Try Address Verify

​FAQ

Coverage

Available Endpoints

Getting Started

What Address Verify Returns

Geocoding Data

Formatted Address Output

Address Components

Organization and Contact

Country Information

Verification Indicators

Address Formatting (Optional)

Unstructured Input

Structured Input

Additional Input Options

Common Error Codes

Try Address Verify

FAQ