SDK
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.
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
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):
$baseUrlis the API root; a trailing/or/v1is ignored.$timeoutis the timeout per attempt in seconds.$transportreplaces ext-curl, for example with WordPress's HTTP API. It is called asfn(string $method, string $url, array $headers, ?string $body, float $timeout)and returns['status' => int, 'body' => string, 'headers' => [...]].headersis 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 (status0).network_error: the request failed before a response arrived (status0).invalid_response: the response wasn't a JSON object.http_<status>: an error response without anerrorcode, such ashttp_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,PUTandDELETErequests are retried once after a network error, a timeout or a5xx.POSTrequests (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.