Address Validation Intro

Introduction to Address Validation

Address validation ensures the accuracy, completeness, and standardization of address data within the United States. By validating addresses, businesses can minimize errors, prevent costly shipping issues, and maintain operational efficiency. Inaccurate or incomplete addresses can lead to shipping delays, returned mail, and potential compliance issues, making address validation an essential tool for businesses managing large volumes of orders.

Important Note:
Currently, the Address Validation API only supports addresses within the United States. Any attempt to validate addresses outside the US will result in an error.

How Address Validation Works

Complyt’s Address Validation API simplifies the process by checking the provided address against official US postal databases. The API identifies potential matches, evaluates their accuracy, and returns the most relevant addresses with a confidence score.

Key Features

1. Component Validation
   Each part of the address—street, city, state, zip code, and country—is validated to detect common errors, such as misspellings or incorrect zip codes.

2. Scoring System
   The API assigns a match level (e.g., EXCELLENT, GOOD) and a confidence score (0.0 - 1.0) to indicate how closely the provided address matches official records.

3. Field Matching
   The system evaluates individual address components, such as country, state, city, street, and zip, with match levels (EXACT, GOOD, etc.) to provide detailed accuracy insights.

Error Handling

When using the Address Validation API, errors may occur due to unsupported inputs, incomplete data, or invalid address formats. These errors provide clear messages to help resolve the issues effectively.

Error Response Behavior

• If the address is invalid, the API returns a 400 Bad Request status code along with an error message detailing the issue.

Example API Response

The following response showcases how the Address Validation API processes an input address and provides potential matches:

{
    "matchedAddresses": [
        {
            "address": {
                "city": "Phoenix",
                "country": "United States",
                "county": "Maricopa",
                "state": "Arizona",
                "street": "S 3rd Ave",
                "zip": "85041-5705"
            },
            "scoring": {
                "matchLevel": "EXCELLENT",
                "score": 0.96,
                "fieldScore": {
                    "countryMatch": "EXACT",
                    "stateMatch": "EXACT",
                    "cityMatch": "EXACT",
                    "streetMatch": "GOOD",
                    "zipMatch": "EXACT"
                }
            }
        },
        {
            "address": {
                "city": "Phoenix",
                "country": "United States",
                "county": "Maricopa",
                "state": "Arizona",
                "street": "S 3rd St",
                "zip": "85042-4206"
            },
            "scoring": {
                "matchLevel": "EXCELLENT",
                "score": 0.92,
                "fieldScore": {
                    "countryMatch": "EXACT",
                    "stateMatch": "EXACT",
                    "cityMatch": "EXACT",
                    "streetMatch": "GOOD",
                    "zipMatch": "GOOD"
                }
            }
        }
    ],
    "requestAddress": {
        "city": "Phoenix",
        "country": "USA",
        "state": "Arizona",
        "street": "6001 W 3rd St",
        "zip": "85041-5705",
        "isPartial": false
    }
}