Aller au contenu
Address Validation iO

Cette documentation est disponible en anglais uniquement.

API

Référence de l’API

Address Validation iO platform API, version 1. Every operation of the live API, generated from its OpenAPI document. Base URL: https://api.address-validation.io.

https://api.address-validation.io/v1/openapi.json

health

GET/v1/healthNo keyLiveness check

Auth: none

Responses

  • 200HealthOK

Response 200

FieldTypeDescription
ok*true
version*"1"
cURL
curl -X GET 'https://api.address-validation.io/v1/health'

faqs

GET/v1/faqsNo keyThe FAQ staff publish for one surface (tag), in a locale (English fallback). No key; any origin may read it (Access-Control-Allow-Origin: *), cacheable for 5 minutes. Never metered

Auth: none

Parameters

FieldTypeDescription
tag*string (query)Where the questions show One of: shopify, shopware, woocommerce, website.
localestring (query)en, de, fr, es (de-DE works too) are translated, anything else is English; a missing translation is English. Default: en Max 35 characters.

Responses

  • 200FaqsOK
  • 400Errorinvalid_query (with fields): tag missing or unknown

Response 200

FieldTypeDescription
tag*stringOne of: shopify, shopware, woocommerce, website.
locale*stringOne of: en, de, fr, es.
topics*object[]
topics[].id*stringStable; usable as a page anchor
topics[].title*string
topics[].items*object[]
topics[].items[].id*stringStable within its topic
topics[].items[].question*string
topics[].items[].answer*stringPlain text
topics[].items[].linkobject
topics[].items[].link.href*stringAn https:// URL
topics[].items[].link.label*string
cURL
curl -X GET 'https://api.address-validation.io/v1/faqs'

changelog

GET/v1/changelogNo keyWhat changed for merchants, newest first: the product changelog entries staff approved and published, optionally only the lines for one platform. No key; any origin may read it (Access-Control-Allow-Origin: *), cacheable for 5 minutes. Never metered

Auth: none

Parameters

FieldTypeDescription
limitinteger (query)Most entries to read, 1 to 50 (default 20). With platform, entries without a line for it are left out, so a page can hold fewer
beforestring (query)The previous page's nextCursor; absent for the newest entries Max 200 characters.
platformstring (query)Only lines for this platform (api = API shops) One of: shopify, woocommerce, shopware, api.

Responses

  • 200ChangelogOK
  • 400Errorinvalid_query (with fields): limit, before or platform invalid

Response 200

FieldTypeDescription
entries*object[]
entries[].id*stringOpaque id of the entry
entries[].date*stringISO 8601 time the entry is dated
entries[].titlestringPlain text; absent when staff gave none
entries[].items*object[]
entries[].items[].kind*stringOne of: new, improved, fixed.
entries[].items[].text*stringPlain text
entries[].items[].platforms*string[]
nextCursorstringPass as before for older entries; absent on the last page
cURL
curl -X GET 'https://api.address-validation.io/v1/changelog'

status

GET/v1/statusNo keyHealth of Address Validation iO's services and validation providers, for status pages. No key; any origin may read it (Access-Control-Allow-Origin: *), cacheable for 1 minute. Never metered

Auth: none

Responses

  • 200StatusOK

Response 200

FieldTypeDescription
updatedAt*stringWhen the alarm states were read Pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$.
components*object[]
components[].id*stringStable kebab-case: api, order-checks, customer-emails, bulk-checks, <group>-<provider> (e.g. address-loqate)
components[].group*stringOne of: service, address, email, phone.
components[].name*string
components[].status*stringunknown: no recent data (no traffic) or the state could not be read; degraded: slow or partly failing One of: operational, degraded, outage, unknown.
cURL
curl -X GET 'https://api.address-validation.io/v1/status'

me

GET/v1/meThe shop and key of this request

Auth: Authorization: Bearer avk_… (API key)

Responses

  • 200TenantInfoOK
  • 401Errormissing_api_key or invalid_api_key
  • 403Errortenant_suspended: the shop's API access is suspended; not_available: the shop's platform or the caller doesn't run this through the API

Response 200

FieldTypeDescription
shopId*string
tenantId*stringUse shopId (same value).
name*string
platform*stringOne of: woocommerce, shopware, custom.
storeDomainstring
sandbox*boolean
keyId*string
apiVersion*"1"
cURL
curl -X GET 'https://api.address-validation.io/v1/me' \
  -H "Authorization: Bearer $AVIO_API_KEY"

addresses

POST/v1/addresses/validateValidate an address (free, quota-limited; fails open with decision: skipped)

Auth: Authorization: Bearer avk_… (API key)

Request body

FieldTypeDescription
address*object
address.firstNamestring | nullMax 255 characters.
address.lastNamestring | nullMax 255 characters.
address.companystring | nullMax 255 characters.
address.address1string | nullMax 255 characters.
address.address2string | nullMax 255 characters.
address.citystring | nullMax 255 characters.
address.zipstring | nullMax 255 characters.
address.provincestring | nullMax 255 characters.
address.provinceCodestring | nullMax 255 characters.
address.countryCode*stringPattern: ^[A-Za-z]{2}$.
address.phonestring | nullMax 255 characters.
contextstringOne of: checkout, account, other, test.
emailstringMax 254 characters.
providerstringOnly for shops Address Validation iO staff allowed to choose (else 400 provider_override_not_allowed): asks this provider alone, no fallback. One of: loqate, google, postcode-eu, smarty.

Responses

  • 200AddressCheckOK
  • 400Errorinvalid_body; provider_override_not_allowed: provider sent, but the shop may not choose its provider
  • 401Errormissing_api_key or invalid_api_key
  • 403Errortenant_suspended: the shop's API access is suspended; not_available: the shop's platform or the caller doesn't run this through the API
  • 413Errorbody_too_large (over 16 KB)
  • 429Errorrate_limited: the api-test quota of context: test is spent; staff's hourly limit replaces its limit

Response 200

FieldTypeDescription
decision*stringOne of: valid, warn, invalid, skipped.
mode*stringOne of: strict, balanced, loose.
addressHash*string
verdict*object
verdict.status*stringOne of: deliverable, corrected, ambiguous, invalid, unsupported, error.
verdict.provider*stringOne of: loqate, google, postcode-eu, smarty, sandbox.
verdict.granularity*stringOne of: subpremise, premise, street, locality, none.
verdict.changes*object[]
verdict.changes[].field*stringOne of: address1, address2, city, zip, province, provinceCode, countryCode.
verdict.changes[].from*string
verdict.changes[].to*string
verdict.changes[].kind*stringOne of: alias, format, minor, major, inferred.
verdict.missing*string[]
verdict.unverified*string[]
verdict.suggestions*Address[]
verdict.suggestions[].firstNamestring
verdict.suggestions[].lastNamestring
verdict.suggestions[].companystring
verdict.suggestions[].address1*string
verdict.suggestions[].address2string
verdict.suggestions[].city*string
verdict.suggestions[].zipstring
verdict.suggestions[].provincestring
verdict.suggestions[].provinceCodestring
verdict.suggestions[].countryCode*string
verdict.suggestions[].phonestring
verdict.suggestionsProviderstringOne of: loqate, google, postcode-eu, smarty, sandbox.
verdict.blockedstringThe kind of delivery point the shop doesn't ship to (its delivery-point settings): the reason for invalid. Absent otherwise. One of: poBox, parcelLocker.
issues*string[]
rulesobject[]
rules[].code*stringOne of: house_number, zip_format, too_long, po_box, parcel_locker_blocked, parcel_locker, email_invalid, email_disposable, address_rule.
rules[].field*stringOne of: address1, address2, city, zip, province, email.
addressRulesobject[]Every merchant address rule that matched. Absent when none did.
addressRules[].id*string
addressRules[].action*stringOne of: flag, block, replace, skip.
addressRules[].field*stringOne of: address1, address2, city, zip, province.
rewriteobject
rewrite.firstNamestring
rewrite.lastNamestring
rewrite.companystring
rewrite.address1*string
rewrite.address2string
rewrite.city*string
rewrite.zipstring
rewrite.provincestring
rewrite.provinceCodestring
rewrite.countryCode*string
rewrite.phonestring
cURL
curl -X POST 'https://api.address-validation.io/v1/addresses/validate' \
  -H "Authorization: Bearer $AVIO_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"address":{"countryCode":"DE"}}'

emails

POST/v1/emails/validateValidate an email address

Auth: Authorization: Bearer avk_… (API key)

Request body

FieldTypeDescription
email*stringMax 254 characters.
providerstringOnly for shops Address Validation iO staff allowed to choose (else 400 provider_override_not_allowed): asks this provider alone, no fallback. One of: bouncer, ses, loqate.

Responses

  • 200EmailCheckResultOK
  • 400Errorinvalid_body; provider_override_not_allowed: provider sent, but the shop may not choose its provider
  • 401Errormissing_api_key or invalid_api_key
  • 403Errortenant_suspended: the shop's API access is suspended; not_available: the shop's platform or the caller doesn't run this through the API
  • 413Errorbody_too_large (over 16 KB)

Response 200

