API
Riferimento 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.
health
GET/v1/healthNo keyLiveness check
Auth: none
Responses
- 200
HealthOK
Response 200
| Field | Type | Description |
|---|---|---|
| ok* | true | |
| version* | "1" |
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
| Field | Type | Description |
|---|---|---|
| tag* | string (query) | Where the questions show One of: shopify, shopware, woocommerce, website. |
| locale | string (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
- 200
FaqsOK - 400
Errorinvalid_query(withfields):tagmissing or unknown
Response 200
| Field | Type | Description |
|---|---|---|
| tag* | string | One of: shopify, shopware, woocommerce, website. |
| locale* | string | One of: en, de, fr, es. |
| topics* | object[] | |
| topics[].id* | string | Stable; usable as a page anchor |
| topics[].title* | string | |
| topics[].items* | object[] | |
| topics[].items[].id* | string | Stable within its topic |
| topics[].items[].question* | string | |
| topics[].items[].answer* | string | Plain text |
| topics[].items[].link | object | |
| topics[].items[].link.href* | string | An https:// URL |
| topics[].items[].link.label* | string |
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
| Field | Type | Description |
|---|---|---|
| limit | integer (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 |
| before | string (query) | The previous page's nextCursor; absent for the newest entries Max 200 characters. |
| platform | string (query) | Only lines for this platform (api = API shops) One of: shopify, woocommerce, shopware, api. |
Responses
- 200
ChangelogOK - 400
Errorinvalid_query(withfields):limit,beforeorplatforminvalid
Response 200
| Field | Type | Description |
|---|---|---|
| entries* | object[] | |
| entries[].id* | string | Opaque id of the entry |
| entries[].date* | string | ISO 8601 time the entry is dated |
| entries[].title | string | Plain text; absent when staff gave none |
| entries[].items* | object[] | |
| entries[].items[].kind* | string | One of: new, improved, fixed. |
| entries[].items[].text* | string | Plain text |
| entries[].items[].platforms* | string[] | |
| nextCursor | string | Pass as before for older entries; absent on the last page |
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
- 200
StatusOK
Response 200
| Field | Type | Description |
|---|---|---|
| updatedAt* | string | When 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* | string | Stable kebab-case: api, order-checks, customer-emails, bulk-checks, <group>-<provider> (e.g. address-loqate) |
| components[].group* | string | One of: service, address, email, phone. |
| components[].name* | string | |
| components[].status* | string | unknown: no recent data (no traffic) or the state could not be read; degraded: slow or partly failing One of: operational, degraded, outage, unknown. |
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
- 200
TenantInfoOK - 401
Errormissing_api_keyorinvalid_api_key - 403
Errortenant_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
| Field | Type | Description |
|---|---|---|
| shopId* | string | |
| tenantId* | string | Use shopId (same value). |
| name* | string | |
| platform* | string | One of: woocommerce, shopware, custom. |
| storeDomain | string | |
| sandbox* | boolean | |
| keyId* | string | |
| apiVersion* | "1" |
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
| Field | Type | Description |
|---|---|---|
| address* | object | |
| address.firstName | string | null | Max 255 characters. |
| address.lastName | string | null | Max 255 characters. |
| address.company | string | null | Max 255 characters. |
| address.address1 | string | null | Max 255 characters. |
| address.address2 | string | null | Max 255 characters. |
| address.city | string | null | Max 255 characters. |
| address.zip | string | null | Max 255 characters. |
| address.province | string | null | Max 255 characters. |
| address.provinceCode | string | null | Max 255 characters. |
| address.countryCode* | string | Pattern: ^[A-Za-z]{2}$. |
| address.phone | string | null | Max 255 characters. |
| context | string | One of: checkout, account, other, test. |
| string | Max 254 characters. | |
| provider | string | Only 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
- 200
AddressCheckOK - 400
Errorinvalid_body;provider_override_not_allowed:providersent, but the shop may not choose its provider - 401
Errormissing_api_keyorinvalid_api_key - 403
Errortenant_suspended: the shop's API access is suspended;not_available: the shop's platform or the caller doesn't run this through the API - 413
Errorbody_too_large(over 16 KB) - 429
Errorrate_limited: theapi-testquota ofcontext: testis spent; staff's hourly limit replaces its limit
Response 200
| Field | Type | Description |
|---|---|---|
| decision* | string | One of: valid, warn, invalid, skipped. |
| mode* | string | One of: strict, balanced, loose. |
| addressHash* | string | |
| verdict* | object | |
| verdict.status* | string | One of: deliverable, corrected, ambiguous, invalid, unsupported, error. |
| verdict.provider* | string | One of: loqate, google, postcode-eu, smarty, sandbox. |
| verdict.granularity* | string | One of: subpremise, premise, street, locality, none. |
| verdict.changes* | object[] | |
| verdict.changes[].field* | string | One of: address1, address2, city, zip, province, provinceCode, countryCode. |
| verdict.changes[].from* | string | |
| verdict.changes[].to* | string | |
| verdict.changes[].kind* | string | One of: alias, format, minor, major, inferred. |
| verdict.missing* | string[] | |
| verdict.unverified* | string[] | |
| verdict.suggestions* | Address[] | |
| verdict.suggestions[].firstName | string | |
| verdict.suggestions[].lastName | string | |
| verdict.suggestions[].company | string | |
| verdict.suggestions[].address1* | string | |
| verdict.suggestions[].address2 | string | |
| verdict.suggestions[].city* | string | |
| verdict.suggestions[].zip | string | |
| verdict.suggestions[].province | string | |
| verdict.suggestions[].provinceCode | string | |
| verdict.suggestions[].countryCode* | string | |
| verdict.suggestions[].phone | string | |
| verdict.suggestionsProvider | string | One of: loqate, google, postcode-eu, smarty, sandbox. |
| verdict.blocked | string | The 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[] | |
| rules | object[] | |
| rules[].code* | string | One of: house_number, zip_format, too_long, po_box, parcel_locker_blocked, parcel_locker, email_invalid, email_disposable, address_rule. |
| rules[].field* | string | One of: address1, address2, city, zip, province, email. |
| addressRules | object[] | Every merchant address rule that matched. Absent when none did. |
| addressRules[].id* | string | |
| addressRules[].action* | string | One of: flag, block, replace, skip. |
| addressRules[].field* | string | One of: address1, address2, city, zip, province. |
| rewrite | object | |
| rewrite.firstName | string | |
| rewrite.lastName | string | |
| rewrite.company | string | |
| rewrite.address1* | string | |
| rewrite.address2 | string | |
| rewrite.city* | string | |
| rewrite.zip | string | |
| rewrite.province | string | |
| rewrite.provinceCode | string | |
| rewrite.countryCode* | string | |
| rewrite.phone | string |
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
| Field | Type | Description |
|---|---|---|
| email* | string | Max 254 characters. |
| provider | string | Only 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
- 200
EmailCheckResultOK - 400
Errorinvalid_body;provider_override_not_allowed:providersent, but the shop may not choose its provider - 401
Errormissing_api_keyorinvalid_api_key - 403
Errortenant_suspended: the shop's API access is suspended;not_available: the shop's platform or the caller doesn't run this through the API - 413
Errorbody_too_large(over 16 KB)
Response 200
| Field | Type | Description |
|---|---|---|
| result* | string | One of: valid, invalid, unknown. |
| reason | "syntax" | |
| disposable | boolean | |
| catchAll | boolean | |
| risky | boolean | |
| role | boolean | |
| suggestion | string |
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
| Field | Type | Description |
|---|---|---|
| phone* | string | Max 64 characters. |
| countryCode | string | Pattern: ^[A-Za-z]{2}$. |
| provider | string | Only 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
- 200
PhoneCheckResultOK - 400
Errorinvalid_body;provider_override_not_allowed:providersent, but the shop may not choose its provider - 401
Errormissing_api_keyorinvalid_api_key - 403
Errortenant_suspended: the shop's API access is suspended;not_available: the shop's platform or the caller doesn't run this through the API - 413
Errorbody_too_large(over 16 KB)
Response 200
| Field | Type | Description |
|---|---|---|
| result* | string | One of: valid, invalid, unknown. |
| e164 | string | |
| lineType | string |
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
| Field | Type | Description |
|---|---|---|
| orderId* | string (path) | The platform's order id (URL-encoded). Pattern: ^[A-Za-z0-9._:-]{1,64}$. |
Responses
- 200
OrderResultOK - 400
Errorinvalid_order_id - 401
Errormissing_api_keyorinvalid_api_key - 403
Errortenant_suspended: the shop's API access is suspended;not_available: the shop's platform or the caller doesn't run this through the API - 404
Errororder_not_found
Response 200
| Field | Type | Description |
|---|---|---|
| orderId* | string | |
| orderNumber | string | |
| decision* | string | One of: valid, warn, invalid, skipped. |
| status* | string | One of: validated, fixed, confirmed. |
| address* | object | |
| address.firstName | string | |
| address.lastName | string | |
| address.company | string | |
| address.address1* | string | |
| address.address2 | string | |
| address.city* | string | |
| address.zip | string | |
| address.province | string | |
| address.provinceCode | string | |
| address.countryCode* | string | |
| address.phone | string | |
| addressHash* | string | |
| verdict* | object | |
| verdict.status* | string | One of: deliverable, corrected, ambiguous, invalid, unsupported, error. |
| verdict.provider* | string | One of: loqate, google, postcode-eu, smarty, sandbox. |
| verdict.granularity* | string | One of: subpremise, premise, street, locality, none. |
| verdict.changes* | object[] | |
| verdict.changes[].field* | string | One of: address1, address2, city, zip, province, provinceCode, countryCode. |
| verdict.changes[].from* | string | |
| verdict.changes[].to* | string | |
| verdict.changes[].kind* | string | One of: alias, format, minor, major, inferred. |
| verdict.missing* | string[] | |
| verdict.unverified* | string[] | |
| verdict.suggestions* | Address[] | |
| verdict.suggestions[].firstName | string | |
| verdict.suggestions[].lastName | string | |
| verdict.suggestions[].company | string | |
| verdict.suggestions[].address1* | string | |
| verdict.suggestions[].address2 | string | |
| verdict.suggestions[].city* | string | |
| verdict.suggestions[].zip | string | |
| verdict.suggestions[].province | string | |
| verdict.suggestions[].provinceCode | string | |
| verdict.suggestions[].countryCode* | string | |
| verdict.suggestions[].phone | string | |
| verdict.suggestionsProvider | string | One of: loqate, google, postcode-eu, smarty, sandbox. |
| issues* | string[] | |
| billing | object | |
| billing.decision* | string | One of: valid, warn, invalid, skipped. |
| billing.verdict* | object | |
| billing.verdict.status* | string | One of: deliverable, corrected, ambiguous, invalid, unsupported, error. |
| billing.verdict.provider* | string | One of: loqate, google, postcode-eu, smarty, sandbox. |
| billing.verdict.granularity* | string | One of: subpremise, premise, street, locality, none. |
| billing.verdict.changes* | object[] | |
| billing.verdict.changes[].field* | string | One of: address1, address2, city, zip, province, provinceCode, countryCode. |
| billing.verdict.changes[].from* | string | |
| billing.verdict.changes[].to* | string | |
| billing.verdict.changes[].kind* | string | One of: alias, format, minor, major, inferred. |
| billing.verdict.missing* | string[] | |
| billing.verdict.unverified* | string[] | |
| billing.verdict.suggestions* | Address[] | |
| billing.verdict.suggestions[].firstName | string | |
| billing.verdict.suggestions[].lastName | string | |
| billing.verdict.suggestions[].company | string | |
| billing.verdict.suggestions[].address1* | string | |
| billing.verdict.suggestions[].address2 | string | |
| billing.verdict.suggestions[].city* | string | |
| billing.verdict.suggestions[].zip | string | |
| billing.verdict.suggestions[].province | string | |
| billing.verdict.suggestions[].provinceCode | string | |
| billing.verdict.suggestions[].countryCode* | string | |
| billing.verdict.suggestions[].phone | string | |
| billing.verdict.suggestionsProvider | string | One of: loqate, google, postcode-eu, smarty, sandbox. |
| object | ||
| email.result* | string | One of: valid, invalid, unknown. |
| email.reason | "syntax" | |
| email.disposable | boolean | |
| email.catchAll | boolean | |
| email.risky | boolean | |
| email.role | boolean | |
| email.suggestion | string | |
| phone | object | |
| phone.result* | string | One of: valid, invalid, unknown. |
| phone.e164 | string | |
| phone.lineType | string | |
| validatedAt* | string | |
| correctedAt | string | |
| correctableUntil | string | |
| metered* | boolean | |
| addressRules | object[] | Every merchant address rule that matched. Absent when none did. |
| addressRules[].id* | string | |
| addressRules[].action* | string | One of: flag, block, replace, skip. |
| addressRules[].field* | string | One of: address1, address2, city, zip, province. |
| rewrite | object | |
| rewrite.firstName | string | |
| rewrite.lastName | string | |
| rewrite.company | string | |
| rewrite.address1* | string | |
| rewrite.address2 | string | |
| rewrite.city* | string | |
| rewrite.zip | string | |
| rewrite.province | string | |
| rewrite.provinceCode | string | |
| rewrite.countryCode* | string | |
| rewrite.phone | string |
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
| Field | Type | Description |
|---|---|---|
| orderId* | string (path) | The platform's order id (URL-encoded). Pattern: ^[A-Za-z0-9._:-]{1,64}$. |
Request body
| Field | Type | Description |
|---|---|---|
| orderNumber | string | Max 64 characters. |
| shippingAddress* | object | |
| shippingAddress.firstName | string | null | Max 255 characters. |
| shippingAddress.lastName | string | null | Max 255 characters. |
| shippingAddress.company | string | null | Max 255 characters. |
| shippingAddress.address1 | string | null | Max 255 characters. |
| shippingAddress.address2 | string | null | Max 255 characters. |
| shippingAddress.city | string | null | Max 255 characters. |
| shippingAddress.zip | string | null | Max 255 characters. |
| shippingAddress.province | string | null | Max 255 characters. |
| shippingAddress.provinceCode | string | null | Max 255 characters. |
| shippingAddress.countryCode* | string | Pattern: ^[A-Za-z]{2}$. |
| shippingAddress.phone | string | null | Max 255 characters. |
| billingAddress | object | |
| billingAddress.firstName | string | null | Max 255 characters. |
| billingAddress.lastName | string | null | Max 255 characters. |
| billingAddress.company | string | null | Max 255 characters. |
| billingAddress.address1 | string | null | Max 255 characters. |
| billingAddress.address2 | string | null | Max 255 characters. |
| billingAddress.city | string | null | Max 255 characters. |
| billingAddress.zip | string | null | Max 255 characters. |
| billingAddress.province | string | null | Max 255 characters. |
| billingAddress.provinceCode | string | null | Max 255 characters. |
| billingAddress.countryCode* | string | Pattern: ^[A-Za-z]{2}$. |
| billingAddress.phone | string | null | Max 255 characters. |
| string | Max 254 characters. | |
| checkEmail | boolean | |
| phone | string | Max 64 characters. |
| checkPhone | boolean | |
| force | boolean |
Responses
- 200
OrderResultOK - 400
Errorinvalid_bodyorinvalid_order_id - 401
Errormissing_api_keyorinvalid_api_key - 403
Errortenant_suspended: the shop's API access is suspended;not_available: the shop's platform or the caller doesn't run this through the API - 409
Errororder_conflict: another address was saved during the request, or the order erased; send the order as it is now - 413
Errorbody_too_large(over 16 KB)
Response 200
| Field | Type | Description |
|---|---|---|
| orderId* | string | |
| orderNumber | string | |
| decision* | string | One of: valid, warn, invalid, skipped. |
| status* | string | One of: validated, fixed, confirmed. |
| address* | object | |
| address.firstName | string | |
| address.lastName | string | |
| address.company | string | |
| address.address1* | string | |
| address.address2 | string | |
| address.city* | string | |
| address.zip | string | |
| address.province | string | |
| address.provinceCode | string | |
| address.countryCode* | string | |
| address.phone | string | |
| addressHash* | string | |
| verdict* | object | |
| verdict.status* | string | One of: deliverable, corrected, ambiguous, invalid, unsupported, error. |
| verdict.provider* | string | One of: loqate, google, postcode-eu, smarty, sandbox. |
| verdict.granularity* | string | One of: subpremise, premise, street, locality, none. |
| verdict.changes* | object[] | |
| verdict.changes[].field* | string | One of: address1, address2, city, zip, province, provinceCode, countryCode. |
| verdict.changes[].from* | string | |
| verdict.changes[].to* | string | |
| verdict.changes[].kind* | string | One of: alias, format, minor, major, inferred. |
| verdict.missing* | string[] | |
| verdict.unverified* | string[] | |
| verdict.suggestions* | Address[] | |
| verdict.suggestions[].firstName | string | |
| verdict.suggestions[].lastName | string | |
| verdict.suggestions[].company | string | |
| verdict.suggestions[].address1* | string | |
| verdict.suggestions[].address2 | string | |
| verdict.suggestions[].city* | string | |
| verdict.suggestions[].zip | string | |
| verdict.suggestions[].province | string | |
| verdict.suggestions[].provinceCode | string | |
| verdict.suggestions[].countryCode* | string | |
| verdict.suggestions[].phone | string | |
| verdict.suggestionsProvider | string | One of: loqate, google, postcode-eu, smarty, sandbox. |
| issues* | string[] | |
| billing | object | |
| billing.decision* | string | One of: valid, warn, invalid, skipped. |
| billing.verdict* | object | |
| billing.verdict.status* | string | One of: deliverable, corrected, ambiguous, invalid, unsupported, error. |
| billing.verdict.provider* | string | One of: loqate, google, postcode-eu, smarty, sandbox. |
| billing.verdict.granularity* | string | One of: subpremise, premise, street, locality, none. |
| billing.verdict.changes* | object[] | |
| billing.verdict.changes[].field* | string | One of: address1, address2, city, zip, province, provinceCode, countryCode. |
| billing.verdict.changes[].from* | string | |
| billing.verdict.changes[].to* | string | |
| billing.verdict.changes[].kind* | string | One of: alias, format, minor, major, inferred. |
| billing.verdict.missing* | string[] | |
| billing.verdict.unverified* | string[] | |
| billing.verdict.suggestions* | Address[] | |
| billing.verdict.suggestions[].firstName | string | |
| billing.verdict.suggestions[].lastName | string | |
| billing.verdict.suggestions[].company | string | |
| billing.verdict.suggestions[].address1* | string | |
| billing.verdict.suggestions[].address2 | string | |
| billing.verdict.suggestions[].city* | string | |
| billing.verdict.suggestions[].zip | string | |
| billing.verdict.suggestions[].province | string | |
| billing.verdict.suggestions[].provinceCode | string | |
| billing.verdict.suggestions[].countryCode* | string | |
| billing.verdict.suggestions[].phone | string | |
| billing.verdict.suggestionsProvider | string | One of: loqate, google, postcode-eu, smarty, sandbox. |
| object | ||
| email.result* | string | One of: valid, invalid, unknown. |
| email.reason | "syntax" | |
| email.disposable | boolean | |
| email.catchAll | boolean | |
| email.risky | boolean | |
| email.role | boolean | |
| email.suggestion | string | |
| phone | object | |
| phone.result* | string | One of: valid, invalid, unknown. |
| phone.e164 | string | |
| phone.lineType | string | |
| validatedAt* | string | |
| correctedAt | string | |
| correctableUntil | string | |
| metered* | boolean | |
| addressRules | object[] | Every merchant address rule that matched. Absent when none did. |
| addressRules[].id* | string | |
| addressRules[].action* | string | One of: flag, block, replace, skip. |
| addressRules[].field* | string | One of: address1, address2, city, zip, province. |
| rewrite | object | |
| rewrite.firstName | string | |
| rewrite.lastName | string | |
| rewrite.company | string | |
| rewrite.address1* | string | |
| rewrite.address2 | string | |
| rewrite.city* | string | |
| rewrite.zip | string | |
| rewrite.province | string | |
| rewrite.provinceCode | string | |
| rewrite.countryCode* | string | |
| rewrite.phone | string |
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
| Field | Type | Description |
|---|---|---|
| orderId* | string (path) | The platform's order id (URL-encoded). Pattern: ^[A-Za-z0-9._:-]{1,64}$. |
Responses
- 200
DeletedOK - 400
Errorinvalid_order_id - 401
Errormissing_api_keyorinvalid_api_key - 403
Errortenant_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
| Field | Type | Description |
|---|---|---|
| deleted* | true |
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
| Field | Type | Description |
|---|---|---|
| orderId* | string (path) | The platform's order id (URL-encoded). Pattern: ^[A-Za-z0-9._:-]{1,64}$. |
Request body
| Field | Type | Description |
|---|---|---|
| address* | object | |
| address.firstName | string | null | Max 255 characters. |
| address.lastName | string | null | Max 255 characters. |
| address.company | string | null | Max 255 characters. |
| address.address1 | string | null | Max 255 characters. |
| address.address2 | string | null | Max 255 characters. |
| address.city | string | null | Max 255 characters. |
| address.zip | string | null | Max 255 characters. |
| address.province | string | null | Max 255 characters. |
| address.provinceCode | string | null | Max 255 characters. |
| address.countryCode* | string | Pattern: ^[A-Za-z]{2}$. |
| address.phone | string | null | Max 255 characters. |
| by | string | One of: customer, admin. |
Responses
- 200
OrderResultOK - 400
Errorinvalid_bodyorinvalid_order_id - 401
Errormissing_api_keyorinvalid_api_key - 403
Errortenant_suspended: the shop's API access is suspended;not_available: the shop's platform or the caller doesn't run this through the API - 404
Errororder_not_found - 409
Errororder_conflict: another save won (not this correction's double submit); send it again as the order is now - 413
Errorbody_too_large(over 16 KB) - 429
Errorrate_limited
Response 200
| Field | Type | Description |
|---|---|---|
| orderId* | string | |
| orderNumber | string | |
| decision* | string | One of: valid, warn, invalid, skipped. |
| status* | string | One of: validated, fixed, confirmed. |
| address* | object | |
| address.firstName | string | |
| address.lastName | string | |
| address.company | string | |
| address.address1* | string | |
| address.address2 | string | |
| address.city* | string | |
| address.zip | string | |
| address.province | string | |
| address.provinceCode | string | |
| address.countryCode* | string | |
| address.phone | string | |
| addressHash* | string | |
| verdict* | object | |
| verdict.status* | string | One of: deliverable, corrected, ambiguous, invalid, unsupported, error. |
| verdict.provider* | string | One of: loqate, google, postcode-eu, smarty, sandbox. |
| verdict.granularity* | string | One of: subpremise, premise, street, locality, none. |
| verdict.changes* | object[] | |
| verdict.changes[].field* | string | One of: address1, address2, city, zip, province, provinceCode, countryCode. |
| verdict.changes[].from* | string | |
| verdict.changes[].to* | string | |
| verdict.changes[].kind* | string | One of: alias, format, minor, major, inferred. |
| verdict.missing* | string[] | |
| verdict.unverified* | string[] | |
| verdict.suggestions* | Address[] | |
| verdict.suggestions[].firstName | string | |
| verdict.suggestions[].lastName | string | |
| verdict.suggestions[].company | string | |
| verdict.suggestions[].address1* | string | |
| verdict.suggestions[].address2 | string | |
| verdict.suggestions[].city* | string | |
| verdict.suggestions[].zip | string | |
| verdict.suggestions[].province | string | |
| verdict.suggestions[].provinceCode | string | |
| verdict.suggestions[].countryCode* | string | |
| verdict.suggestions[].phone | string | |
| verdict.suggestionsProvider | string | One of: loqate, google, postcode-eu, smarty, sandbox. |
| issues* | string[] | |
| billing | object | |
| billing.decision* | string | One of: valid, warn, invalid, skipped. |
| billing.verdict* | object | |
| billing.verdict.status* | string | One of: deliverable, corrected, ambiguous, invalid, unsupported, error. |
| billing.verdict.provider* | string | One of: loqate, google, postcode-eu, smarty, sandbox. |
| billing.verdict.granularity* | string | One of: subpremise, premise, street, locality, none. |
| billing.verdict.changes* | object[] | |
| billing.verdict.changes[].field* | string | One of: address1, address2, city, zip, province, provinceCode, countryCode. |
| billing.verdict.changes[].from* | string | |
| billing.verdict.changes[].to* | string | |
| billing.verdict.changes[].kind* | string | One of: alias, format, minor, major, inferred. |
| billing.verdict.missing* | string[] | |
| billing.verdict.unverified* | string[] | |
| billing.verdict.suggestions* | Address[] | |
| billing.verdict.suggestions[].firstName | string | |
| billing.verdict.suggestions[].lastName | string | |
| billing.verdict.suggestions[].company | string | |
| billing.verdict.suggestions[].address1* | string | |
| billing.verdict.suggestions[].address2 | string | |
| billing.verdict.suggestions[].city* | string | |
| billing.verdict.suggestions[].zip | string | |
| billing.verdict.suggestions[].province | string | |
| billing.verdict.suggestions[].provinceCode | string | |
| billing.verdict.suggestions[].countryCode* | string | |
| billing.verdict.suggestions[].phone | string | |
| billing.verdict.suggestionsProvider | string | One of: loqate, google, postcode-eu, smarty, sandbox. |
| object | ||
| email.result* | string | One of: valid, invalid, unknown. |
| email.reason | "syntax" | |
| email.disposable | boolean | |
| email.catchAll | boolean | |
| email.risky | boolean | |
| email.role | boolean | |
| email.suggestion | string | |
| phone | object | |
| phone.result* | string | One of: valid, invalid, unknown. |
| phone.e164 | string | |
| phone.lineType | string | |
| validatedAt* | string | |
| correctedAt | string | |
| correctableUntil | string | |
| metered* | boolean | |
| addressRules | object[] | Every merchant address rule that matched. Absent when none did. |
| addressRules[].id* | string | |
| addressRules[].action* | string | One of: flag, block, replace, skip. |
| addressRules[].field* | string | One of: address1, address2, city, zip, province. |
| rewrite | object | |
| rewrite.firstName | string | |
| rewrite.lastName | string | |
| rewrite.company | string | |
| rewrite.address1* | string | |
| rewrite.address2 | string | |
| rewrite.city* | string | |
| rewrite.zip | string | |
| rewrite.province | string | |
| rewrite.provinceCode | string | |
| rewrite.countryCode* | string | |
| rewrite.phone | string |
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
| Field | Type | Description |
|---|---|---|
| orderId* | string (path) | The platform's order id (URL-encoded). Pattern: ^[A-Za-z0-9._:-]{1,64}$. |
Responses
- 200
OrderLogsOK - 400
Errorinvalid_order_id - 401
Errormissing_api_keyorinvalid_api_key - 403
Errortenant_suspended: the shop's API access is suspended;not_available: the shop's platform or the caller doesn't run this through the API - 429
Errorrate_limited(shared withGET /v1/logs)
Response 200
| Field | Type | Description |
|---|---|---|
| items* | LogRow[] | |
| items[].id* | string | |
| items[].at* | string | |
| items[].kind* | string | One of: validation, address, correction, email, phone, hold, tag, flow, billing, settings, app, error. |
| items[].level* | string | One of: info, warning, error. |
| items[].code* | string | |
| items[].params | object | |
| items[].orderId | string | |
| items[].orderName | string | |
| items[].source | string | One of: checkout, order-created, order-updated, admin, bulk, flow, customer, widget-address, test, ab-test. |
| items[].decision | string | One of: valid, warn, invalid, skipped. |
| items[].previousDecision | string | One of: valid, warn, invalid, skipped. |
| items[].countryCode | string | |
| items[].providers | object[] | |
| items[].providers[].provider* | string | |
| items[].providers[].status* | string | |
| items[].providers[].latencyMs* | number | |
| items[].cached | boolean | |
| items[].actor | object | |
| items[].actor.type* | string | One of: merchant, customer, avio, system, platform-api. |
| items[].changes | object[] | |
| items[].changes[].field* | string | |
| items[].changes[].from | string | |
| items[].changes[].to | string | |
| items[].recipientChanged | boolean | |
| items[].tags | object | |
| items[].tags.added* | string[] | |
| items[].tags.removed* | string[] |
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
| Field | Type | Description |
|---|---|---|
| period | string (query) | yyyy-mm, default: the current month Pattern: ^\d{4}-(0[1-9]|1[0-2])$. |
Responses
- 200
UsageWithPricesOK - 400
Errorinvalid_period - 401
Errormissing_api_keyorinvalid_api_key - 403
Errortenant_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
| Field | Type | Description |
|---|---|---|
| period* | string | |
| currency* | "USD" | |
| addressChecks* | number | |
| providerChecks* | number | |
| orders* | number | |
| freeOrders* | number | The 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* | boolean | false 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* | object | addressChecks per provider that answered. Counts only. |
| emailByProvider* | object | Email checks of every source per provider that answered (unknown: no definite answer, test: the admin's comparison), counted since 2026-10-11. |
| phoneByProvider* | object | Phone 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* | string | accrual: the charged prices accrue and are not invoiced yet. shopify-billing: Shopify usage records bill them. One of: accrual, shopify-billing. |
| countersSince* | string | The 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 -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
| Field | Type | Description |
|---|---|---|
| count | integer (query) | How many months, starting with the current one. Default: 12. |
Responses
- 200
UsageMonthsOK - 400
Errorinvalid_query(withfields: ["count"]) - 401
Errormissing_api_keyorinvalid_api_key - 403
Errortenant_suspended: the shop's API access is suspended;not_available: the shop's platform or the caller doesn't run this through the API - 429
Errorrate_limited(shared withGET /v1/logs)
Response 200
| Field | Type | Description |
|---|---|---|
| months* | Usage[] | |
| months[].period* | string | |
| months[].currency* | "USD" | |
| months[].addressChecks* | number | |
| months[].providerChecks* | number | |
| months[].orders* | number | |
| months[].freeOrders* | number | The 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* | boolean | false 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* | object | addressChecks per provider that answered. Counts only. |
| months[].emailByProvider* | object | Email checks of every source per provider that answered (unknown: no definite answer, test: the admin's comparison), counted since 2026-10-11. |
| months[].phoneByProvider* | object | Phone checks as emailByProvider. |
| months[].meteredEmailChecks* | number | |
| months[].meteredPhoneChecks* | number | |
| months[].emailAccruedMicros* | number | |
| months[].phoneAccruedMicros* | number | |
| metering* | string | accrual: the charged prices accrue and are not invoiced yet. shopify-billing: Shopify usage records bill them. One of: accrual, shopify-billing. |
| countersSince* | string | The 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 -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
- 200
CapabilitiesOK - 401
Errormissing_api_keyorinvalid_api_key - 403
Errortenant_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
| Field | Type | Description |
|---|---|---|
| apiVersion* | "1" | |
| shop* | object | |
| shop.shopId* | string | |
| shop.platform* | string | One of: shopify, woocommerce, shopware, custom. |
| shop.sandbox* | boolean | |
| shop.validating* | boolean | |
| shop.installation* | object | |
| shop.installation.state* | string | One of: pending, connected, uninstalled, suspended. |
| shop.installation.proof* | string | One of: shopify-oauth, shopware-app, api-key. |
| shop.installation.connectedAt | string | |
| shop.installation.lastSeenDay | string | |
| shop.installation.client | object | |
| shop.installation.client.name* | string | |
| shop.installation.client.version* | string | |
| shop.installation.platformVersion | string | |
| plan | object | |
| plan.id* | string | One of: payg, starter, business, pro, enterprise. |
| plan.packages* | object[] | |
| plan.packages[].id* | string | One 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* | string | One 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* | string | One 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.storeFields | string[] | |
| features* | object[] | |
| features[].id* | string | One 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* | string | One of: avio, client, native, unsupported. |
| features[].available* | boolean | |
| features[].gate | object | |
| features[].gate.package | string | One of: fulfillmentHolds, flow, insights, headlessWidget. |
| features[].gate.addon | string | One of: email, phone. |
| features[].reason | string | One of: platform, planned, needs_invoicing. |
| features[].config | object[] | |
| features[].config[].area* | string | One of: orders, delivery-points, checkout, address-rules, contact, analytics, store, holds, emails, accounts, general, widget, default-mode. |
| features[].config[].fields* | string[] |
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
| Field | Type | Description |
|---|---|---|
| client* | string | Max 100 characters. |
| clientVersion* | string | Max 100 characters. |
| platformVersion | string | Max 100 characters. |
| storeUrl | string | Max 100 characters. |
Responses
- 200
CapabilitiesOK - 400
Errorinvalid_body(withfields) - 401
Errormissing_api_keyorinvalid_api_key - 403
Errortenant_suspended: the shop's API access is suspended;not_available: the shop's platform or the caller doesn't run this through the API - 413
Errorbody_too_large(over 16 KB)
Response 200
| Field | Type | Description |
|---|---|---|
| apiVersion* | "1" | |
| shop* | object | |
| shop.shopId* | string | |
| shop.platform* | string | One of: shopify, woocommerce, shopware, custom. |
| shop.sandbox* | boolean | |
| shop.validating* | boolean | |
| shop.installation* | object | |
| shop.installation.state* | string | One of: pending, connected, uninstalled, suspended. |
| shop.installation.proof* | string | One of: shopify-oauth, shopware-app, api-key. |
| shop.installation.connectedAt | string | |
| shop.installation.lastSeenDay | string | |
| shop.installation.client | object | |
| shop.installation.client.name* | string | |
| shop.installation.client.version* | string | |
| shop.installation.platformVersion | string | |
| plan | object | |
| plan.id* | string | One of: payg, starter, business, pro, enterprise. |
| plan.packages* | object[] | |
| plan.packages[].id* | string | One 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* | string | One 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* | string | One 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.storeFields | string[] | |
| features* | object[] | |
| features[].id* | string | One 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* | string | One of: avio, client, native, unsupported. |
| features[].available* | boolean | |
| features[].gate | object | |
| features[].gate.package | string | One of: fulfillmentHolds, flow, insights, headlessWidget. |
| features[].gate.addon | string | One of: email, phone. |
| features[].reason | string | One of: platform, planned, needs_invoicing. |
| features[].config | object[] | |
| features[].config[].area* | string | One of: orders, delivery-points, checkout, address-rules, contact, analytics, store, holds, emails, accounts, general, widget, default-mode. |
| features[].config[].fields* | string[] |
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
| Field | Type | Description |
|---|---|---|
| keepData | boolean |
Responses
- 200
UninstallResultOK - 400
Errorinvalid_body(withfields) - 401
Errormissing_api_keyorinvalid_api_key - 403
Errortenant_suspended: the shop's API access is suspended;not_available: the shop's platform or the caller doesn't run this through the API - 413
Errorbody_too_large(over 16 KB)
Response 200
| Field | Type | Description |
|---|---|---|
| state* | "uninstalled" | |
| keepData* | boolean |
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
- 200
PlatformSettingsOK - 401
Errormissing_api_keyorinvalid_api_key - 403
Errortenant_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
| Field | Type | Description |
|---|---|---|
| version* | string | null | |
| orders* | object | |
| orders.ignoreAddress2* | boolean | |
| orders.correctionLock | object | When 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.stage | string | One of: requested, in_progress, partially_fulfilled, fulfilled. |
| orders.correctionLock.afterHours | integer | |
| orders.validateBilling | boolean | |
| orders.channels | string[] | 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.orderTags | object | |
| orders.orderTags.enabled* | boolean | |
| orders.orderTags.prefix* | string | |
| orders.orderTags.format* | string | Max 40 characters. |
| orders.orderTags.words* | object | |
| orders.orderTags.words.valid* | string | Max 40 characters. |
| orders.orderTags.words.warn* | string | Max 40 characters. |
| orders.orderTags.words.invalid* | string | Max 40 characters. |
| orders.orderTags.words.unsupported* | string | Max 40 characters. |
| orders.orderTags.words.skipped* | string | Max 40 characters. |
| orders.orderTags.words.manual* | string | Max 40 characters. |
| orders.orderTags.words.confirmed* | string | Max 40 characters. |
| orders.orderTags.words.postBox* | string | Max 40 characters. |
| orders.orderTags.words.emailValid* | string | Max 40 characters. |
| orders.orderTags.words.emailInvalid* | string | Max 40 characters. |
| orders.orderTags.words.emailUnknown* | string | Max 40 characters. |
| orders.orderTags.words.phoneValid* | string | Max 40 characters. |
| orders.orderTags.words.phoneInvalid* | string | Max 40 characters. |
| orders.orderTags.words.phoneUnknown* | string | Max 40 characters. |
| deliveryPoints* | object | |
| deliveryPoints.default* | object | |
| deliveryPoints.default.poBox* | string | One of: allow, block. |
| deliveryPoints.default.parcelLocker* | string | One of: allow, block. |
| deliveryPoints.countries* | object | |
| checkout* | object | |
| checkout.houseNumberCountries* | string[] | |
| checkout.zipCountries* | string[] | |
| checkout.maxAddressLength* | number | |
| checkout.blockInvalidEmail* | boolean | |
| checkout.blockDisposableEmail* | boolean | |
| checkout.verifyEnabled | boolean | |
| checkout.blockOnInvalid | boolean | |
| checkout.autocompleteEnabled | boolean | Address 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* | string | One of: address, address1, address2, city, zip, province. |
| addressRules.rules[].match* | string | One of: contains, word, equals, military, emoji, nonLatin, script, maxLength. |
| addressRules.rules[].value | string | |
| addressRules.rules[].max | number | |
| addressRules.rules[].action* | string | One of: flag, block, replace, skip. |
| addressRules.rules[].replacement | string | |
| addressRules.rules[].countries* | string[] | |
| contact* | object | |
| contact.email* | object | |
| contact.email.provider* | string | |
| contact.email.fallback | string | |
| contact.phone* | object | |
| contact.phone.provider* | string | |
| contact.phone.fallback | string | |
| analytics* | object | |
| analytics.costPerFailedDeliveryMicros* | integer | |
| analytics.calculator | object | |
| analytics.calculator.orders | integer | |
| analytics.calculator.badRate* | number | |
| analytics.calculator.preventRate* | number | |
| analytics.calculator.mode* | string | One 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 | |
| store | object | The 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. |
| holds | object | Shopify 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.alertBeforeHours | integer | |
| holds.fulfillmentHold.alertIntervalHours | integer | |
| emails | object | Shopify 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.replyTo | string | Pattern: ^(?:[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.linkTarget | string | One of: order-status, correction-page. |
| emails.customerEmails.proxyPath | string | Max 41 characters. |
| accounts | object | Shopify 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 -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
| Field | Type | Description |
|---|---|---|
| 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
| Field | Type | Description |
|---|---|---|
| version* | string | null | |
| values* | object |
Responses
- 200
PlatformSettingsOK - 400
Errorinvalid_body(withfields) orinvalid_area(an area the shop's platform doesn't save here: seex-avio-platforms) - 401
Errormissing_api_keyorinvalid_api_key - 403
Errortenant_suspended: the shop's API access is suspended;not_available: the shop's platform or the caller doesn't run this through the API - 409
Errorsettings_conflict:versionis stale (a save that changes nothing answers 200 instead) - 413
Errorbody_too_large(over 16 KB)
Response 200
| Field | Type | Description |
|---|---|---|
| version* | string | null | |
| orders* | object | |
| orders.ignoreAddress2* | boolean | |
| orders.correctionLock | object | When 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.stage | string | One of: requested, in_progress, partially_fulfilled, fulfilled. |
| orders.correctionLock.afterHours | integer | |
| orders.validateBilling | boolean | |
| orders.channels | string[] | 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.orderTags | object | |
| orders.orderTags.enabled* | boolean | |
| orders.orderTags.prefix* | string | |
| orders.orderTags.format* | string | Max 40 characters. |
| orders.orderTags.words* | object | |
| orders.orderTags.words.valid* | string | Max 40 characters. |
| orders.orderTags.words.warn* | string | Max 40 characters. |
| orders.orderTags.words.invalid* | string | Max 40 characters. |
| orders.orderTags.words.unsupported* | string | Max 40 characters. |
| orders.orderTags.words.skipped* | string | Max 40 characters. |
| orders.orderTags.words.manual* | string | Max 40 characters. |
| orders.orderTags.words.confirmed* | string | Max 40 characters. |
| orders.orderTags.words.postBox* | string | Max 40 characters. |
| orders.orderTags.words.emailValid* | string | Max 40 characters. |
| orders.orderTags.words.emailInvalid* | string | Max 40 characters. |
| orders.orderTags.words.emailUnknown* | string | Max 40 characters. |
| orders.orderTags.words.phoneValid* | string | Max 40 characters. |
| orders.orderTags.words.phoneInvalid* | string | Max 40 characters. |
| orders.orderTags.words.phoneUnknown* | string | Max 40 characters. |
| deliveryPoints* | object | |
| deliveryPoints.default* | object | |
| deliveryPoints.default.poBox* | string | One of: allow, block. |
| deliveryPoints.default.parcelLocker* | string | One of: allow, block. |
| deliveryPoints.countries* | object | |
| checkout* | object | |
| checkout.houseNumberCountries* | string[] | |
| checkout.zipCountries* | string[] | |
| checkout.maxAddressLength* | number | |
| checkout.blockInvalidEmail* | boolean | |
| checkout.blockDisposableEmail* | boolean | |
| checkout.verifyEnabled | boolean | |
| checkout.blockOnInvalid | boolean | |
| checkout.autocompleteEnabled | boolean | Address 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* | string | One of: address, address1, address2, city, zip, province. |
| addressRules.rules[].match* | string | One of: contains, word, equals, military, emoji, nonLatin, script, maxLength. |
| addressRules.rules[].value | string | |
| addressRules.rules[].max | number | |
| addressRules.rules[].action* | string | One of: flag, block, replace, skip. |
| addressRules.rules[].replacement | string | |
| addressRules.rules[].countries* | string[] | |
| contact* | object | |
| contact.email* | object | |
| contact.email.provider* | string | |
| contact.email.fallback | string | |
| contact.phone* | object | |
| contact.phone.provider* | string | |
| contact.phone.fallback | string | |
| analytics* | object | |
| analytics.costPerFailedDeliveryMicros* | integer | |
| analytics.calculator | object | |
| analytics.calculator.orders | integer | |
| analytics.calculator.badRate* | number | |
| analytics.calculator.preventRate* | number | |
| analytics.calculator.mode* | string | One 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 | |
| store | object | The 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. |
| holds | object | Shopify 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.alertBeforeHours | integer | |
| holds.fulfillmentHold.alertIntervalHours | integer | |
| emails | object | Shopify 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.replyTo | string | Pattern: ^(?:[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.linkTarget | string | One of: order-status, correction-page. |
| emails.customerEmails.proxyPath | string | Max 41 characters. |
| accounts | object | Shopify 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 -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
- 200
PlatformRoutesOK - 401
Errormissing_api_keyorinvalid_api_key - 403
Errortenant_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
| Field | Type | Description |
|---|---|---|
| routes* | object[] | |
| routes[].provider* | string | One of: loqate, google, postcode-eu, smarty, sandbox. |
| routes[].fallback | string | One of: loqate, google, postcode-eu, smarty, sandbox. |
| routes[].mode* | string | One of: strict, balanced, loose. |
| routes[].enabled* | boolean | |
| routes[].countryCode* | string | |
| routes[].source* | string | One of: recommended, custom. |
| stored* | boolean | |
| followsRecommended* | boolean | |
| recommended* | object[] | |
| recommended[].provider* | string | One of: loqate, google, postcode-eu, smarty, sandbox. |
| recommended[].fallback | string | One of: loqate, google, postcode-eu, smarty, sandbox. |
| recommended[].mode* | string | One of: strict, balanced, loose. |
| recommended[].enabled* | boolean | |
| recommended[].countryCode* | string | |
| choices* | object | |
| choices.countries* | string[] | |
| choices.providers* | object[] | |
| choices.providers[].id* | string | One of: loqate, google, postcode-eu, smarty, sandbox. |
| choices.providers[].countries* | string[] | "*" | |
| choices.modes* | string[] |
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
| Field | Type | Description |
|---|---|---|
| country* | string (path) | A country of choices.countries, or default for the * row. |
Request body
| Field | Type | Description |
|---|---|---|
| provider* | string | One of: loqate, google, postcode-eu, smarty, sandbox. |
| fallback | string | One of: loqate, google, postcode-eu, smarty, sandbox. |
| mode* | string | One of: strict, balanced, loose. |
| enabled* | boolean | |
| expected* | object | null | |
| expected.provider* | string | |
| expected.fallback | string | |
| expected.mode* | string | |
| expected.enabled* | boolean |
Responses
- 200
PlatformRoutesOK - 400
Errorinvalid_body(withfields) orinvalid_country - 401
Errormissing_api_keyorinvalid_api_key - 403
Errortenant_suspended: the shop's API access is suspended;not_available: the shop's platform or the caller doesn't run this through the API - 409
Errorroute_conflict: the stored row is notexpected(a row that already has the values answers 200) - 413
Errorbody_too_large(over 16 KB)
Response 200
| Field | Type | Description |
|---|---|---|
| routes* | object[] | |
| routes[].provider* | string | One of: loqate, google, postcode-eu, smarty, sandbox. |
| routes[].fallback | string | One of: loqate, google, postcode-eu, smarty, sandbox. |
| routes[].mode* | string | One of: strict, balanced, loose. |
| routes[].enabled* | boolean | |
| routes[].countryCode* | string | |
| routes[].source* | string | One of: recommended, custom. |
| stored* | boolean | |
| followsRecommended* | boolean | |
| recommended* | object[] | |
| recommended[].provider* | string | One of: loqate, google, postcode-eu, smarty, sandbox. |
| recommended[].fallback | string | One of: loqate, google, postcode-eu, smarty, sandbox. |
| recommended[].mode* | string | One of: strict, balanced, loose. |
| recommended[].enabled* | boolean | |
| recommended[].countryCode* | string | |
| choices* | object | |
| choices.countries* | string[] | |
| choices.providers* | object[] | |
| choices.providers[].id* | string | One of: loqate, google, postcode-eu, smarty, sandbox. |
| choices.providers[].countries* | string[] | "*" | |
| choices.modes* | string[] |
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
| Field | Type | Description |
|---|---|---|
| country* | string (path) | A country of choices.countries, or default for the * row. |
Request body
| Field | Type | Description |
|---|---|---|
| expected* | object | |
| expected.provider* | string | |
| expected.fallback | string | |
| expected.mode* | string | |
| expected.enabled* | boolean |
Responses
- 200
PlatformRoutesOK - 400
Errorinvalid_bodyorinvalid_country - 401
Errormissing_api_keyorinvalid_api_key - 403
Errortenant_suspended: the shop's API access is suspended;not_available: the shop's platform or the caller doesn't run this through the API - 409
Errorroute_conflict: the stored row is notexpected(a row that already has the values answers 200) - 413
Errorbody_too_large(over 16 KB)
Response 200
| Field | Type | Description |
|---|---|---|
| routes* | object[] | |
| routes[].provider* | string | One of: loqate, google, postcode-eu, smarty, sandbox. |
| routes[].fallback | string | One of: loqate, google, postcode-eu, smarty, sandbox. |
| routes[].mode* | string | One of: strict, balanced, loose. |
| routes[].enabled* | boolean | |
| routes[].countryCode* | string | |
| routes[].source* | string | One of: recommended, custom. |
| stored* | boolean | |
| followsRecommended* | boolean | |
| recommended* | object[] | |
| recommended[].provider* | string | One of: loqate, google, postcode-eu, smarty, sandbox. |
| recommended[].fallback | string | One of: loqate, google, postcode-eu, smarty, sandbox. |
| recommended[].mode* | string | One of: strict, balanced, loose. |
| recommended[].enabled* | boolean | |
| recommended[].countryCode* | string | |
| choices* | object | |
| choices.countries* | string[] | |
| choices.providers* | object[] | |
| choices.providers[].id* | string | One of: loqate, google, postcode-eu, smarty, sandbox. |
| choices.providers[].countries* | string[] | "*" | |
| choices.modes* | string[] |
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
| Field | Type | Description |
|---|---|---|
| from | string (query) | yyyy-mm-dd, inclusive, within the last 90 days. Default: 6 days before to. Pattern: ^\d{4}-\d{2}-\d{2}$. |
| to | string (query) | yyyy-mm-dd, inclusive. Default: today in timeZone. Pattern: ^\d{4}-\d{2}-\d{2}$. |
| timeZone | string (query) | The days' time zone: an IANA name or ±hh:mm. Default: UTC. Max 64 characters. |
| kind | string (query) | One of: validation, address, correction, email, phone, hold, tag, flow, billing, settings, app, error. |
| result | string (query) | One of: valid, warn, invalid, skipped. |
| source | string (query) | One of: checkout, order-created, order-updated, admin, bulk, flow, customer, widget-address, test, ab-test. |
| order | string (query) | An order number, with or without # (matched against orderName). Max 64 characters. |
| problems | "1" (query) | 1: warnings and errors only. |
| pageSize | integer (query) | Default: 50. |
| cursor | string (query) | The page.cursor of the page shown. Max 1024 characters. |
| direction | string (query) | With cursor: next (older, the default) or previous (newer). One of: next, previous. |
Responses
- 200
LogPageOK - 400
Errorinvalid_query(withfields),invalid_range(a bad day,fromafterto, a day over 90 days ago or after tomorrow) orinvalid_cursor - 401
Errormissing_api_keyorinvalid_api_key - 403
Errortenant_suspended: the shop's API access is suspended;not_available: the shop's platform or the caller doesn't run this through the API - 429
Errorrate_limited(1000 log reads per hour and shop)
Response 200
| Field | Type | Description |
|---|---|---|
| items* | LogRow[] | |
| items[].id* | string | |
| items[].at* | string | |
| items[].kind* | string | One of: validation, address, correction, email, phone, hold, tag, flow, billing, settings, app, error. |
| items[].level* | string | One of: info, warning, error. |
| items[].code* | string | |
| items[].params | object | |
| items[].orderId | string | |
| items[].orderName | string | |
| items[].source | string | One of: checkout, order-created, order-updated, admin, bulk, flow, customer, widget-address, test, ab-test. |
| items[].decision | string | One of: valid, warn, invalid, skipped. |
| items[].previousDecision | string | One of: valid, warn, invalid, skipped. |
| items[].countryCode | string | |
| items[].providers | object[] | |
| items[].providers[].provider* | string | |
| items[].providers[].status* | string | |
| items[].providers[].latencyMs* | number | |
| items[].cached | boolean | |
| items[].actor | object | |
| items[].actor.type* | string | One of: merchant, customer, avio, system, platform-api. |
| items[].changes | object[] | |
| items[].changes[].field* | string | |
| items[].changes[].from | string | |
| items[].changes[].to | string | |
| items[].recipientChanged | boolean | |
| items[].tags | object | |
| items[].tags.added* | string[] | |
| items[].tags.removed* | string[] | |
| page* | object | |
| page.cursor* | string | null | |
| page.hasNext* | boolean | |
| page.hasPrevious* | boolean |
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
| Field | Type | Description |
|---|---|---|
| days | string (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
- 200
PlatformStatsOK - 400
Errorinvalid_query(withfields:days,daily) - 401
Errormissing_api_keyorinvalid_api_key - 403
Errortenant_suspended: the shop's API access is suspended;not_available: the shop's platform or the caller doesn't run this through the API - 429
Errorrate_limited(shared withGET /v1/logs)
Response 200
| Field | Type | Description |
|---|---|---|
| days* | 7 | 30 | 90 | 365 | |
| range* | object | |
| range.from* | string | |
| range.to* | string | |
| range.bucket* | string | One 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* | object | Address checks per country, every country (??: unknown). |
| totals.byProvider* | object | Provider 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* | object | Address checks per country, every country (??: unknown). |
| previous.byProvider* | object | Provider 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* | string | accrual: the charged prices accrue and are not invoiced yet. shopify-billing: Shopify usage records bill them. One of: accrual, shopify-billing. |
| countersSince* | string | The 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. |
| daily | object[] | 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* | object | The 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 -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
| Field | Type | Description |
|---|---|---|
| from | string (query) | yyyy-mm-dd (UTC), inclusive. Default: 6 days before to. Pattern: ^\d{4}-\d{2}-\d{2}$. |
| to | string (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}$. |
| bucket | string (query) | week buckets start on Monday. Default: day. One of: day, week, month. |
Responses
- 200
StatsSourcesOK - 400
Errorinvalid_query(withfields:from,to,bucket) orinvalid_range(a day that doesn't exist,fromafterto,toafter tomorrow or more than 366 days) - 401
Errormissing_api_keyorinvalid_api_key - 403
Errortenant_suspended: the shop's API access is suspended;not_available: the shop's platform or the caller doesn't run this through the API - 429
Errorrate_limited(shared withGET /v1/logs)
Response 200
| Field | Type | Description |
|---|---|---|
| range* | object | |
| range.from* | string | |
| range.to* | string | |
| range.bucket* | string | One of: day, week, month. |
| labels* | string[] | |
| series* | object | |
| series.checkout* | number[] | |
| series.admin* | number[] | |
| series.order* | number[] | |
| series.correction* | number[] | |
| sourcesSince* | string | null | Set when range.from is before this day: the sources are counted from then on, and earlier checks have none. |
curl -X GET 'https://api.address-validation.io/v1/stats/sources' \
-H "Authorization: Bearer $AVIO_API_KEY"