Address Validation Consolidation: Migration Guide

Deprecation notice: POST /addresses/validations_domestic Retires 31 Oct 2026

Move to POST /addresses/validations, the single endpoint for US and non-US addresses. Change the URL and add "country_alpha2": "US". Billing is unchanged.

After 31 Oct 2026, calls to the domestic endpoint return 410 Gone.

A two-line change: one URL and one field. Your responses, error handling and US billing rate stay the same.

POST/addresses/validations POST/addresses/validations_domestic

Deadline

31 Oct 2026

Change

New URL + country_alpha2

New scope

public.address_validation:write

Billing

Unchanged

On this page

What changes
Parameter differences
OAuth scope
Billing
Examples
FAQ

What changes

Update the URL
Replace /addresses/validations_domestic with /addresses/validations. Both work in 2023-01 and 2024-09.
Add "country_alpha2": "US" to the body
The unified endpoint needs the country to know which rules to validate against. Use the uppercase code.

Before/validations_domestic

{ "line_1": "417 Montgomery St", "city": "San Francisco", "state": "CA", "postal_code": "94104" }

After/validations

{ "line_1": "417 Montgomery St", "city": "San Francisco", "state": "CA", "postal_code": "94104", "country_alpha2": "US" }

That's it. The response has the same shape on both endpoints, so you don't need to change how you parse responses or handle errors.

Parameter differences

Only country_alpha2 differs.

Parameter	Domestic (deprecated)	Unified
`line_1`	Required	Required
`city`	Required	Required
`country_alpha2`	✘ Not accepted (always US)	✔ Required: `"US"` for US addresses
`postal_code`	Optional	Optional
`state`	Optional	Optional
`line_2`	Optional	Optional
`company_name`	Optional	Optional
`replace_with_validation_result`	Optional (boolean)	Optional (boolean)

Sending postal_code and state still gives the most accurate results.

OAuth scope

Endpoint	Required scope
`/addresses/validations_domestic` (deprecated)	`public.address_validation_domestic:write`
`/addresses/validations`	`public.address_validation:write`

Check your token before you switch. A token with only the domestic scope gets 403 Forbidden on the unified endpoint. Add public.address_validation:write to your API connection, or ask your account manager.

Billing

Billing follows the country_alpha2 you send. The rates and quotas you have today don't change.

Address country	Billed as
US (`"country_alpha2": "US"`)	US Address Validation (same as the domestic endpoint)
Any other country	Address Validation

Examples

Validate a US address

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": "350 Fifth Ave", "city": "New York", "state": "NY", "postal_code": "10118", "country_alpha2": "US", "replace_with_validation_result": true }'

Response (same on both endpoints)

Response200 OK

{ "address": { "id": "01563646-58c1-4607-8fe0-cae3e33c0001", "line_1": "350 5th Ave", "city": "New York", "state": "NY", "postal_code": "10118-0110", "country_alpha2": "US", "validation": { "status": "verified", "detail": "premise", "comparison": { "pre": "premise", "post": "premise", "changes": "minor" }, "address": { "line_1": "350 5th Ave", "city": "New York", "state": "NY", "postal_code": "10118-0110" } } } }

How to read status and comparison: see How to Validate Addresses.

FAQ

What happens after 31 Oct 2026?

POST /addresses/validations_domestic returns 410 Gone, with a message pointing to this guide.

What if I forget country_alpha2?

The request fails with 422 (invalid_content), because country_alpha2 is required on the unified endpoint.

Will my bill change?

No. Requests with "country_alpha2": "US" are billed at the US Address Validation rate, the same as today.

Can I use the unified endpoint for other countries?

Yes. Send any ISO 3166-1 alpha-2 code. Non-US addresses are billed at the standard Address Validation rate.

Do I need to change how I read the response?

No. Both endpoints return the same address object, including validation.

What changes

Parameter differences

OAuth scope

Billing

Examples

Validate a US address

Response (same on both endpoints)

FAQ

Related