Skip to content
Address Validation iO

SDKs

TypeScript and PHP clients

The official TypeScript and PHP clients for the Address Validation iO platform API, their methods, errors, timeouts and retries.

Address Validation iO has two official clients for the platform API: one for TypeScript and JavaScript, one for PHP. They wrap the same HTTP endpoints the API guides describe, add types (TypeScript), timeouts, safe retries and one error class. The AVIO WooCommerce plugin is built on the PHP client.

Note: Neither client is published to a package registry (npm or Packagist) yet. A registry release is planned. Until then, the clients are available on request: ask through the API contact form. You can also call the API directly over HTTP; every guide shows plain cURL, TypeScript, PHP and Python examples.

Both clients are server side only. Never ship your API key to a browser.

TypeScript client

An ESM package with type declarations and no runtime dependencies. It uses the global fetch, so it runs on Node.js 18 or later, Bun, Deno and edge runtimes.

TypeScript
import { AvioApiError, createAvioClient } from "@avio/platform-sdk";

const avio = createAvioClient({
  apiKey: process.env.AVIO_API_KEY!,
  baseUrl: "https://api.address-validation.io",
});

try {
  const check = await avio.validateAddress({
    address: { address1: "Unter den Linden 77", city: "Berlin", zip: "10117", countryCode: "DE" },
    context: "checkout",
  });
  if (check.decision === "invalid") {
    // ask the customer to fix the address, offering check.verdict.suggestions
  }
} catch (error) {
  if (error instanceof AvioApiError) {
    console.error(error.status, error.code, error.requestId);
  }
  // fail open: let the customer continue
}

Options of createAvioClient:

Option Description
apiKey Your API key.
baseUrl The API root, https://api.address-validation.io. A trailing / or /v1 is ignored.
timeoutMs Timeout per attempt in milliseconds. Default 5000.
fetch A custom fetch implementation, for example for tests or a proxy. Optional.

Responses are not validated at runtime; the types mirror the server's schemas.

PHP client

A single class, Avio\Sdk\AvioClient, for PHP 8.1 or later with no Composer dependencies. The default transport uses ext-curl. Results are associative arrays with the API's camelCase keys.

PHP
<?php
use Avio\Sdk\AvioClient;
use Avio\Sdk\AvioException;

$avio = new AvioClient(getenv('AVIO_API_KEY'), 'https://api.address-validation.io');

try {
    $check = $avio->validateAddress(
        ['address1' => 'Unter den Linden 77', 'city' => 'Berlin', 'zip' => '10117', 'countryCode' => 'DE'],
        'checkout',
    );
} catch (AvioException $e) {
    error_log("AVIO {$e->status} {$e->errorCode} {$e->requestId}");
    // fail open: let the customer continue
}

The constructor is new AvioClient(string $apiKey, string $baseUrl, ?callable $transport = null, float $timeout = 5.0):

  • $baseUrl is the API root; a trailing / or /v1 is ignored.
  • $timeout is the timeout per attempt in seconds.
  • $transport replaces ext-curl, for example with WordPress's HTTP API. It is called as fn(string $method, string $url, array $headers, ?string $body, float $timeout) and returns ['status' => int, 'body' => string, 'headers' => [...]]. headers is optional and only used to read the request id. Throw on a network failure.

PHP encodes an empty array as []. Where the API expects an empty JSON object, pass (object) [].

Methods

Both clients have the same methods. Where a call has several inputs, the TypeScript client takes an object and the PHP client positional arguments.

TypeScript PHP Calls
me() me() GET /v1/me
validateAddress({ address, context?, email? }) validateAddress($address, $context, $email) POST /v1/addresses/validate
validateEmail(email) validateEmail($email) POST /v1/emails/validate
validatePhone({ phone, countryCode? }) validatePhone($phone, $countryCode) POST /v1/phones/validate
submitOrder(orderId, input) submitOrder($orderId, $input) PUT /v1/orders/{orderId}
getOrder(orderId) getOrder($orderId) GET /v1/orders/{orderId}; undefined (PHP: null) when the order doesn't exist
correctOrder(orderId, address, by?) correctOrder($orderId, $address, $by) POST /v1/orders/{orderId}/correction
deleteOrder(orderId) deleteOrder($orderId) DELETE /v1/orders/{orderId}; returns nothing
usage(period?) usage($period) GET /v1/usage
usageMonths(count?) usageMonths($count) GET /v1/usage/months

Order ids are URL-encoded for you. See the guides for the request fields and results: Validate an address, Validate an email and a phone, Orders and Usage.

For platform integrations that manage a shop from their own admin, both clients also cover the configuration endpoints: capabilities(), connect(), uninstall(), settings(), saveSettings(), routes(), saveRoute(), deleteRoute(), logs(), orderLogs(), stats(), banners(), dismissBanner() and faqs(). The TypeScript client also has statsSources(). These endpoints are described in the API reference.

Errors

Every failure throws one error type: AvioApiError in TypeScript, AvioException in PHP.

TypeScript PHP Meaning
status status The HTTP status, or 0 when no response arrived.
code errorCode The API's error code (see Errors and rate limits), or one of the client's own codes below.
requestId requestId The x-avio-request-id header, when a response arrived. Quote it to support.
fields fields The invalid fields or parameters, when the error response lists them (for example with invalid_query).

The client's own codes:

  • timeout: no answer within the timeout (status 0).
  • network_error: the request failed before a response arrived (status 0).
  • invalid_response: the response wasn't a JSON object.
  • http_<status>: an error response without an error code, such as http_502.
  • invalid_request (PHP only): the request body couldn't be encoded as JSON, for example because of invalid UTF-8.

Timeouts and retries

  • The timeout applies to each attempt: 5 seconds by default.
  • GET, PUT and DELETE requests are retried once after a network error, a timeout or a 5xx.
  • POST requests (address, email and phone checks, corrections) are never retried, because a retry could run and charge a check again.

submitOrder is a PUT, so it is retried. That is safe: sending the same order with the same shipping address again returns the stored result without a new check (see Orders).

Full reference

Every operation the clients call is in the API reference.