API
Validate an address
Check a postal address with POST /v1/addresses/validate and act on the decision, suggestions and issues it returns.
POST /v1/addresses/validate checks one address and tells you what to do with it. Use it in your checkout, in a customer account or anywhere a customer enters an address. Standalone address checks are not metered; they only count against your hourly limit. To check the address of a placed order, use Orders instead.
Request
| Field | Type | Description |
|---|---|---|
address |
object | The address to check. Required. |
context |
string | Where the address comes from: checkout, account, other or test. Optional. |
email |
string | The buyer's email, for your checkout rules. Only allowed with context: "checkout". Never stored or logged. |
The address object:
| Field | Description |
|---|---|
countryCode |
ISO 3166-1 alpha-2 code, such as DE or US. Required. |
address1 |
Street and house number. |
address2 |
Apartment, suite, building. |
city |
City or town. |
zip |
Postal code. |
province, provinceCode |
State or region, as a name or a code. |
firstName, lastName, company, phone |
Optional. Sent along with the address. |
Empty optional fields may be omitted or sent as null. Strings can be at most 255 characters.
About context:
checkout: the answer also containsrules, the checkout rules of your shop that the address (or theemail) breaks.accountandother: a plain check. This is the default when you leavecontextout.test: for an admin "test an address" screen. It always asks the provider (no cache), is never billed, and has its own hourly limit. A used-up test limit answers429 rate_limited.
Example
curl https://api.address-validation.io/v1/addresses/validate \
-H "Authorization: Bearer $AVIO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"address": {
"address1": "Unter den Linden 77",
"city": "Berlin",
"zip": "10118",
"countryCode": "DE"
},
"context": "checkout"
}'const response = await fetch("https://api.address-validation.io/v1/addresses/validate", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.AVIO_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
address: { address1: "Unter den Linden 77", city: "Berlin", zip: "10118", countryCode: "DE" },
context: "checkout",
}),
signal: AbortSignal.timeout(5000),
});
if (!response.ok) {
throw new Error(`AVIO ${response.status}: ${(await response.json()).error}`);
}
const check = await response.json();<?php
$payload = json_encode([
'address' => [
'address1' => 'Unter den Linden 77',
'city' => 'Berlin',
'zip' => '10118',
'countryCode' => 'DE',
],
'context' => 'checkout',
]);
$ch = curl_init('https://api.address-validation.io/v1/addresses/validate');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => $payload,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . getenv('AVIO_API_KEY'),
'Content-Type: application/json',
],
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 5,
]);
$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);
$check = json_decode($body, true);
if ($status !== 200) {
throw new RuntimeException("AVIO {$status}: {$check['error']}");
}import os
import requests
response = requests.post(
"https://api.address-validation.io/v1/addresses/validate",
headers={"Authorization": f"Bearer {os.environ['AVIO_API_KEY']}"},
json={
"address": {
"address1": "Unter den Linden 77",
"city": "Berlin",
"zip": "10118",
"countryCode": "DE",
},
"context": "checkout",
},
timeout=5,
)
response.raise_for_status()
check = response.json()Here the postal code was off by one digit. AVIO corrected it and asks the customer to confirm:
{
"decision": "warn",
"mode": "balanced",
"addressHash": "5d0c3e9a7b41f2c86e1a9d07b3f5c2e48a6d1b90c7e3f5a2d4b6c8e0f1a3b5c7",
"verdict": {
"status": "corrected",
"provider": "loqate",
"granularity": "premise",
"changes": [
{ "field": "zip", "from": "10118", "to": "10117", "kind": "minor" }
],
"missing": [],
"unverified": [],
"suggestions": [
{
"address1": "Unter den Linden 77",
"city": "Berlin",
"zip": "10117",
"countryCode": "DE"
}
]
},
"issues": [],
"rules": []
}Read the result
decision
decision is the field to act on. It already applies the validation mode configured for the address's country.
decision |
What to do |
|---|---|
valid |
Accept the address. |
warn |
The address was corrected or is uncertain. Show the suggestion and let the customer confirm or edit. |
invalid |
The address can't be delivered as entered. Ask the customer to fix it, offering verdict.suggestions if there are any. |
skipped |
No answer, for example the country isn't covered, a provider failed or your hourly limit is used up. Let the customer continue. |
The address check fails open: problems on our side answer skipped instead of an error, so a checkout never has to block on AVIO.
mode
The validation mode used for this check: strict, balanced or loose. Stricter modes turn more corrections and less precise matches into invalid.
verdict
verdict is the detail behind the decision:
| Field | Meaning |
|---|---|
status |
The provider's view: deliverable, corrected, ambiguous, invalid, unsupported or error. |
provider |
Which provider answered. |
granularity |
How precisely the address was matched: subpremise (unit), premise (building), street, locality or none. |
changes |
Each corrected field with field, from, to and kind (alias, format, minor, major or inferred). |
missing |
Parts the customer left empty that are needed: house_number, street, subpremise, postbox_number, zip, city. |
unverified |
Parts the customer entered that couldn't be confirmed (same values as missing). |
suggestions |
Corrected addresses to offer, in the same shape as the input address. Can be empty. |
suggestionsProvider |
The provider of the suggestions, when it differs from provider. |
blocked |
poBox or parcelLocker when your delivery-point settings don't allow this kind of address. The decision is then invalid; ask for another address instead of offering suggestions. |
Note: When
suggestionsProvider(or, if absent,provider) is
issues
issues lists problems found in the address as entered, before any provider was asked: missing_house_number, empty_required_field, zip_in_address1, email_in_field, phone_in_field, url_in_field, po_box, po_box_blocked, parcel_locker, parcel_locker_without_number, parcel_locker_blocked and address_rule. Use them to show a precise hint next to the right field.
rules
Only with context: "checkout". Each entry is { "code", "field" }, one per checkout rule of your shop the input breaks, for example { "code": "house_number", "field": "address1" }. Codes: house_number, zip_format, too_long, po_box, parcel_locker_blocked, parcel_locker, email_invalid, email_disposable, address_rule. Fields: address1, address2, city, zip, province, email. An empty list means no rule is broken.
Address rules
If your shop has address rules, two more fields can appear:
addressRules: the rules that matched, each as{ "id", "action", "field" }.rewrite: the address after your replace rules. This is the address that was checked and thatverdictdescribes. Decide yourself whether to write it back.
Both are absent when no rule matched.
addressHash
A hash of the normalized address. The same address gives the same hash, so you can use it to tell whether a customer changed the address since the last check.
Full reference
The full request and response schema is in the API reference.