FieldTypeDescription
result*stringOne of: valid, invalid, unknown.
reason"syntax"
disposableboolean
catchAllboolean
riskyboolean
roleboolean
suggestionstring
cURL
curl -X POST 'https://api.address-validation.io/v1/emails/validate' \
  -H "Authorization: Bearer $AVIO_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"email":"string"}'

phones

POST/v1/phones/validateValidate a phone number

Auth: Authorization: Bearer avk_… (API key)

Request body

FieldTypeDescription
phone*stringMax 64 characters.
countryCodestringPattern: ^[A-Za-z]{2}$.
providerstringOnly for shops Address Validation iO staff allowed to choose (else 400 provider_override_not_allowed): asks this provider alone, no fallback. One of: offline, aws, loqate.

Responses

  • 200PhoneCheckResultOK
  • 400Errorinvalid_body; provider_override_not_allowed: provider sent, but the shop may not choose its provider
  • 401Errormissing_api_key or invalid_api_key
  • 403Errortenant_suspended: the shop's API access is suspended; not_available: the shop's platform or the caller doesn't run this through the API
  • 413Errorbody_too_large (over 16 KB)

Response 200

FieldTypeDescription
result*stringOne of: valid, invalid, unknown.
e164string
lineTypestring
cURL
curl -X POST 'https://api.address-validation.io/v1/phones/validate' \
  -H "Authorization: Bearer $AVIO_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"phone":"string"}'

orders

GET/v1/orders/{orderId}The stored order result

Auth: Authorization: Bearer avk_… (API key)

Parameters

FieldTypeDescription
orderId*string (path)The platform's order id (URL-encoded). Pattern: ^[A-Za-z0-9._:-]{1,64}$.

Responses

  • 200OrderResultOK
  • 400Errorinvalid_order_id
  • 401Errormissing_api_key or invalid_api_key
  • 403Errortenant_suspended: the shop's API access is suspended; not_available: the shop's platform or the caller doesn't run this through the API
  • 404Errororder_not_found

Response 200

FieldTypeDescription
orderId*string
orderNumberstring
decision*stringOne of: valid, warn, invalid, skipped.
status*stringOne of: validated, fixed, confirmed.
address*object
address.firstNamestring
address.lastNamestring
address.companystring
address.address1*string
address.address2string
address.city*string
address.zipstring
address.provincestring
address.provinceCodestring
address.countryCode*string
address.phonestring
addressHash*string
verdict*object
verdict.status*stringOne of: deliverable, corrected, ambiguous, invalid, unsupported, error.
verdict.provider*stringOne of: loqate, google, postcode-eu, smarty, sandbox.
verdict.granularity*stringOne of: subpremise, premise, street, locality, none.
verdict.changes*object[]
verdict.changes[].field*stringOne of: address1, address2, city, zip, province, provinceCode, countryCode.
verdict.changes[].from*string
verdict.changes[].to*string
verdict.changes[].kind*stringOne of: alias, format, minor, major, inferred.
verdict.missing*string[]
verdict.unverified*string[]
verdict.suggestions*Address[]
verdict.suggestions[].firstNamestring
verdict.suggestions[].lastNamestring
verdict.suggestions[].companystring
verdict.suggestions[].address1*string
verdict.suggestions[].address2string
verdict.suggestions[].city*string
verdict.suggestions[].zipstring
verdict.suggestions[].provincestring
verdict.suggestions[].provinceCodestring
verdict.suggestions[].countryCode*string
verdict.suggestions[].phonestring
verdict.suggestionsProviderstringOne of: loqate, google, postcode-eu, smarty, sandbox.
issues*string[]
billingobject
billing.decision*stringOne of: valid, warn, invalid, skipped.
billing.verdict*object
billing.verdict.status*stringOne of: deliverable, corrected, ambiguous, invalid, unsupported, error.
billing.verdict.provider*stringOne of: loqate, google, postcode-eu, smarty, sandbox.
billing.verdict.granularity*stringOne of: subpremise, premise, street, locality, none.
billing.verdict.changes*object[]
billing.verdict.changes[].field*stringOne of: address1, address2, city, zip, province, provinceCode, countryCode.
billing.verdict.changes[].from*string
billing.verdict.changes[].to*string
billing.verdict.changes[].kind*stringOne of: alias, format, minor, major, inferred.
billing.verdict.missing*string[]
billing.verdict.unverified*string[]
billing.verdict.suggestions*Address[]
billing.verdict.suggestions[].firstNamestring
billing.verdict.suggestions[].lastNamestring
billing.verdict.suggestions[].companystring
billing.verdict.suggestions[].address1*string
billing.verdict.suggestions[].address2string
billing.verdict.suggestions[].city*string
billing.verdict.suggestions[].zipstring
billing.verdict.suggestions[].provincestring
billing.verdict.suggestions[].provinceCodestring
billing.verdict.suggestions[].countryCode*string
billing.verdict.suggestions[].phonestring
billing.verdict.suggestionsProviderstringOne of: loqate, google, postcode-eu, smarty, sandbox.
emailobject
email.result*stringOne of: valid, invalid, unknown.
email.reason"syntax"
email.disposableboolean
email.catchAllboolean
email.riskyboolean
email.roleboolean
email.suggestionstring
phoneobject
phone.result*stringOne of: valid, invalid, unknown.
phone.e164string
phone.lineTypestring
validatedAt*string
correctedAtstring
correctableUntilstring
metered*boolean
addressRulesobject[]Every merchant address rule that matched. Absent when none did.
addressRules[].id*string
addressRules[].action*stringOne of: flag, block, replace, skip.
addressRules[].field*stringOne of: address1, address2, city, zip, province.
rewriteobject
rewrite.firstNamestring
rewrite.lastNamestring
rewrite.companystring
rewrite.address1*string
rewrite.address2string
rewrite.city*string
rewrite.zipstring
rewrite.provincestring
rewrite.provinceCodestring
rewrite.countryCode*string
rewrite.phonestring
cURL
curl -X GET 'https://api.address-validation.io/v1/orders/{orderId}' \
  -H "Authorization: Bearer $AVIO_API_KEY"
PUT/v1/orders/{orderId}Validate and store an order (idempotent by id and shipping address; metered once)

Auth: Authorization: Bearer avk_… (API key)

Parameters

FieldTypeDescription
orderId*string (path)The platform's order id (URL-encoded). Pattern: ^[A-Za-z0-9._:-]{1,64}$.

Request body

FieldTypeDescription
orderNumberstringMax 64 characters.
shippingAddress*object
shippingAddress.firstNamestring | nullMax 255 characters.
shippingAddress.lastNamestring | nullMax 255 characters.
shippingAddress.companystring | nullMax 255 characters.
shippingAddress.address1string | nullMax 255 characters.
shippingAddress.address2string | nullMax 255 characters.
shippingAddress.citystring | nullMax 255 characters.
shippingAddress.zipstring | nullMax 255 characters.
shippingAddress.provincestring | nullMax 255 characters.
shippingAddress.provinceCodestring | nullMax 255 characters.
shippingAddress.countryCode*stringPattern: ^[A-Za-z]{2}$.
shippingAddress.phonestring | nullMax 255 characters.
billingAddressobject
billingAddress.firstNamestring | nullMax 255 characters.
billingAddress.lastNamestring | nullMax 255 characters.
billingAddress.companystring | nullMax 255 characters.
billingAddress.address1string | nullMax 255 characters.
billingAddress.address2string | nullMax 255 characters.
billingAddress.citystring | nullMax 255 characters.
billingAddress.zipstring | nullMax 255 characters.
billingAddress.provincestring | nullMax 255 characters.
billingAddress.provinceCodestring | nullMax 255 characters.
billingAddress.countryCode*stringPattern: ^[A-Za-z]{2}$.
billingAddress.phonestring | nullMax 255 characters.
emailstringMax 254 characters.
checkEmailboolean
phonestringMax 64 characters.
checkPhoneboolean
forceboolean

Responses

  • 200OrderResultOK
  • 400Errorinvalid_body or invalid_order_id
  • 401Errormissing_api_key or invalid_api_key
  • 403Errortenant_suspended: the shop's API access is suspended; not_available: the shop's platform or the caller doesn't run this through the API
  • 409Errororder_conflict: another address was saved during the request, or the order erased; send the order as it is now
  • 413Errorbody_too_large (over 16 KB)

Response 200

