Questions · API

Is there an API for address verification and normalisation?

What the address verification API does

The address verification endpoint fixes the address in the postal form of its country and the name that goes with it. In the same operation it also checks the email, phone and website, if you send them. It reads street, house number, postcode and city together and declares every correction. The country goes in country_code (ISO 3166-1) or in country, written any way.

One contact at a time in the request body, or a list in the items field, up to five hundred per call. Every call needs a token, which you generate from your account area once registered, and pass in the Authorization: Bearer header. The token can be given an expiry date, or left valid until you revoke it.

The validation result, field by field

The response has two forms of the same address: a readable one with accents, and the postal one for printing labels, in capitals. You need both for different reasons: the first to show the address to an operator or in an interface, the second for the actual printing.

With them comes a keyword outcome — correct, modified with the detail of what changed field by field, or to be checked when the address cannot be rebuilt with certainty, with the reason in clear: street not found in the municipality, insufficient data, house number not found. Every correction is declared, and when the engine is not sure it says so just as clearly. Where the register is in service you also get the coordinates of the house number, the municipality code and, in cities that have them, the district.

Single address or batch jobs

Under five hundred requests you get the answer at once, in the same call: the typical case of a registration form or a checkout, where the address is to be verified the moment the user types it. For bigger lists, up to a hundred thousand addresses at a time, add "async": true: the request returns a job code immediately and the processing enters the queue, the same one that handles batch jobs uploaded from the site. You read the result back with a GET on the same endpoint passing the code, in JSON or, if you need a file to download, in CSV.

Address autocomplete for your forms

If you are building an address form, /api/v1/suggest gives you autocomplete while the user types: street, city and house number proposed as they go, with the field already verified at the moment of selection, without a separate call. It is to be used from a server of yours, acting as a proxy towards the endpoint: the token must never appear in the end user's browser.

When integrating the API pays off

It makes sense when the address enters your records continuously: a registration form, an e-commerce checkout, a CRM fed by several channels. Verifying it there, the moment it enters, avoids piling up wrong addresses that then have to be cleaned in bulk before every mailing. If instead you already have a list to fix once, it is simpler to upload it as an Excel or CSV file from the site: same engine, without writing a line of code.

Error codes, limits and API documentation

Every response has an HTTP code consistent with what happened: 401 if the token is missing or invalid, 413 if the batch exceeds the limit, 429 if you exceeded the allowed number of requests per minute, 402 if the credit is not enough to cover the call. Even when an address cannot be normalised, the response arrives, with the outcome explaining why.

On the API page you find all the endpoints — address, deduplication, email, phone, website, name enrichment — with parameters, curl examples and error codes in full. If you work with a tool that imports specifications, there is also openapi.json.

A minimal call

The full response also carries the postal form, the detail of every changed field, the coordinates of the house number and the data as you sent them, for comparison.