How to Validate Addresses

Catch wrong or incomplete addresses before you buy a label. Failed deliveries, return-to-sender fees and courier address-correction surcharges all start with a bad address.

POST/addresses/validations

What it does

Checks, corrects and standardises an address

Countries

US and international, one endpoint

Scope

public.address_validation:write

Billing

Per call. US addresses are billed at the US rate

What validation does for you

✅

Confirms deliverability

Checks that couriers recognise the address.

🧹

Fixes mistakes

Fills in a missing postal code, corrects typos, and fixes a postal code that doesn't match the city.

📐

Standardises the format

Formats the address the way the local postal service and couriers expect it.

🔤

Transliterates

Converts non-Latin scripts to Latin: Улица Ленина 12 → Ulica Lenina 12.

Where to use it: at checkout (ask the buyer to confirm a correction), when importing orders in bulk, and before shipping to countries with non-Latin scripts.

Validate an address

Send the address
Required: line_1, city, country_alpha2. Optional, but they improve accuracy: postal_code, state, line_2, company_name.

cURLPOST /2024-09/addresses/validations
curl -X POST https://public-api.easyship.com/2024-09/addresses/validations \ -H "Authorization: Bearer $EASYSHIP_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "line_1": "10 Downing Street", "city": "London", "postal_code": "SW1A 2AA", "country_alpha2": "GB", "replace_with_validation_result": false }'
Read the result
Response200 OK
{ "address": { "id": "01563646-58c1-4607-8fe0-cae3e33c0001", "line_1": "10 Downing Street", "city": "London", "postal_code": "SW1A 2AA", "country_alpha2": "GB", "validation": { "status": "verified", "detail": "premise", "comparison": { "pre": "premise", "post": "premise", "changes": "none" }, "address": { "line_1": "10 Downing Street", "city": "London", "state": "London", "postal_code": "SW1A 2AA", "company_name": "Prime Minister's Office" } } } }

Decide what to do

The validation object has four parts. Check status first, then comparison.changes.

validation.status: was the address found?

`status`	Meaning
verified	The address was matched to a known, deliverable address
partial	Only part of the address could be matched (for example, the street but not the building)
ambiguous	More than one possible match; the address needs more detail
none	The address couldn't be verified

validation.comparison.changes: how much the returned address differs from what you sent, based on a 0–100 match score.

`changes`	Match score	Suggested action
none	100	Use the address as sent
minor	95–99 (for example, capitalisation or a single character)	Use `validation.address`
moderate	90–94	Show the suggestion and let the buyer confirm
major	80–89	Ask the buyer to confirm or re-enter
drastic	0–79	Ask the buyer to re-enter the address

validation.detail is the most precise level the returned address reaches: premise (building), street, city or none.

validation.comparison.pre / post show that level before and after correction, from most to least precise: delivery_point → premise → street → city → state → none. For example, pre: street and post: premise means validation added the building.

replace_with_validation_result: set it to true to save the corrected address automatically. Leave it false when the buyer should confirm the change first.

FAQ

Do I need a different endpoint for US addresses?

No. Use /addresses/validations with "country_alpha2": "US". The old domestic endpoint will stop working on 31 October 2026.

Why do I get 422 invalid_content?

A required field is missing. line_1, city and country_alpha2 are required.

Is state required?

Not for validation, but couriers require it to ship to AU, CA, CN, ID, MX, MY, TH, US and VN, so collect it for those countries.

Is every call billed?

Yes, every successful call counts towards your usage, except in the sandbox. US addresses are billed at the US Address Validation rate.

What validation does for you

Validate an address

FAQ

Related