Vai al contenuto
Address Validation iO

Questa documentazione è disponibile solo in inglese.

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" }'

The domain has a typo, so the answer suggests a fix:

JSON
{
  "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" }'

A valid number comes back in international format:

JSON
{
  "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, with result: "unknown". See Rate limits.
  • These are POST requests and are charged per check, so don't retry them automatically after a timeout. See Retries.
  • An empty or overlong email or phone answers 400 invalid_body.

Full reference

The full request and response schema is in the API reference.