Address Validation Consolidation: Migration Guide

⚠️ Deprecation Notice Action Required

The POST /{version}/addresses/validations_domestic endpoint is being deprecated. Please migrate to POST /{version}/addresses/validations — the unified Address Validation endpoint that handles both US and non-US addresses.

What you need to do: Update your API call URL and add "country_alpha2": "US" to your request body. No other changes are required.

Billing is unchanged. Requests with country_alpha2: "US" continue to be billed at the US Address Validation rate. There is no price change.

On this page

Overview
What changes: the two-line migration
Endpoint reference
Parameter differences
Billing — no change
OAuth scope
Before & after examples
FAQ

Overview

We are consolidating address validation into a single endpoint: POST /{version}/addresses/validations. This endpoint handles both US and non-US addresses, so you no longer need to decide which endpoint to call based on the destination country.

The POST /{version}/addresses/validations_domestic endpoint is being deprecated. The migration requires two small changes to your integration — see below.

Your validation results and billing rates are unchanged. US addresses continue to be validated with the same accuracy and billed at the same US Address Validation rate.

What changes: the two-line migration

This is a minimal change. There are exactly two things to update:

Update the URL
Replace /addresses/validations_domestic with /addresses/validations.
Add country_alpha2: "US" to your request body
Pass "country_alpha2": "US" in your request body. This tells the endpoint which country to validate against.

That's it. No changes to authentication, response parsing, error handling, or retry logic are needed. The response schema is identical between the two endpoints.

Before (deprecated)

POST /2024-09/addresses/validations_domestic

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

After (use this)

POST /2024-09/addresses/validations

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

Endpoint reference

Endpoint	API versions	Status
`POST /{version}/addresses/validations_domestic`	`2023-01`, `2024-09`	Deprecated
`POST /{version}/addresses/validations`	`2023-01`, `2024-09`	Use this

The deprecated endpoint will return 410 Gone once it is retired. Migrate before the deprecation date communicated to you by your account manager.

Parameter differences

All parameters are identical between the two endpoints with one exception: country_alpha2.

Parameter	Deprecated endpoint	Unified endpoint
`line_1`	Required	Required
`city`	Required	Required
`postal_code`	Required	Required
`state`	Optional	Optional
`line_2`	Optional	Optional
`company_name`	Optional	Optional
`replace_with_validation_result`	Optional (boolean)	Optional (boolean)
`country_alpha2`	✘ Not accepted — always forced to `"US"`	✔ Required — pass `"US"` for US addresses

country_alpha2 is case-insensitive. The API accepts "US", "us", or "Us" — all are treated the same.

Billing — no change

Your pricing and quotas are unchanged. The unified endpoint bills based on the country_alpha2 you provide — US addresses are billed at the US Address Validation rate, all other countries at the standard Address Validation rate.

Address country	Billed as
US (`country_alpha2: "US"`)	US Address Validation
All other countries	Address Validation

No overage surprises. Your existing US Address Validation quota and overage thresholds remain exactly as before.

OAuth scope

The unified endpoint requires the public.address_validation:write scope. If your OAuth token was issued with the deprecated public.address_validation_domestic:write scope only, you will need to re-issue a token with the correct scope before migrating.

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

Check your token scopes before deploying. A request to the unified endpoint with only the address_validation_domestic scope will receive a 403 Forbidden response. Re-issue your token through your OAuth application settings or contact your account manager if you need assistance.

Before & after examples

Example 1 — Validate a US address

// Before (deprecated)
POST /2024-09/addresses/validations_domestic
Authorization: Bearer <token with address_validation_domestic:write>

{
  "line_1": "1600 Amphitheatre Pkwy",
  "city": "Mountain View",
  "state": "CA",
  "postal_code": "94043"
}

// After (use this)
POST /2024-09/addresses/validations
Authorization: Bearer <token with address_validation:write>

{
  "line_1": "1600 Amphitheatre Pkwy",
  "city": "Mountain View",
  "state": "CA",
  "postal_code": "94043",
  "country_alpha2": "US"
}

Billing: Counted as US Address Validation — same rate as before.

Example 2 — With replace_with_validation_result

// Before (deprecated)
POST /2024-09/addresses/validations_domestic

{
  "line_1": "350 Fifth Ave",
  "city": "New York",
  "state": "NY",
  "postal_code": "10118",
  "replace_with_validation_result": true
}

// After (use this)
POST /2024-09/addresses/validations

{
  "line_1": "350 Fifth Ave",
  "city": "New York",
  "state": "NY",
  "postal_code": "10118",
  "replace_with_validation_result": true,
  "country_alpha2": "US"
}

Example 3 — Successful response (identical on both endpoints)

// HTTP 200 — response shape is unchanged
{
  "address": {
    "id": "addr_abc123",
    "line_1": "1600 Amphitheatre Pkwy",
    "line_2": null,
    "line_3": null,
    "city": "Mountain View",
    "state": "CA",
    "postal_code": "94043",
    "country_alpha2": "US",
    "validation_data": {
      "status": "verified",
      "detail": "premise"
    }
  }
}

FAQ

Will my billing rate change after migrating?

No. Requests to /addresses/validations with country_alpha2: "US" are automatically billed at the US Address Validation rate — the same rate you pay today on the domestic endpoint.

What happens if I forget to include country_alpha2?

The request will be rejected with a 422 Unprocessable Entity error. country_alpha2 is required on the unified endpoint. Always pass "US" for US address validation.

Do I need to change how I parse the response?

No. The response schema is identical between the two endpoints. No changes to deserialization, field mapping, or error handling are required.

What scope does my OAuth token need?

Your token needs the public.address_validation:write scope. If your current token only has public.address_validation_domestic:write, re-issue it through your OAuth application settings before deploying the URL change. See OAuth scope above.

Can I use the unified endpoint for non-US addresses too?

Yes — and that is precisely the point. Pass any valid ISO 3166-1 alpha-2 country code in country_alpha2. Requests with a non-US country code are billed at the standard Address Validation rate.

Does the 2023-01 API version work the same way?

Yes. Both 2023-01 and 2024-09 support POST /{version}/addresses/validations. Simply replace the version prefix as appropriate for your integration.

What happens to the domestic endpoint after deprecation?

Once fully retired, POST /{version}/addresses/validations_domestic will return 410 Gone. Your account manager will notify you of the exact retirement date with sufficient lead time.

Overview

What changes: the two-line migration

Endpoint reference

Parameter differences

Billing — no change

OAuth scope

Before & after examples

Example 1 — Validate a US address

Example 2 — With replace_with_validation_result

Example 3 — Successful response (identical on both endpoints)

FAQ

Related