Endpoints

Verify

Validate a structured or free-form address and get a verdict, corrections and confidence score.

POST/v1/addresses/verify

Parameters

Name	Type	Required	Description
`freeform`	string	no	A single free-form address string, e.g. "Str. Mihai Vitezu 12, cluj".
`street`	string	no	Street name (use instead of freeform).
`house_number`	string	no	House number. Accepts "nr.", "bl.", "sc." patterns.
`locality`	string	no	Locality (city, commune, village).
`county`	string	no	County. Accepts code (CJ) or name.

Example request

curl -X POST https://api.posty.ro/v1/addresses/verify \
  -H "Authorization: Bearer psk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{ "freeform": "Str. Mihai Vitezu 12, cluj" }'

Example response

{
  "verdict": "corrected",
  "confidence": 0.92,
  "address": {
    "street": "Strada Mihai Viteazu",
    "house_number": "12",
    "locality": "Cluj-Napoca",
    "county": "Cluj",
    "county_code": "CJ",
    "postal_code": "400151"
  },
  "corrections": [
    {
      "field": "street_name",
      "from": "Mihai Vitezu",
      "to": "Mihai Viteazu",
      "reason": "diacritic"
    }
  ],
  "request_id": "req_01J9Z8H..."
}