Docs

Getting started

Postio is the UK validation API for addresses, emails and phone numbers. Every endpoint is a single GET request that returns JSON over HTTPS — if you can speak HTTP and parse JSON, you can integrate in under five minutes.

What Postio does

Postio validates and enriches three kinds of UK contact data through one REST API: postal addresses (Royal Mail PAF lookup and autocomplete), email addresses (syntax, MX and SMTP checks) and phonenumbers (format and live carrier lookup). The API runs on Cloudflare’s edge, so requests are answered close to wherever your users are.

The base URL is https://api.postio.co.uk/v1. Every endpoint is a GET; there is nothing to install to start.

Get an API key

Sign up free — the first 100 lookups are on us, no card needed. Copy your key from the dashboard: it looks like pk_ followed by 32 hex characters. Keys are scoped per service (address / email / phone) and can be locked to specific origins or IP ranges.

Your first request

Send your key in the x-api-key header. This searches for a UK address and returns typeahead suggestions:

curl "https://api.postio.co.uk/v1/address/search?q=57+wimpole+street" \
  -H "x-api-key: pk_..."

The response is JSON. A successful search returns a list of suggestions, each with a udprn you can pass to the address endpoints to fetch the full, structured address.

The response shape

Every response — success or error — follows the same envelope, so you only write your parsing once:

{
  "success": true,
  "results": [ /* one or more result objects */ ],
  "meta": {
    "countResults": 1,
    "requestId": "dd273343-4597-4fa4-bcb6-c74a608c10dc",
    "performance": { "workerMs": 15, "lookupMs": 12 }
  }
}

On error, success is false, results is empty, and a top-level error field carries a stable machine-readable code (with details for humans). Log the requestId — it is how we trace any request you raise with us. See Errors & rate limits for the full list.

Free vs billable requests

/connect and /address/search are free (monitored for abuse). Everything else is billable on a hit with results only — a query that returns no match is a 200 with an empty results array and is not charged. See pricing for per-lookup rates.

Where to go next

Authentication — keys, origin locks, and keeping them secret.
Address, Email and Phone — each endpoint in detail.
SDKs & libraries — official clients for six languages plus the drop-in widget.
Integrations — the full directory of ways to install: SDKs, the browser widget, WordPress, MCP and more. Usually where you start.
Guides — UK address data, Royal Mail PAF and postcode lookup, explained.
OpenAPI spec — the full machine-readable contract, for codegen and API clients.