API
Validate an email and a phone
Check an email address with POST /v1/emails/validate and a phone number with POST /v1/phones/validate.
Two endpoints check a customer's contact details: POST /v1/emails/validate for an email address and POST /v1/phones/validate for a phone number. Both are charged per check at your shop's price (see Pricing). To check the email and phone of a placed order, pass them with the order instead (see Orders).
Validate an email
The body has one field, email (at most 254 characters).
curl https://api.address-validation.io/v1/emails/validate \
-H "Authorization: Bearer $AVIO_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "email": "jane.doe@gmial.com" }'const response = await fetch("https://api.address-validation.io/v1/emails/validate", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.AVIO_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({ email: "jane.doe@gmial.com" }),
signal: AbortSignal.timeout(5000),
});
if (!response.ok) {
throw new Error(`AVIO ${response.status}: ${(await response.json()).error}`);
}
const emailCheck = await response.json();<?php
$ch = curl_init('https://api.address-validation.io/v1/emails/validate');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => json_encode(['email' => 'jane.doe@gmial.com']),
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);
$emailCheck = json_decode($body, true);
if ($status !== 200) {
throw new RuntimeException("AVIO {$status}: {$emailCheck['error']}");
}import os
import requests
response = requests.post(
"https://api.address-validation.io/v1/emails/validate",
headers={"Authorization": f"Bearer {os.environ['AVIO_API_KEY']}"},
json={"email": "jane.doe@gmial.com"},
timeout=5,
)
response.raise_for_status()
email_check = response.json()The domain has a typo, so the answer suggests a fix:
{
"result": "invalid",
"suggestion": "jane.doe@gmail.com"
}| Field | Meaning |
|---|---|
result |
valid, invalid or unknown (no definite answer). |
reason |
syntax when the address is invalid because it isn't a well-formed email address. |
disposable |
true for a throwaway (disposable) email domain. |
catchAll |
true when the domain accepts mail for any address, so the mailbox itself can't be confirmed. |
risky |
true when the address is deliverable but risky. |
role |
true for a role address such as info@ or sales@. |
suggestion |
A corrected address for a common domain typo, such as gmial.com to gmail.com. |
The flags are only present when they are true. Treat unknown as "don't block": the customer may still have typed a working address.
Validate a phone number
| Field | Description |
|---|---|
phone |
The number as the customer entered it (at most 64 characters). Required. |
countryCode |
ISO alpha-2 country, used for numbers without an international prefix. Optional; usually the shipping country. |
curl https://api.address-validation.io/v1/phones/validate \
-H "Authorization: Bearer $AVIO_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "phone": "030 1234567", "countryCode": "DE" }'const response = await fetch("https://api.address-validation.io/v1/phones/validate", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.AVIO_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({ phone: "030 1234567", countryCode: "DE" }),
signal: AbortSignal.timeout(5000),
});
if (!response.ok) {
throw new Error(`AVIO ${response.status}: ${(await response.json()).error}`);
}
const phoneCheck = await response.json();<?php
$ch = curl_init('https://api.address-validation.io/v1/phones/validate');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => json_encode(['phone' => '030 1234567', 'countryCode' => 'DE']),
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);
$phoneCheck = json_decode($body, true);
if ($status !== 200) {
throw new RuntimeException("AVIO {$status}: {$phoneCheck['error']}");
}import os
import requests
response = requests.post(
"https://api.address-validation.io/v1/phones/validate",
headers={"Authorization": f"Bearer {os.environ['AVIO_API_KEY']}"},
json={"phone": "030 1234567", "countryCode": "DE"},
timeout=5,
)
response.raise_for_status()
phone_check = response.json()A valid number comes back in international format:
{
"result": "valid",
"e164": "+49301234567",
"lineType": "landline"
}| Field | Meaning |
|---|---|
result |
valid, invalid or unknown. |
e164 |
The number in E.164 format. Only present when result is valid; store this form. |
lineType |
mobile, landline, voip or other, when it is known. |
Limits and failures
- Email and phone checks each have their own hourly limit per shop. When it is used up, the endpoint still answers
200, withresult: "unknown". See Rate limits. - These are
POSTrequests and are charged per check, so don't retry them automatically after a timeout. See Retries. - An empty or overlong
emailorphoneanswers400 invalid_body.
Full reference
The full request and response schema is in the API reference.