FieldTypeDescription
orderId*string
orderNumberstring
decision*stringOne of: valid, warn, invalid, skipped.
status*stringOne of: validated, fixed, confirmed.
address*object
address.firstNamestring
address.lastNamestring
address.companystring
address.address1*string
address.address2string
address.city*string
address.zipstring
address.provincestring
address.provinceCodestring
address.countryCode*string
address.phonestring
addressHash*string
verdict*object
verdict.status*stringOne of: deliverable, corrected, ambiguous, invalid, unsupported, error.
verdict.provider*stringOne of: loqate, google, postcode-eu, smarty, sandbox.
verdict.granularity*stringOne of: subpremise, premise, street, locality, none.
verdict.changes*object[]
verdict.changes[].field*stringOne of: address1, address2, city, zip, province, provinceCode, countryCode.
verdict.changes[].from*string
verdict.changes[].to*string
verdict.changes[].kind*stringOne of: alias, format, minor, major, inferred.
verdict.missing*string[]
verdict.unverified*string[]
verdict.suggestions*Address[]
verdict.suggestions[].firstNamestring
verdict.suggestions[].lastNamestring
verdict.suggestions[].companystring
verdict.suggestions[].address1*string
verdict.suggestions[].address2string
verdict.suggestions[].city*string
verdict.suggestions[].zipstring
verdict.suggestions[].provincestring
verdict.suggestions[].provinceCodestring
verdict.suggestions[].countryCode*string
verdict.suggestions[].phonestring
verdict.suggestionsProviderstringOne of: loqate, google, postcode-eu, smarty, sandbox.
issues*string[]
billingobject
billing.decision*stringOne of: valid, warn, invalid, skipped.
billing.verdict*object
billing.verdict.status*stringOne of: deliverable, corrected, ambiguous, invalid, unsupported, error.
billing.verdict.provider*stringOne of: loqate, google, postcode-eu, smarty, sandbox.
billing.verdict.granularity*stringOne of: subpremise, premise, street, locality, none.
billing.verdict.changes*object[]
billing.verdict.changes[].field*stringOne of: address1, address2, city, zip, province, provinceCode, countryCode.
billing.verdict.changes[].from*string
billing.verdict.changes[].to*string
billing.verdict.changes[].kind*stringOne of: alias, format, minor, major, inferred.
billing.verdict.missing*string[]
billing.verdict.unverified*string[]
billing.verdict.suggestions*Address[]
billing.verdict.suggestions[].firstNamestring
billing.verdict.suggestions[].lastNamestring
billing.verdict.suggestions[].companystring
billing.verdict.suggestions[].address1*string
billing.verdict.suggestions[].address2string
billing.verdict.suggestions[].city*string
billing.verdict.suggestions[].zipstring
billing.verdict.suggestions[].provincestring
billing.verdict.suggestions[].provinceCodestring
billing.verdict.suggestions[].countryCode*string
billing.verdict.suggestions[].phonestring
billing.verdict.suggestionsProviderstringOne of: loqate, google, postcode-eu, smarty, sandbox.
emailobject
email.result*stringOne of: valid, invalid, unknown.
email.reason"syntax"
email.disposableboolean
email.catchAllboolean
email.riskyboolean
email.roleboolean
email.suggestionstring
phoneobject
phone.result*stringOne of: valid, invalid, unknown.
phone.e164string
phone.lineTypestring
validatedAt*string
correctedAtstring
correctableUntilstring
metered*boolean
addressRulesobject[]Every merchant address rule that matched. Absent when none did.
addressRules[].id*string
addressRules[].action*stringOne of: flag, block, replace, skip.
addressRules[].field*stringOne of: address1, address2, city, zip, province.
rewriteobject
rewrite.firstNamestring
rewrite.lastNamestring
rewrite.companystring
rewrite.address1*string
rewrite.address2string
rewrite.city*string
rewrite.zipstring
rewrite.provincestring
rewrite.provinceCodestring
rewrite.countryCode*string
rewrite.phonestring
cURL
curl -X PUT 'https://api.address-validation.io/v1/orders/{orderId}' \
  -H "Authorization: Bearer $AVIO_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"shippingAddress":{"countryCode":"DE"}}'
DELETE/v1/orders/{orderId}Erase the order and its logs (GDPR)

Auth: Authorization: Bearer avk_… (API key)

Parameters

FieldTypeDescription
orderId*string (path)The platform's order id (URL-encoded). Pattern: ^[A-Za-z0-9._:-]{1,64}$.

Responses

  • 200DeletedOK
  • 400Errorinvalid_order_id
  • 401Errormissing_api_key or invalid_api_key
  • 403Errortenant_suspended: the shop's API access is suspended; not_available: the shop's platform or the caller doesn't run this through the API

Response 200

FieldTypeDescription
deleted*true
cURL
curl -X DELETE 'https://api.address-validation.io/v1/orders/{orderId}' \
  -H "Authorization: Bearer $AVIO_API_KEY"
POST/v1/orders/{orderId}/correctionThe customer's correction (by: admin: staff applied a suggestion): confirmed when unchanged, else fixed

Auth: Authorization: Bearer avk_… (API key)

Parameters

FieldTypeDescription
orderId*string (path)The platform's order id (URL-encoded). Pattern: ^[A-Za-z0-9._:-]{1,64}$.

Request body

FieldTypeDescription
address*object
address.firstNamestring | nullMax 255 characters.
address.lastNamestring | nullMax 255 characters.
address.companystring | nullMax 255 characters.
address.address1string | nullMax 255 characters.
address.address2string | nullMax 255 characters.
address.citystring | nullMax 255 characters.
address.zipstring | nullMax 255 characters.
address.provincestring | nullMax 255 characters.
address.provinceCodestring | nullMax 255 characters.
address.countryCode*stringPattern: ^[A-Za-z]{2}$.
address.phonestring | nullMax 255 characters.
bystringOne of: customer, admin.

