Zum Inhalt springen
Address Validation iO

Diese Dokumentation gibt es nur auf Englisch.

API

Authentication

Authenticate to the Address Validation iO platform API with a bearer API key, and check which shop a key belongs to.

The Address Validation iO platform API lets your own server validate addresses, emails and phone numbers and check orders. It is the same API the AVIO WooCommerce plugin uses. Every request goes to https://api.address-validation.io, and all endpoints live under /v1.

Get an API key

API keys are issued by the AVIO team. Request one through the API contact form. Each key belongs to one shop (your store), and everything the key does (checks, orders, usage) is counted for that shop.

The key is shown to you once. AVIO stores only a hash of it, so we can't show it again. If you lose it, ask for a new one. A shop can have two active keys at the same time, so you can switch to a new key before the old one is revoked.

A key looks like this:

text
avk_<shop>_<keyId>_<secret>

Treat the whole string as an opaque secret. Store it in an environment variable or your platform's secret store, never in source control. The examples in these docs read it from AVIO_API_KEY.

Send the key

Send the key as a bearer token in the Authorization header of every request:

text
Authorization: Bearer avk_…

Send request bodies as JSON with Content-Type: application/json. Responses are JSON as well.

Note: The API is server to server only. Never put a key in a browser, a mobile app or any code your customers can download. Anyone who has the key can run checks on your account. To validate addresses in the browser, use the headless widget with a short-lived token minted on your server.

Check a key

GET /v1/me returns the shop and the key the request was made with. It costs nothing, so it is a good first call when you set up an integration.

curl https://api.address-validation.io/v1/me \
  -H "Authorization: Bearer $AVIO_API_KEY"

A valid key returns your shop:

JSON
{
  "shopId": "tn_3f9a1c2b7d4e5f60",
  "tenantId": "tn_3f9a1c2b7d4e5f60",
  "name": "Example Store",
  "platform": "custom",
  "storeDomain": "shop.example.com",
  "sandbox": false,
  "keyId": "k7p2x9",
  "apiVersion": "1"
}
Field Meaning
shopId Your shop's id.
tenantId Deprecated. Always equal to shopId; use shopId.
name The shop's name.
platform woocommerce, shopware or custom.
storeDomain Your store's host. Absent until it is set for your shop.
sandbox true for a test shop.
keyId The id of the key you used (not the secret).
apiVersion Always "1".

Authentication errors

Status error What it means
401 missing_api_key No Authorization header was sent.
401 invalid_api_key The header is malformed, the key is unknown, or it was revoked.
403 tenant_suspended The key is valid, but API access for the shop is suspended. Contact us.

See Errors and rate limits for every other error.

What a key can call

This guide section covers the endpoints most integrations need:

The API also has endpoints for platform integrations that manage a shop's configuration from their own admin: capabilities, connection reports, uninstall, settings, routes, logs, stats and banners. They are listed in the reference.

Two endpoints need no key: GET /v1/health (returns { "ok": true, "version": "1" }) and GET /v1/openapi.json (the OpenAPI 3.1 document of the API).

Full reference

Every operation, with its request and response schema, is in the API reference.