Overview
This section provides endpoints for address verification and normalization using the EasyPost service. These endpoints allow clients to validate and standardize address data, which helps ensure accurate shipping labels and deliveries.
1. Normalize Address
This endpoint takes an address and returns a normalized version using the EasyPost API. It converts the address to a standardized format and corrects minor errors in spelling or formatting.
POST /api/v1/addresses/normalize
{
"X-API-Key": "123456789",
"Content-Type": "application/json"
}
Request Body
{
"address": {
"street1": "417 Montgomery St",
"street2": "5th Floor",
"city": "San Francisco",
"state": "CA",
"zip": "94104",
"country": "US",
"name": "John Doe",
"company": "Example Corp",
"phone": "555-555-5555"
}
}
Expected Response
{
"success": true,
"address": {
"street1": "417 MONTGOMERY ST # 5",
"street2": "",
"city": "SAN FRANCISCO",
"state": "CA",
"zip": "94104-1129",
"country": "US",
"residential": false,
"federal_tax_id": null,
"state_tax_id": null,
"verifications": [],
"original": {
"street1": "417 Montgomery St",
"street2": "5th Floor",
"city": "San Francisco",
"state": "CA",
"zip": "94104",
"country": "US",
"name": "John Doe",
"company": "Example Corp",
"phone": "555-555-5555"
},
"is_different": true
}
}
2. Verify Address
This endpoint compares an old address with a new one, and checks if the new address needs verification. If the new address differs from the old one, it's validated against EasyPost's database. The response includes whether the address requires confirmation from the user, which happens when EasyPost suggests a different format or correction for the address.
POST /api/v1/addresses/verify
{
"X-API-Key": "123456789",
"Content-Type": "application/json"
}
Request Body
{
"oldAddress": {
"street1": "417 Montgomery St",
"street2": "",
"city": "San Francisco",
"state": "CA",
"zip": "94104",
"country": "US"
},
"newAddress": {
"street1": "417 Montgomery Street",
"street2": "5th Floor",
"city": "San Fransisco",
"state": "CA",
"zip": "94104",
"country": "US",
"name": "John Doe",
"company": "Example Corp",
"phone": "555-555-5555"
}
}
Expected Responses
Case 1: When Address Has Not Changed
{
"success": true,
"message": "Address has not changed",
"address": {
"street1": "417 Montgomery Street",
"street2": "5th Floor",
"city": "San Fransisco",
"state": "CA",
"zip": "94104",
"country": "US",
"name": "John Doe",
"company": "Example Corp",
"phone": "555-555-5555"
},
"needsConfirmation": false
}
Case 2: When Address Has Changed and Suggestion Differs
{
"success": true,
"message": "Suggested address differs from entered address",
"originalAddress": {
"street1": "417 Montgomery Street",
"street2": "5th Floor",
"city": "San Fransisco",
"state": "CA",
"zip": "94104",
"country": "US",
"name": "John Doe",
"company": "Example Corp",
"phone": "555-555-5555"
},
"suggestedAddress": {
"street1": "417 MONTGOMERY ST",
"street2": "5TH FLOOR",
"city": "SAN FRANCISCO",
"state": "CA",
"zip": "94104-1129",
"country": "US",
"residential": false,
"federal_tax_id": null,
"state_tax_id": null,
"verifications": {
"delivery": {
"success": true,
"errors": []
}
},
"original": {
"street1": "417 Montgomery Street",
"street2": "5th Floor",
"city": "San Fransisco",
"state": "CA",
"zip": "94104",
"country": "US",
"name": "John Doe",
"company": "Example Corp",
"phone": "555-555-5555"
},
"is_different": true
},
"needsConfirmation": true
}
Case 3: When Verification Failed
{
"success": false,
"message": "Address verification failed",
"error": "The address could not be verified: invalid zip code for state",
"address": {
"street1": "417 Montgomery Street",
"street2": "5th Floor",
"city": "San Fransisco",
"state": "CA",
"zip": "12345",
"country": "US",
"name": "John Doe",
"company": "Example Corp",
"phone": "555-555-5555"
},
"needsConfirmation": false
}
Technical Details
The normalizeAddress endpoint processes a single address and returns it in standardized format
The verify endpoint compares two addresses and suggests corrections when they differ
Required fields for addresses are: street1, city, state, and zip
The API handles common abbreviations and minor formatting differences when comparing addresses
For ZIP codes, only the first 5 digits are compared, ignoring extensions
Special characters and extra spaces are removed during comparison to reduce false positives
Usage Recommendations
Use the normalize endpoint when you just need to standardize a single address
Use the verify endpoint during address update processes to validate changes
Always implement a user confirmation step when needsConfirmation is true
If is_different is true in a response, your UI should present both options to the user
The originalAddress should be displayed alongside the suggestedAddress for user comparison
Consider caching verified addresses to reduce API calls to EasyPost