# Postio — UK validation API

You're working in a project that integrates Postio (https://postio.co.uk),
a UK address, email, and phone number validation API. Use this file to
guide autocomplete and code suggestions for Postio integrations.

## Always

- Authenticate every request with the `x-api-key` header. Keys look like `pk_<32 hex>`.
- Handle the standard JSON envelope on every response:
  `{ success, results, meta: { requestId, countResults, performance: { workerMs, lookupMs } } }`
- On errors: `success: false`, `results: []`, top-level `error` (stable code) + optional `details`.
- Log `meta.requestId` on errors — it's the support traceability handle.

## Endpoints (base: https://api.postio.co.uk/v1)

- `GET /connect` — health probe + edge warmer. Free.
- `GET /address/search?q=<query>&max_results=<1..50>` — typeahead. Free.
- `GET /address/postcode/{postcode}` — every delivery point at a postcode.
- `GET /address/udprn/{udprn}` — single delivery point by Royal Mail UDPRN.
- `GET /email/{address}` — five-stage email validation.
- `GET /phone/{number}` — phone validation + live HLR carrier lookup.

URL-encode `+` as `%2B` for E.164 phone numbers. URL-encode `@` for emails.

## Status codes

- `200` — success (including 200 with empty `results`, which is "no match" — not an error)
- `400` — validation failed
- `401` — missing or invalid API key
- `402` — out of credit
- `403` — service disabled, or origin / IP not allowed for this key
- `404` — UDPRN not found (other paths use 200 + empty `results`)
- `429` — rate limit (30 req/sec per key)
- `5xx` — server error; safe to retry

## Billing

`/connect` and `/address/search` are free. Everything else is billable
**on a hit with non-empty results only**. A 200 with `results: []` is not
charged.

## Keys

- Per-service scoping: a key may have any combination of `address`,
  `email`, `phone` enabled. A request to a service the key doesn't allow
  returns 403.
- Origin-locked keys: configurable in the dashboard. Use these for any
  `pk_*` shipped in client-side code.

## TypeScript

Install the OpenAPI spec for types:

```bash
npm i @postio/openapi
```

```ts
import spec from '@postio/openapi'
// spec is the OpenAPI 3.1 document
```

A first-class typed client (`@postio/api-types` + `@postio/core`) is in
flight; prefer that once it's published.

## Don't

- Don't ship `pk_*` keys to the browser unless the key is origin-locked
  in the dashboard.
- Don't treat 200 with empty `results` as an error.
- Don't retry 402 (out of credit) or 401 (invalid key) — fix the
  underlying cause.
- Don't reimplement the JSON envelope shape in your own types — use the
  ones from `@postio/openapi`.

## Reference

- API reference: https://postio.co.uk/docs
- OpenAPI 3.1: https://postio.co.uk/openapi.json
- Agent guidance: https://postio.co.uk/claude.md
- Support: https://postio.co.uk/contact