API
Authentication
Authenticate to the Address Validation iO platform API with a bearer API key, and check which shop a key belongs to.
The Address Validation iO platform API lets your own server validate addresses, emails and phone numbers and check orders. It is the same API the AVIO WooCommerce plugin uses. Every request goes to https://api.address-validation.io, and all endpoints live under /v1.
Get an API key
API keys are issued by the AVIO team. Request one through the API contact form. Each key belongs to one shop (your store), and everything the key does (checks, orders, usage) is counted for that shop.
The key is shown to you once. AVIO stores only a hash of it, so we can't show it again. If you lose it, ask for a new one. A shop can have two active keys at the same time, so you can switch to a new key before the old one is revoked.
A key looks like this:
avk_<shop>_<keyId>_<secret>Treat the whole string as an opaque secret. Store it in an environment variable or your platform's secret store, never in source control. The examples in these docs read it from AVIO_API_KEY.
Send the key
Send the key as a bearer token in the Authorization header of every request:
Authorization: Bearer avk_…Send request bodies as JSON with Content-Type: application/json. Responses are JSON as well.
Note: The API is server to server only. Never put a key in a browser, a mobile app or any code your customers can download. Anyone who has the key can run checks on your account. To validate addresses in the browser, use the headless widget with a short-lived token minted on your server.
Check a key
GET /v1/me returns the shop and the key the request was made with. It costs nothing, so it is a good first call when you set up an integration.
curl https://api.address-validation.io/v1/me \
-H "Authorization: Bearer $AVIO_API_KEY"const response = await fetch("https://api.address-validation.io/v1/me", {
headers: { Authorization: `Bearer ${process.env.AVIO_API_KEY}` },
});
if (!response.ok) {
throw new Error(`AVIO ${response.status}: ${(await response.json()).error}`);
}
const me = await response.json();
console.log(me.shopId, me.name);<?php
$ch = curl_init('https://api.address-validation.io/v1/me');
curl_setopt_array($ch, [
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('AVIO_API_KEY')],
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 5,
]);
$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);
$me = json_decode($body, true);
if ($status !== 200) {
throw new RuntimeException("AVIO {$status}: {$me['error']}");
}
echo $me['shopId'], ' ', $me['name'];import os
import requests
response = requests.get(
"https://api.address-validation.io/v1/me",
headers={"Authorization": f"Bearer {os.environ['AVIO_API_KEY']}"},
timeout=5,
)
response.raise_for_status()
me = response.json()
print(me["shopId"], me["name"])A valid key returns your shop:
{
"shopId": "tn_3f9a1c2b7d4e5f60",
"tenantId": "tn_3f9a1c2b7d4e5f60",
"name": "Example Store",
"platform": "custom",
"storeDomain": "shop.example.com",
"sandbox": false,
"keyId": "k7p2x9",
"apiVersion": "1"
}| Field | Meaning |
|---|---|
shopId |
Your shop's id. |
tenantId |
Deprecated. Always equal to shopId; use shopId. |
name |
The shop's name. |
platform |
woocommerce, shopware or custom. |
storeDomain |
Your store's host. Absent until it is set for your shop. |
sandbox |
true for a test shop. |
keyId |
The id of the key you used (not the secret). |
apiVersion |
Always "1". |
Authentication errors
| Status | error |
What it means |
|---|---|---|
| 401 | missing_api_key |
No Authorization header was sent. |
| 401 | invalid_api_key |
The header is malformed, the key is unknown, or it was revoked. |
| 403 | tenant_suspended |
The key is valid, but API access for the shop is suspended. Contact us. |
See Errors and rate limits for every other error.
What a key can call
This guide section covers the endpoints most integrations need:
- Validate an address:
POST /v1/addresses/validate - Validate an email and a phone:
POST /v1/emails/validate,POST /v1/phones/validate - Orders:
PUT,GETandDELETE /v1/orders/{orderId},POST /v1/orders/{orderId}/correction - Usage:
GET /v1/usage,GET /v1/usage/months
The API also has endpoints for platform integrations that manage a shop's configuration from their own admin: capabilities, connection reports, uninstall, settings, routes, logs, stats and banners. They are listed in the reference.
Two endpoints need no key: GET /v1/health (returns { "ok": true, "version": "1" }) and GET /v1/openapi.json (the OpenAPI 3.1 document of the API).
Full reference
Every operation, with its request and response schema, is in the API reference.