Responses

  • 200OrderResultOK
  • 400Errorinvalid_body or invalid_order_id
  • 401Errormissing_api_key or invalid_api_key
  • 403Errortenant_suspended: the shop's API access is suspended; not_available: the shop's platform or the caller doesn't run this through the API
  • 404Errororder_not_found
  • 409Errororder_conflict: another save won (not this correction's double submit); send it again as the order is now
  • 413Errorbody_too_large (over 16 KB)
  • 429Errorrate_limited

Response 200

FieldTypeDescription
orderId*string
orderNumberstring
decision*stringOne of: valid, warn, invalid, skipped.
status*stringOne of: validated, fixed, confirmed.
address*object
address.firstNamestring
address.lastNamestring
address.companystring
address.address1*string
address.address2string
address.city*string
address.zipstring
address.provincestring
address.provinceCodestring
address.countryCode*string
address.phonestring
addressHash*string
verdict*object
verdict.status*stringOne of: deliverable, corrected, ambiguous, invalid, unsupported, error.
verdict.provider*stringOne of: loqate, google, postcode-eu, smarty, sandbox.
verdict.granularity*stringOne of: subpremise, premise, street, locality, none.
verdict.changes*object[]
verdict.changes[].field*stringOne of: address1, address2, city, zip, province, provinceCode, countryCode.
verdict.changes[].from*string
verdict.changes[].to*string
verdict.changes[].kind*stringOne of: alias, format, minor, major, inferred.
verdict.missing*string[]
verdict.unverified*string[]
verdict.suggestions*Address[]
verdict.suggestions[].firstNamestring
verdict.suggestions[].lastNamestring
verdict.suggestions[].companystring
verdict.suggestions[].address1*string
verdict.suggestions[].address2string
verdict.suggestions[].city*string
verdict.suggestions[].zipstring
verdict.suggestions[].provincestring
verdict.suggestions[].provinceCodestring
verdict.suggestions[].countryCode*string
verdict.suggestions[].phonestring
verdict.suggestionsProviderstringOne of: loqate, google, postcode-eu, smarty, sandbox.
issues*string[]
billingobject
billing.decision*stringOne of: valid, warn, invalid, skipped.
billing.verdict*object
billing.verdict.status*stringOne of: deliverable, corrected, ambiguous, invalid, unsupported, error.
billing.verdict.provider*stringOne of: loqate, google, postcode-eu, smarty, sandbox.
billing.verdict.granularity*stringOne of: subpremise, premise, street, locality, none.
billing.verdict.changes*object[]
billing.verdict.changes[].field*stringOne of: address1, address2, city, zip, province, provinceCode, countryCode.
billing.verdict.changes[].from*string
billing.verdict.changes[].to*string
billing.verdict.changes[].kind*stringOne of: alias, format, minor, major, inferred.
billing.verdict.missing*string[]
billing.verdict.unverified*string[]
billing.verdict.suggestions*Address[]
billing.verdict.suggestions[].firstNamestring
billing.verdict.suggestions[].lastNamestring
billing.verdict.suggestions[].companystring
billing.verdict.suggestions[].address1*string
billing.verdict.suggestions[].address2string
billing.verdict.suggestions[].city*string
billing.verdict.suggestions[].zipstring
billing.verdict.suggestions[].provincestring
billing.verdict.suggestions[].provinceCodestring
billing.verdict.suggestions[].countryCode*string
billing.verdict.suggestions[].phonestring
billing.verdict.suggestionsProviderstringOne of: loqate, google, postcode-eu, smarty, sandbox.
emailobject
email.result*stringOne of: valid, invalid, unknown.
email.reason"syntax"
email.disposableboolean
email.catchAllboolean
email.riskyboolean
email.roleboolean
email.suggestionstring
phoneobject
phone.result*stringOne of: valid, invalid, unknown.
phone.e164string
phone.lineTypestring
validatedAt*string
correctedAtstring
correctableUntilstring
metered*boolean
addressRulesobject[]Every merchant address rule that matched. Absent when none did.
addressRules[].id*string
addressRules[].action*stringOne of: flag, block, replace, skip.
addressRules[].field*stringOne of: address1, address2, city, zip, province.
rewriteobject
rewrite.firstNamestring
rewrite.lastNamestring
rewrite.companystring
rewrite.address1*string
rewrite.address2string
rewrite.city*string
rewrite.zipstring
rewrite.provincestring
rewrite.provinceCodestring
rewrite.countryCode*string
rewrite.phonestring
cURL
curl -X POST 'https://api.address-validation.io/v1/orders/{orderId}/correction' \
  -H "Authorization: Bearer $AVIO_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"address":{"countryCode":"DE"}}'
GET/v1/orders/{orderId}/logsThe order's history, oldest first (at most 300 rows; none for an unknown order)

Auth: Authorization: Bearer avk_… (API key)

Parameters

FieldTypeDescription
orderId*string (path)The platform's order id (URL-encoded). Pattern: ^[A-Za-z0-9._:-]{1,64}$.

Responses

  • 200OrderLogsOK
  • 400Errorinvalid_order_id
  • 401Errormissing_api_key or invalid_api_key
  • 403Errortenant_suspended: the shop's API access is suspended; not_available: the shop's platform or the caller doesn't run this through the API
  • 429Errorrate_limited (shared with GET /v1/logs)

Response 200

FieldTypeDescription
items*LogRow[]
items[].id*string
items[].at*string
items[].kind*stringOne of: validation, address, correction, email, phone, hold, tag, flow, billing, settings, app, error.
items[].level*stringOne of: info, warning, error.
items[].code*string
items[].paramsobject
items[].orderIdstring
items[].orderNamestring
items[].sourcestringOne of: checkout, order-created, order-updated, admin, bulk, flow, customer, widget-address, test, ab-test.
items[].decisionstringOne of: valid, warn, invalid, skipped.
items[].previousDecisionstringOne of: valid, warn, invalid, skipped.
items[].countryCodestring
items[].providersobject[]
items[].providers[].provider*string
items[].providers[].status*string
items[].providers[].latencyMs*number
items[].cachedboolean
items[].actorobject
items[].actor.type*stringOne of: merchant, customer, avio, system, platform-api.
items[].changesobject[]
items[].changes[].field*string
items[].changes[].fromstring
items[].changes[].tostring
items[].recipientChangedboolean
items[].tagsobject
items[].tags.added*string[]
items[].tags.removed*string[]
cURL
curl -X GET 'https://api.address-validation.io/v1/orders/{orderId}/logs' \
  -H "Authorization: Bearer $AVIO_API_KEY"

usage

GET/v1/usageMetered usage of one month (UTC) and the shop's current prices

Auth: Authorization: Bearer avk_… (API key)

Parameters

FieldTypeDescription
periodstring (query)yyyy-mm, default: the current month Pattern: ^\d{4}-(0[1-9]|1[0-2])$.

Responses

  • 200UsageWithPricesOK
  • 400Errorinvalid_period
  • 401Errormissing_api_key or invalid_api_key
  • 403Errortenant_suspended: the shop's API access is suspended; not_available: the shop's platform or the caller doesn't run this through the API

Response 200

FieldTypeDescription
period*string
currency*"USD"
addressChecks*number
providerChecks*number
orders*number
freeOrders*numberThe part of orders the store's one-time free checks covered: verified, never billed.
repeatOrders*number
accruedMicros*number
emailChecks*number
phoneChecks*number
repeatSavedMicros*number
accruedCounted*booleanfalse while the month has no running charge total (nothing charged yet, or a month carried over from the old app): accruedMicros is 0 then.
byProvider*objectaddressChecks per provider that answered. Counts only.
emailByProvider*objectEmail checks of every source per provider that answered (unknown: no definite answer, test: the admin's comparison), counted since 2026-10-11.
phoneByProvider*objectPhone checks as emailByProvider.
meteredEmailChecks*number
meteredPhoneChecks*number
emailAccruedMicros*number
phoneAccruedMicros*number
prices*object
prices.verifiedOrderMicros*number
prices.verifiedOrderFrom*boolean
prices.includedPerMonth*number
prices.repeatDiscountPercent*number
prices.emailCheckMicros*number
prices.phoneCheckMicros*number
metering*stringaccrual: the charged prices accrue and are not invoiced yet. shopify-billing: Shopify usage records bill them. One of: accrual, shopify-billing.
countersSince*stringThe UTC day from which the shop's daily charges are counted: the stats' accruedMicros, and with it the savings, leave out the days before it.
cURL
curl -X GET 'https://api.address-validation.io/v1/usage' \
  -H "Authorization: Bearer $AVIO_API_KEY"
GET/v1/usage/monthsThe usage of the latest months, newest first; a month without usage is all zeros

Auth: Authorization: Bearer avk_… (API key)

Parameters

FieldTypeDescription
countinteger (query)How many months, starting with the current one. Default: 12.

Responses

  • 200UsageMonthsOK
  • 400Errorinvalid_query (with fields: ["count"])
  • 401Errormissing_api_key or invalid_api_key
  • 403Errortenant_suspended: the shop's API access is suspended; not_available: the shop's platform or the caller doesn't run this through the API
  • 429Errorrate_limited (shared with GET /v1/logs)

Response 200

FieldTypeDescription
months*Usage[]
months[].period*string
months[].currency*"USD"
months[].addressChecks*number
months[].providerChecks*number
months[].orders*number
months[].freeOrders*numberThe part of orders the store's one-time free checks covered: verified, never billed.
months[].repeatOrders*number
months[].accruedMicros*number
months[].emailChecks*number
months[].phoneChecks*number
months[].repeatSavedMicros*number
months[].accruedCounted*booleanfalse while the month has no running charge total (nothing charged yet, or a month carried over from the old app): accruedMicros is 0 then.
months[].byProvider*objectaddressChecks per provider that answered. Counts only.
months[].emailByProvider*objectEmail checks of every source per provider that answered (unknown: no definite answer, test: the admin's comparison), counted since 2026-10-11.
months[].phoneByProvider*objectPhone checks as emailByProvider.
months[].meteredEmailChecks*number
months[].meteredPhoneChecks*number
months[].emailAccruedMicros*number
months[].phoneAccruedMicros*number
metering*stringaccrual: the charged prices accrue and are not invoiced yet. shopify-billing: Shopify usage records bill them. One of: accrual, shopify-billing.
countersSince*stringThe UTC day from which the shop's daily charges are counted: the stats' accruedMicros, and with it the savings, leave out the days before it.
cURL
curl -X GET 'https://api.address-validation.io/v1/usage/months' \
  -H "Authorization: Bearer $AVIO_API_KEY"

capabilities

GET/v1/capabilitiesWhat the shop can use: checks, providers with charged prices, settings areas and every feature with how it runs on the shop's platform

Auth: Authorization: Bearer avk_… (API key)

Responses

  • 200CapabilitiesOK
  • 401Errormissing_api_key or invalid_api_key
  • 403Errortenant_suspended: the shop's API access is suspended; not_available: the shop's platform or the caller doesn't run this through the API

Response 200

FieldTypeDescription
apiVersion*"1"
shop*object
shop.shopId*string
shop.platform*stringOne of: shopify, woocommerce, shopware, custom.
shop.sandbox*boolean
shop.validating*boolean
shop.installation*object
shop.installation.state*stringOne of: pending, connected, uninstalled, suspended.
shop.installation.proof*stringOne of: shopify-oauth, shopware-app, api-key.
shop.installation.connectedAtstring
shop.installation.lastSeenDaystring
shop.installation.clientobject
shop.installation.client.name*string
shop.installation.client.version*string
shop.installation.platformVersionstring
planobject
plan.id*stringOne of: payg, starter, business, pro, enterprise.
plan.packages*object[]
plan.packages[].id*stringOne of: fulfillmentHolds, flow, insights, headlessWidget.
plan.packages[].active*boolean
plan.addons*object
plan.addons.email*boolean
plan.addons.phone*boolean
checks*object
checks.address*object
checks.address.contexts*string[]
checks.address.modes*string[]
checks.address.countries*string[]
checks.address.providers*object[]
checks.address.providers[].id*stringOne of: loqate, google, postcode-eu, smarty, sandbox.
checks.address.providers[].name*string
checks.address.providers[].countries*string[] | "*"
checks.address.providers[].capabilities*string[]
checks.address.providers[].region*stringOne of: UK/EU, Global, EU.
checks.address.providers[].priceMicros*number
checks.address.deliveryPointKinds*string[]
checks.address.zipRuleCountries*string[]
checks.email*object
checks.email.providers*object[]
checks.email.providers[].id*string
checks.email.providers[].name*string
checks.email.providers[].capabilities*string[]
checks.email.providers[].priceMicros*number
checks.phone*object
checks.phone.providers*object[]
checks.phone.providers[].id*string
checks.phone.providers[].name*string
checks.phone.providers[].capabilities*string[]
checks.phone.providers[].priceMicros*number
prices*object
prices.verifiedOrderMicros*number
prices.verifiedOrderFrom*boolean
prices.includedPerMonth*number
prices.repeatDiscountPercent*number
prices.emailCheckMicros*number
prices.phoneCheckMicros*number
settings*object
settings.areas*string[]
settings.storeFieldsstring[]
features*object[]
features[].id*stringOne of: address-check, checkout-check, checkout-rules, address-rules, order-check, email-check, phone-check, hold, order-tags, correction, customer-emails, flow, bulk-check, ab-tests, insights, headless-widget.
features[].execution*stringOne of: avio, client, native, unsupported.
features[].available*boolean
features[].gateobject
features[].gate.packagestringOne of: fulfillmentHolds, flow, insights, headlessWidget.
features[].gate.addonstringOne of: email, phone.
features[].reasonstringOne of: platform, planned, needs_invoicing.
features[].configobject[]
features[].config[].area*stringOne of: orders, delivery-points, checkout, address-rules, contact, analytics, store, holds, emails, accounts, general, widget, default-mode.
features[].config[].fields*string[]
cURL
curl -X GET 'https://api.address-validation.io/v1/capabilities' \
  -H "Authorization: Bearer $AVIO_API_KEY"

connection

PUT/v1/connectionReport the integration (on key save, version change and daily); answers the capabilities. Writes only what changed

Auth: Authorization: Bearer avk_… (API key)

Request body

FieldTypeDescription
client*stringMax 100 characters.
clientVersion*stringMax 100 characters.
platformVersionstringMax 100 characters.
storeUrlstringMax 100 characters.

Responses

  • 200CapabilitiesOK
  • 400Errorinvalid_body (with fields)
  • 401Errormissing_api_key or invalid_api_key
  • 403Errortenant_suspended: the shop's API access is suspended; not_available: the shop's platform or the caller doesn't run this through the API
  • 413Errorbody_too_large (over 16 KB)

Response 200

FieldTypeDescription
apiVersion*"1"
shop*object
shop.shopId*string
shop.platform*stringOne of: shopify, woocommerce, shopware, custom.
shop.sandbox*boolean
shop.validating*boolean
shop.installation*object
shop.installation.state*stringOne of: pending, connected, uninstalled, suspended.
shop.installation.proof*stringOne of: shopify-oauth, shopware-app, api-key.
shop.installation.connectedAtstring
shop.installation.lastSeenDaystring
shop.installation.clientobject
shop.installation.client.name*string
shop.installation.client.version*string
shop.installation.platformVersionstring
planobject
plan.id*stringOne of: payg, starter, business, pro, enterprise.
plan.packages*object[]
plan.packages[].id*stringOne of: fulfillmentHolds, flow, insights, headlessWidget.
plan.packages[].active*boolean
plan.addons*object
plan.addons.email*boolean
plan.addons.phone*boolean
checks*object
checks.address*object
checks.address.contexts*string[]
checks.address.modes*string[]
checks.address.countries*string[]
checks.address.providers*object[]
checks.address.providers[].id*stringOne of: loqate, google, postcode-eu, smarty, sandbox.
checks.address.providers[].name*string
checks.address.providers[].countries*string[] | "*"
checks.address.providers[].capabilities*string[]
checks.address.providers[].region*stringOne of: UK/EU, Global, EU.
checks.address.providers[].priceMicros*number
checks.address.deliveryPointKinds*string[]
checks.address.zipRuleCountries*string[]
checks.email*object
checks.email.providers*object[]
checks.email.providers[].id*string
checks.email.providers[].name*string
checks.email.providers[].capabilities*string[]
checks.email.providers[].priceMicros*number
checks.phone*object
checks.phone.providers*object[]
checks.phone.providers[].id*string
checks.phone.providers[].name*string
checks.phone.providers[].capabilities*string[]
checks.phone.providers[].priceMicros*number
prices*object
prices.verifiedOrderMicros*number
prices.verifiedOrderFrom*boolean
prices.includedPerMonth*number
prices.repeatDiscountPercent*number
prices.emailCheckMicros*number
prices.phoneCheckMicros*number
settings*object
settings.areas*string[]
settings.storeFieldsstring[]
features*object[]
features[].id*stringOne of: address-check, checkout-check, checkout-rules, address-rules, order-check, email-check, phone-check, hold, order-tags, correction, customer-emails, flow, bulk-check, ab-tests, insights, headless-widget.
features[].execution*stringOne of: avio, client, native, unsupported.
features[].available*boolean
features[].gateobject
features[].gate.packagestringOne of: fulfillmentHolds, flow, insights, headlessWidget.
features[].gate.addonstringOne of: email, phone.
features[].reasonstringOne of: platform, planned, needs_invoicing.
features[].configobject[]
features[].config[].area*stringOne of: orders, delivery-points, checkout, address-rules, contact, analytics, store, holds, emails, accounts, general, widget, default-mode.
features[].config[].fields*string[]
cURL
curl -X PUT 'https://api.address-validation.io/v1/connection' \
  -H "Authorization: Bearer $AVIO_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"client":"string","clientVersion":"string"}'

uninstall

POST/v1/uninstallThe integration was deleted: marks the shop uninstalled and, unless keepData, erases its orders, their logs and the check details in the analytics archive (bounded; the rest expires; the pseudonymous general part of the archive stays until its 400 days are up). Keys stay valid; the next connection report reinstalls. Idempotent

Auth: Authorization: Bearer avk_… (API key)

Request body

FieldTypeDescription
keepDataboolean

Responses

  • 200UninstallResultOK
  • 400Errorinvalid_body (with fields)
  • 401Errormissing_api_key or invalid_api_key
  • 403Errortenant_suspended: the shop's API access is suspended; not_available: the shop's platform or the caller doesn't run this through the API
  • 413Errorbody_too_large (over 16 KB)

Response 200

FieldTypeDescription
state*"uninstalled"
keepData*boolean
cURL
curl -X POST 'https://api.address-validation.io/v1/uninstall' \
  -H "Authorization: Bearer $AVIO_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"keepData":true}'

settings

GET/v1/settingsThe shop's settings, their version and the choices (charged prices only)

Auth: Authorization: Bearer avk_… (API key)

Responses

  • 200PlatformSettingsOK
  • 401Errormissing_api_key or invalid_api_key
  • 403Errortenant_suspended: the shop's API access is suspended; not_available: the shop's platform or the caller doesn't run this through the API

Response 200

FieldTypeDescription
version*string | null
orders*object
orders.ignoreAddress2*boolean
orders.correctionLockobjectWhen customers can no longer change an order's address. stage: the fulfillment stage from which on (Shopify and Shopware only; absent on a save: the platform's default, which a read always shows); a shipped order always locks. afterHours: 1 to 1440 hours after the order was placed; absent: no time limit. A read always answers it.
orders.correctionLock.stagestringOne of: requested, in_progress, partially_fulfilled, fulfilled.
orders.correctionLock.afterHoursinteger
orders.validateBillingboolean
orders.channelsstring[]Sales channels whose orders Address Validation iO checks: a source name such as web, or an app's numeric id. A Shopify shop's read can still answer a value saved in the old app's form (gid://shopify/App/<id>), which a save refuses, until a save sends channels.
orders.orderTagsobject
orders.orderTags.enabled*boolean
orders.orderTags.prefix*string
orders.orderTags.format*stringMax 40 characters.
orders.orderTags.words*object
orders.orderTags.words.valid*stringMax 40 characters.
orders.orderTags.words.warn*stringMax 40 characters.
orders.orderTags.words.invalid*stringMax 40 characters.
orders.orderTags.words.unsupported*stringMax 40 characters.
orders.orderTags.words.skipped*stringMax 40 characters.
orders.orderTags.words.manual*stringMax 40 characters.
orders.orderTags.words.confirmed*stringMax 40 characters.
orders.orderTags.words.postBox*stringMax 40 characters.
orders.orderTags.words.emailValid*stringMax 40 characters.
orders.orderTags.words.emailInvalid*stringMax 40 characters.
orders.orderTags.words.emailUnknown*stringMax 40 characters.
orders.orderTags.words.phoneValid*stringMax 40 characters.
orders.orderTags.words.phoneInvalid*stringMax 40 characters.
orders.orderTags.words.phoneUnknown*stringMax 40 characters.
deliveryPoints*object
deliveryPoints.default*object
deliveryPoints.default.poBox*stringOne of: allow, block.
deliveryPoints.default.parcelLocker*stringOne of: allow, block.
deliveryPoints.countries*object
checkout*object
checkout.houseNumberCountries*string[]
checkout.zipCountries*string[]
checkout.maxAddressLength*number
checkout.blockInvalidEmail*boolean
checkout.blockDisposableEmail*boolean
checkout.verifyEnabledboolean
checkout.blockOnInvalidboolean
checkout.autocompleteEnabledbooleanAddress Validation iO's address suggestions in Shopify checkout (Plus only, also selected in the checkout editor). A read answers false until it is turned on.
addressRules*object
addressRules.rules*object[]
addressRules.rules[].id*string
addressRules.rules[].field*stringOne of: address, address1, address2, city, zip, province.
addressRules.rules[].match*stringOne of: contains, word, equals, military, emoji, nonLatin, script, maxLength.
addressRules.rules[].valuestring
addressRules.rules[].maxnumber
addressRules.rules[].action*stringOne of: flag, block, replace, skip.
addressRules.rules[].replacementstring
addressRules.rules[].countries*string[]
contact*object
contact.email*object
contact.email.provider*string
contact.email.fallbackstring
contact.phone*object
contact.phone.provider*string
contact.phone.fallbackstring
analytics*object
analytics.costPerFailedDeliveryMicros*integer
analytics.calculatorobject
analytics.calculator.ordersinteger
analytics.calculator.badRate*number
analytics.calculator.preventRate*number
analytics.calculator.mode*stringOne of: basic, advanced.
analytics.calculator.lines*object
analytics.calculator.lines.returns*object
analytics.calculator.lines.returns.value*number
analytics.calculator.lines.returns.share*number
analytics.calculator.lines.support*object
analytics.calculator.lines.support.value*number
analytics.calculator.lines.support.share*number
analytics.calculator.lines.reshipping*object
analytics.calculator.lines.reshipping.value*number
analytics.calculator.lines.reshipping.share*number
analytics.calculator.lines.restocking*object
analytics.calculator.lines.restocking.value*number
analytics.calculator.lines.restocking.share*number
analytics.version*string | null
storeobjectThe store's own settings in its platform's shape, for the platforms in x-avio-platforms: when the store checks and what it does with the answer. WooCommerce: checkout mode, order, billing, email and phone checks, holds, the My Account check. Shopware: the same checks plus order tags, flow events, the correction link and the sales channels.
holdsobjectShopify shops only: hold the fulfillment of an order whose address is invalid, released on correction or after releaseAfterHours (1 to 720). alertBeforeHours (0 to 719, absent = 12): email the shop that many hours before the release about held orders the customer hasn't fixed yet; 0 or at least releaseAfterHours = no email. alertIntervalHours (1 to 168, absent = 6): at most one such email per that many hours; an order may be listed up to that much earlier than alertBeforeHours. Needs the Fulfillment holds package; without it a save keeps the stored values.
holds.fulfillmentHold*object
holds.fulfillmentHold.enabled*boolean
holds.fulfillmentHold.releaseAfterHours*integer
holds.fulfillmentHold.alertBeforeHoursinteger
holds.fulfillmentHold.alertIntervalHoursinteger
emailsobjectShopify shops only: the correction request emails to the customer. reminderHours: at most 5 reminders, each 1 to 720 hours after the request. replyTo: where replies go; absent, the shop's email when the emails come from Address Validation iO's sender. merchantCopy: Bcc the shop's email on the request (not the reminders). linkTarget: where the email's link leads, order-status (the order status page, Address Validation iO's block) or correction-page (Address Validation iO's own page on the shop's app proxy); absent, by the shop's customer accounts: classic accounts get correction-page, anything else order-status. proxyPath: /<a|apps|community|tools>/<subpath>, only for a merchant who renamed Address Validation iO's app proxy in Shopify; absent, /a/address-validation.
emails.customerEmails*object
emails.customerEmails.enabled*boolean
emails.customerEmails.reminderHours*integer[]
emails.customerEmails.replyTostringPattern: ^(?:[A-Za-z0-9_'+\-]+\.)*[A-Za-z0-9_'+\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$.
emails.customerEmails.merchantCopy*boolean
emails.customerEmails.linkTargetstringOne of: order-status, correction-page.
emails.customerEmails.proxyPathstringMax 41 characters.
accountsobjectShopify shops only: the customer account extensions (the order list banner, the address check page, saved addresses).
accounts.customerAccount*object
accounts.customerAccount.enabled*boolean
choices*object
choices.zipCountries*string[]
choices.contactProviders*object
choices.contactProviders.email*object[]
choices.contactProviders.email[].id*string
choices.contactProviders.email[].priceMicros*number
choices.contactProviders.phone*object[]
choices.contactProviders.phone[].id*string
choices.contactProviders.phone[].priceMicros*number
cURL
curl -X GET 'https://api.address-validation.io/v1/settings' \
  -H "Authorization: Bearer $AVIO_API_KEY"
PUT/v1/settings/{area}Save one settings area (orders, delivery-points, checkout, contact, analytics; store for WooCommerce and Shopware shops, in the platform's shape; holds, emails, accounts for Shopify shops); answers the whole settings with the new versions

Auth: Authorization: Bearer avk_… (API key)

Parameters

FieldTypeDescription
area*string (path)x-avio-platforms names, per area, the platforms whose shops save it here. One of: orders, delivery-points, checkout, address-rules, contact, analytics, store, holds, emails, accounts.

Request body

FieldTypeDescription
version*string | null
values*object

Responses

  • 200PlatformSettingsOK
  • 400Errorinvalid_body (with fields) or invalid_area (an area the shop's platform doesn't save here: see x-avio-platforms)
  • 401Errormissing_api_key or invalid_api_key
  • 403Errortenant_suspended: the shop's API access is suspended; not_available: the shop's platform or the caller doesn't run this through the API
  • 409Errorsettings_conflict: version is stale (a save that changes nothing answers 200 instead)
  • 413Errorbody_too_large (over 16 KB)

Response 200

FieldTypeDescription
version*string | null
orders*object
orders.ignoreAddress2*boolean
orders.correctionLockobjectWhen customers can no longer change an order's address. stage: the fulfillment stage from which on (Shopify and Shopware only; absent on a save: the platform's default, which a read always shows); a shipped order always locks. afterHours: 1 to 1440 hours after the order was placed; absent: no time limit. A read always answers it.
orders.correctionLock.stagestringOne of: requested, in_progress, partially_fulfilled, fulfilled.
orders.correctionLock.afterHoursinteger
orders.validateBillingboolean
orders.channelsstring[]Sales channels whose orders Address Validation iO checks: a source name such as web, or an app's numeric id. A Shopify shop's read can still answer a value saved in the old app's form (gid://shopify/App/<id>), which a save refuses, until a save sends channels.
orders.orderTagsobject
orders.orderTags.enabled*boolean
orders.orderTags.prefix*string
orders.orderTags.format*stringMax 40 characters.
orders.orderTags.words*object
orders.orderTags.words.valid*stringMax 40 characters.
orders.orderTags.words.warn*stringMax 40 characters.
orders.orderTags.words.invalid*stringMax 40 characters.
orders.orderTags.words.unsupported*stringMax 40 characters.
orders.orderTags.words.skipped*stringMax 40 characters.
orders.orderTags.words.manual*stringMax 40 characters.
orders.orderTags.words.confirmed*stringMax 40 characters.
orders.orderTags.words.postBox*stringMax 40 characters.
orders.orderTags.words.emailValid*stringMax 40 characters.
orders.orderTags.words.emailInvalid*stringMax 40 characters.
orders.orderTags.words.emailUnknown*stringMax 40 characters.
orders.orderTags.words.phoneValid*stringMax 40 characters.
orders.orderTags.words.phoneInvalid*stringMax 40 characters.
orders.orderTags.words.phoneUnknown*stringMax 40 characters.
deliveryPoints*object
deliveryPoints.default*object
deliveryPoints.default.poBox*stringOne of: allow, block.
deliveryPoints.default.parcelLocker*stringOne of: allow, block.
deliveryPoints.countries*object
checkout*object
checkout.houseNumberCountries*string[]
checkout.zipCountries*string[]
checkout.maxAddressLength*number
checkout.blockInvalidEmail*boolean
checkout.blockDisposableEmail*boolean
checkout.verifyEnabledboolean
checkout.blockOnInvalidboolean
checkout.autocompleteEnabledbooleanAddress Validation iO's address suggestions in Shopify checkout (Plus only, also selected in the checkout editor). A read answers false until it is turned on.
addressRules*object
addressRules.rules*object[]
addressRules.rules[].id*string
addressRules.rules[].field*stringOne of: address, address1, address2, city, zip, province.
addressRules.rules[].match*stringOne of: contains, word, equals, military, emoji, nonLatin, script, maxLength.
addressRules.rules[].valuestring
addressRules.rules[].maxnumber
addressRules.rules[].action*stringOne of: flag, block, replace, skip.
addressRules.rules[].replacementstring
addressRules.rules[].countries*string[]
contact*object
contact.email*object
contact.email.provider*string
contact.email.fallbackstring
contact.phone*object
contact.phone.provider*string
contact.phone.fallbackstring
analytics*object
analytics.costPerFailedDeliveryMicros*integer
analytics.calculatorobject
analytics.calculator.ordersinteger
analytics.calculator.badRate*number
analytics.calculator.preventRate*number
analytics.calculator.mode*stringOne of: basic, advanced.
analytics.calculator.lines*object
analytics.calculator.lines.returns*object
analytics.calculator.lines.returns.value*number
analytics.calculator.lines.returns.share*number
analytics.calculator.lines.support*object
analytics.calculator.lines.support.value*number
analytics.calculator.lines.support.share*number
analytics.calculator.lines.reshipping*object
analytics.calculator.lines.reshipping.value*number
analytics.calculator.lines.reshipping.share*number
analytics.calculator.lines.restocking*object
analytics.calculator.lines.restocking.value*number
analytics.calculator.lines.restocking.share*number
analytics.version*string | null
storeobjectThe store's own settings in its platform's shape, for the platforms in x-avio-platforms: when the store checks and what it does with the answer. WooCommerce: checkout mode, order, billing, email and phone checks, holds, the My Account check. Shopware: the same checks plus order tags, flow events, the correction link and the sales channels.
holdsobjectShopify shops only: hold the fulfillment of an order whose address is invalid, released on correction or after releaseAfterHours (1 to 720). alertBeforeHours (0 to 719, absent = 12): email the shop that many hours before the release about held orders the customer hasn't fixed yet; 0 or at least releaseAfterHours = no email. alertIntervalHours (1 to 168, absent = 6): at most one such email per that many hours; an order may be listed up to that much earlier than alertBeforeHours. Needs the Fulfillment holds package; without it a save keeps the stored values.
holds.fulfillmentHold*object
holds.fulfillmentHold.enabled*boolean
holds.fulfillmentHold.releaseAfterHours*integer
holds.fulfillmentHold.alertBeforeHoursinteger
holds.fulfillmentHold.alertIntervalHoursinteger
emailsobjectShopify shops only: the correction request emails to the customer. reminderHours: at most 5 reminders, each 1 to 720 hours after the request. replyTo: where replies go; absent, the shop's email when the emails come from Address Validation iO's sender. merchantCopy: Bcc the shop's email on the request (not the reminders). linkTarget: where the email's link leads, order-status (the order status page, Address Validation iO's block) or correction-page (Address Validation iO's own page on the shop's app proxy); absent, by the shop's customer accounts: classic accounts get correction-page, anything else order-status. proxyPath: /<a|apps|community|tools>/<subpath>, only for a merchant who renamed Address Validation iO's app proxy in Shopify; absent, /a/address-validation.
emails.customerEmails*object
emails.customerEmails.enabled*boolean
emails.customerEmails.reminderHours*integer[]
emails.customerEmails.replyTostringPattern: ^(?:[A-Za-z0-9_'+\-]+\.)*[A-Za-z0-9_'+\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$.
emails.customerEmails.merchantCopy*boolean
emails.customerEmails.linkTargetstringOne of: order-status, correction-page.
emails.customerEmails.proxyPathstringMax 41 characters.
accountsobjectShopify shops only: the customer account extensions (the order list banner, the address check page, saved addresses).
accounts.customerAccount*object
accounts.customerAccount.enabled*boolean
choices*object
choices.zipCountries*string[]
choices.contactProviders*object
choices.contactProviders.email*object[]
choices.contactProviders.email[].id*string
choices.contactProviders.email[].priceMicros*number
choices.contactProviders.phone*object[]
choices.contactProviders.phone[].id*string
choices.contactProviders.phone[].priceMicros*number
cURL
curl -X PUT 'https://api.address-validation.io/v1/settings/{area}' \
  -H "Authorization: Bearer $AVIO_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"version":"string","values":{"ignoreAddress2":true}}'

routes

GET/v1/routesThe shop's effective routes (its own rows over Address Validation iO's recommended ones, each with its source), the recommended routes and the choices

Auth: Authorization: Bearer avk_… (API key)

Responses

  • 200PlatformRoutesOK
  • 401Errormissing_api_key or invalid_api_key
  • 403Errortenant_suspended: the shop's API access is suspended; not_available: the shop's platform or the caller doesn't run this through the API

Response 200

FieldTypeDescription
routes*object[]
routes[].provider*stringOne of: loqate, google, postcode-eu, smarty, sandbox.
routes[].fallbackstringOne of: loqate, google, postcode-eu, smarty, sandbox.
routes[].mode*stringOne of: strict, balanced, loose.
routes[].enabled*boolean
routes[].countryCode*string
routes[].source*stringOne of: recommended, custom.
stored*boolean
followsRecommended*boolean
recommended*object[]
recommended[].provider*stringOne of: loqate, google, postcode-eu, smarty, sandbox.
recommended[].fallbackstringOne of: loqate, google, postcode-eu, smarty, sandbox.
recommended[].mode*stringOne of: strict, balanced, loose.
recommended[].enabled*boolean
recommended[].countryCode*string
choices*object
choices.countries*string[]
choices.providers*object[]
choices.providers[].id*stringOne of: loqate, google, postcode-eu, smarty, sandbox.
choices.providers[].countries*string[] | "*"
choices.modes*string[]
cURL
curl -X GET 'https://api.address-validation.io/v1/routes' \
  -H "Authorization: Bearer $AVIO_API_KEY"
PUT/v1/routes/{country}Save a country's own route while the row shown is still expected (null: none); a recommended row becomes custom

Auth: Authorization: Bearer avk_… (API key)

Parameters

FieldTypeDescription
country*string (path)A country of choices.countries, or default for the * row.

Request body

FieldTypeDescription
provider*stringOne of: loqate, google, postcode-eu, smarty, sandbox.
fallbackstringOne of: loqate, google, postcode-eu, smarty, sandbox.
mode*stringOne of: strict, balanced, loose.
enabled*boolean
expected*object | null
expected.provider*string
expected.fallbackstring
expected.mode*string
expected.enabled*boolean

Responses

  • 200PlatformRoutesOK
  • 400Errorinvalid_body (with fields) or invalid_country
  • 401Errormissing_api_key or invalid_api_key
  • 403Errortenant_suspended: the shop's API access is suspended; not_available: the shop's platform or the caller doesn't run this through the API
  • 409Errorroute_conflict: the stored row is not expected (a row that already has the values answers 200)
  • 413Errorbody_too_large (over 16 KB)

Response 200

FieldTypeDescription
routes*object[]
routes[].provider*stringOne of: loqate, google, postcode-eu, smarty, sandbox.
routes[].fallbackstringOne of: loqate, google, postcode-eu, smarty, sandbox.
routes[].mode*stringOne of: strict, balanced, loose.
routes[].enabled*boolean
routes[].countryCode*string
routes[].source*stringOne of: recommended, custom.
stored*boolean
followsRecommended*boolean
recommended*object[]
recommended[].provider*stringOne of: loqate, google, postcode-eu, smarty, sandbox.
recommended[].fallbackstringOne of: loqate, google, postcode-eu, smarty, sandbox.
recommended[].mode*stringOne of: strict, balanced, loose.
recommended[].enabled*boolean
recommended[].countryCode*string
choices*object
choices.countries*string[]
choices.providers*object[]
choices.providers[].id*stringOne of: loqate, google, postcode-eu, smarty, sandbox.
choices.providers[].countries*string[] | "*"
choices.modes*string[]
cURL
curl -X PUT 'https://api.address-validation.io/v1/routes/{country}' \
  -H "Authorization: Bearer $AVIO_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"provider":"loqate","mode":"strict","enabled":true,"expected":{"provider":"string","mode":"string","enabled":true}}'
DELETE/v1/routes/{country}Delete a country's own route while it is still expected, so it follows the recommended route again (no own row answers 200)

Auth: Authorization: Bearer avk_… (API key)

Parameters

FieldTypeDescription
country*string (path)A country of choices.countries, or default for the * row.

Request body

FieldTypeDescription
expected*object
expected.provider*string
expected.fallbackstring
expected.mode*string
expected.enabled*boolean

Responses

  • 200PlatformRoutesOK
  • 400Errorinvalid_body or invalid_country
  • 401Errormissing_api_key or invalid_api_key
  • 403Errortenant_suspended: the shop's API access is suspended; not_available: the shop's platform or the caller doesn't run this through the API
  • 409Errorroute_conflict: the stored row is not expected (a row that already has the values answers 200)
  • 413Errorbody_too_large (over 16 KB)

Response 200

FieldTypeDescription
routes*object[]
routes[].provider*stringOne of: loqate, google, postcode-eu, smarty, sandbox.
routes[].fallbackstringOne of: loqate, google, postcode-eu, smarty, sandbox.
routes[].mode*stringOne of: strict, balanced, loose.
routes[].enabled*boolean
routes[].countryCode*string
routes[].source*stringOne of: recommended, custom.
stored*boolean
followsRecommended*boolean
recommended*object[]
recommended[].provider*stringOne of: loqate, google, postcode-eu, smarty, sandbox.
recommended[].fallbackstringOne of: loqate, google, postcode-eu, smarty, sandbox.
recommended[].mode*stringOne of: strict, balanced, loose.
recommended[].enabled*boolean
recommended[].countryCode*string
choices*object
choices.countries*string[]
choices.providers*object[]
choices.providers[].id*stringOne of: loqate, google, postcode-eu, smarty, sandbox.
choices.providers[].countries*string[] | "*"
choices.modes*string[]
cURL
curl -X DELETE 'https://api.address-validation.io/v1/routes/{country}' \
  -H "Authorization: Bearer $AVIO_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"expected":{"provider":"string","mode":"string","enabled":true}}'

logs

GET/v1/logsThe shop's app log, newest first (90 days, paged), with each provider call's response time; never provider cost

Auth: Authorization: Bearer avk_… (API key)

Parameters

FieldTypeDescription
fromstring (query)yyyy-mm-dd, inclusive, within the last 90 days. Default: 6 days before to. Pattern: ^\d{4}-\d{2}-\d{2}$.
tostring (query)yyyy-mm-dd, inclusive. Default: today in timeZone. Pattern: ^\d{4}-\d{2}-\d{2}$.
timeZonestring (query)The days' time zone: an IANA name or ±hh:mm. Default: UTC. Max 64 characters.
kindstring (query)One of: validation, address, correction, email, phone, hold, tag, flow, billing, settings, app, error.
resultstring (query)One of: valid, warn, invalid, skipped.
sourcestring (query)One of: checkout, order-created, order-updated, admin, bulk, flow, customer, widget-address, test, ab-test.
orderstring (query)An order number, with or without # (matched against orderName). Max 64 characters.
problems"1" (query)1: warnings and errors only.
pageSizeinteger (query)Default: 50.
cursorstring (query)The page.cursor of the page shown. Max 1024 characters.
directionstring (query)With cursor: next (older, the default) or previous (newer). One of: next, previous.

Responses

  • 200LogPageOK
  • 400Errorinvalid_query (with fields), invalid_range (a bad day, from after to, a day over 90 days ago or after tomorrow) or invalid_cursor
  • 401Errormissing_api_key or invalid_api_key
  • 403Errortenant_suspended: the shop's API access is suspended; not_available: the shop's platform or the caller doesn't run this through the API
  • 429Errorrate_limited (1000 log reads per hour and shop)

Response 200

FieldTypeDescription
items*LogRow[]
items[].id*string
items[].at*string
items[].kind*stringOne of: validation, address, correction, email, phone, hold, tag, flow, billing, settings, app, error.
items[].level*stringOne of: info, warning, error.
items[].code*string
items[].paramsobject
items[].orderIdstring
items[].orderNamestring
items[].sourcestringOne of: checkout, order-created, order-updated, admin, bulk, flow, customer, widget-address, test, ab-test.
items[].decisionstringOne of: valid, warn, invalid, skipped.
items[].previousDecisionstringOne of: valid, warn, invalid, skipped.
items[].countryCodestring
items[].providersobject[]
items[].providers[].provider*string
items[].providers[].status*string
items[].providers[].latencyMs*number
items[].cachedboolean
items[].actorobject
items[].actor.type*stringOne of: merchant, customer, avio, system, platform-api.
items[].changesobject[]
items[].changes[].field*string
items[].changes[].fromstring
items[].changes[].tostring
items[].recipientChangedboolean
items[].tagsobject
items[].tags.added*string[]
items[].tags.removed*string[]
page*object
page.cursor*string | null
page.hasNext*boolean
page.hasPrevious*boolean
cURL
curl -X GET 'https://api.address-validation.io/v1/logs' \
  -H "Authorization: Bearer $AVIO_API_KEY"

stats

GET/v1/statsThe Analytics numbers over 7, 30, 90 days or 12 months in UTC buckets; charged prices only, never provider cost

Auth: Authorization: Bearer avk_… (API key)

Parameters

FieldTypeDescription
daysstring (query)7, 30 or 90: that many UTC days ending today, in daily buckets. 365: this month and the 11 before, in monthly buckets. Default: 30. One of: 7, 30, 90, 365.
daily"1" (query)1: add daily, the checks and their sources per stored day.

Responses

  • 200PlatformStatsOK
  • 400Errorinvalid_query (with fields: days, daily)
  • 401Errormissing_api_key or invalid_api_key
  • 403Errortenant_suspended: the shop's API access is suspended; not_available: the shop's platform or the caller doesn't run this through the API
  • 429Errorrate_limited (shared with GET /v1/logs)

Response 200

FieldTypeDescription
days*7 | 30 | 90 | 365
range*object
range.from*string
range.to*string
range.bucket*stringOne of: day, month.
labels*string[]
series*object
series.checks*number[]
series.valid*number[]
series.warn*number[]
series.invalid*number[]
series.skipped*number[]
series.corrected*number[]
series.confirmed*number[]
series.emailsChecked*number[]
series.phonesChecked*number[]
series.savingsMicros*number[]
series.emailsSent*number[]
totals*object
totals.checks*number
totals.valid*number
totals.warn*number
totals.invalid*number
totals.skipped*number
totals.corrected*number
totals.confirmed*number
totals.ordersFlagged*number
totals.verifiedOrders*number
totals.emailsChecked*number
totals.emailsInvalid*number
totals.emailsBounced*number
totals.phonesChecked*number
totals.phonesInvalid*number
totals.accruedMicros*number
totals.failedDeliveryCostAvoidedMicros*number
totals.savingsMicros*number
totals.emailsSent*number
totals.ordersEmailed*number
totals.held*number
totals.released*number
totals.byCountry*objectAddress checks per country, every country (??: unknown).
totals.byProvider*objectProvider calls per provider, fallbacks and the admin's tests included. Counts only.
previous*object | null
previous.checks*number
previous.valid*number
previous.warn*number
previous.invalid*number
previous.skipped*number
previous.corrected*number
previous.confirmed*number
previous.ordersFlagged*number
previous.verifiedOrders*number
previous.emailsChecked*number
previous.emailsInvalid*number
previous.emailsBounced*number
previous.phonesChecked*number
previous.phonesInvalid*number
previous.accruedMicros*number
previous.failedDeliveryCostAvoidedMicros*number
previous.savingsMicros*number
previous.emailsSent*number
previous.ordersEmailed*number
previous.held*number
previous.released*number
previous.byCountry*objectAddress checks per country, every country (??: unknown).
previous.byProvider*objectProvider calls per provider, fallbacks and the admin's tests included. Counts only.
changes*object
changes.checks*number | null
changes.validRate*number | null
changes.corrected*number | null
changes.confirmed*number | null
changes.savings*number | null
changes.emailsSent*number | null
countries*object[]
countries[].countryCode*string
countries[].checks*number
costPerFailedDeliveryMicros*number
accruedSince*string | null
metering*stringaccrual: the charged prices accrue and are not invoiced yet. shopify-billing: Shopify usage records bill them. One of: accrual, shopify-billing.
countersSince*stringThe UTC day from which the shop's daily charges are counted: the stats' accruedMicros, and with it the savings, leave out the days before it.
dailyobject[]With daily=1: the days of range that have counters, oldest first. A day without any has no entry.
daily[].day*string
daily[].checks*number
daily[].bySource*objectThe day's checks per source: checkout, order, admin (bulk and Flow included), correction. Counted since 2026-10-06; a check from a test, the widget or an A/B arm has none.
cURL
curl -X GET 'https://api.address-validation.io/v1/stats' \
  -H "Authorization: Bearer $AVIO_API_KEY"
GET/v1/stats/sourcesAddress checks per source (checkout, admin, order, correction) per day, week or month over UTC days, as the Logs chart shows them

Auth: Authorization: Bearer avk_… (API key)

Parameters

FieldTypeDescription
fromstring (query)yyyy-mm-dd (UTC), inclusive. Default: 6 days before to. Pattern: ^\d{4}-\d{2}-\d{2}$.
tostring (query)yyyy-mm-dd (UTC), inclusive: at most tomorrow, and at most 366 days from from on. Default: today. Pattern: ^\d{4}-\d{2}-\d{2}$.
bucketstring (query)week buckets start on Monday. Default: day. One of: day, week, month.

Responses

  • 200StatsSourcesOK
  • 400Errorinvalid_query (with fields: from, to, bucket) or invalid_range (a day that doesn't exist, from after to, to after tomorrow or more than 366 days)
  • 401Errormissing_api_key or invalid_api_key
  • 403Errortenant_suspended: the shop's API access is suspended; not_available: the shop's platform or the caller doesn't run this through the API
  • 429Errorrate_limited (shared with GET /v1/logs)

Response 200

FieldTypeDescription
range*object
range.from*string
range.to*string
range.bucket*stringOne of: day, week, month.
labels*string[]
series*object
series.checkout*number[]
series.admin*number[]
series.order*number[]
series.correction*number[]
sourcesSince*string | nullSet when range.from is before this day: the sources are counted from then on, and earlier checks have none.
cURL
curl -X GET 'https://api.address-validation.io/v1/stats/sources' \
  -H "Authorization: Bearer $AVIO_API_KEY"

banners

GET/v1/bannersAddress Validation iO's banners for the shop's admin: live, meant for the shop and not dismissed, by priority, in the merchant's locale (English fallback), as blocks and as escaped HTML. Never metered

Auth: Authorization: Bearer avk_… (API key)

Parameters

FieldTypeDescription
localestring (query)The merchant's admin locale (de, de-DE); en, de, fr, es are translated, anything else is English. Default: the shop's locale Max 35 characters.

Responses

  • 200BannersOK
  • 400Errorinvalid_query (with fields: ["locale"])
  • 401Errormissing_api_key or invalid_api_key
  • 403Errortenant_suspended: the shop's API access is suspended; not_available: the shop's platform or the caller doesn't run this through the API

Response 200

FieldTypeDescription
banners*object[]
banners[].id*string
banners[].tone*stringOne of: info, success, warning, critical.
banners[].dismissible*boolean
banners[].endAtstringISO time the banner ends; absent: until unpublished
banners[].blocks*object[]
banners[].html*stringThe blocks as plain HTML, every value escaped (one h3 level, action rows as <p> of links, buttons with class button)
cURL
curl -X GET 'https://api.address-validation.io/v1/banners' \
  -H "Authorization: Bearer $AVIO_API_KEY"
POST/v1/banners/{id}/dismissHide a dismissible banner for the shop (a repeat answers 200 too). Never metered

Auth: Authorization: Bearer avk_… (API key)

Parameters

FieldTypeDescription
id*string (path)The banner's id from GET /v1/banners.

Responses

  • 200BannerDismissedOK
  • 401Errormissing_api_key or invalid_api_key
  • 403Errortenant_suspended: the shop's API access is suspended; not_available: the shop's platform or the caller doesn't run this through the API
  • 404Errorbanner_not_found: unknown, not live or not dismissible

Response 200

FieldTypeDescription
dismissed*true
cURL
curl -X POST 'https://api.address-validation.io/v1/banners/{id}/dismiss' \
  -H "Authorization: Bearer $AVIO_API_KEY"