Zum Inhalt springen
Address Validation iO

Diese Dokumentation gibt es nur auf Englisch.

API

API-Referenz

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"