POST /v1/address/restructure

Deterministic restructurer — split a freeform address line into the structured form required by the Nov 14 SWIFT mandate.

Takes a single freeform address_line (up to 280 chars) and emits a structured { street_name?, building_number?, post_code?, town_name?, country? } block plus a confidence label (high / medium / low) and a list of caveats.

The algorithm is deterministic token-mapping — no LLM. Same input always produces same output (which is what the audit trail and the idempotency contract need). See apps/api/src/lib/address-restructure.ts for the rules.

Limitations: poor on multi-line freeform addresses, poor on non-European postal formats, poor when the country is implicit. The Phase-2 roadmap adds a small-model rescue lane for low-confidence cases; today, low-confidence results should be routed to human review.

For pure-local lint (does the address have street_name + building_number + post_code + town_name + country?) use the free /address-lint page.

Request

Request body

{
  "address_line": "string (1..280)"
}

Response

Response body

{
  "structured": "{ street_name?, building_number?, post_code?, town_name?, country? }",
  "confidence": "\"high\" | \"medium\" | \"low\"",
  "caveats": "string[]",
  "metadata": "{ idempotency_key, algorithm: \"deterministic-token-map\" }"
}

Idempotency

Mandatory header `Idempotency-Key` (UUID or other opaque ≤64 char string). A second request with the same key and the same body returns the cached response and the header `X-Iso-Compliant-Idempotent-Replay: true`. A second request with the same key but a different body returns 409.

Rate limit

Sandbox: 60 requests / minute, 1000 / day. Production: 600 requests / minute soft cap, lifted per tenant on request.

← All docs