Questions · Addresses

Is there an API to normalise addresses?

What the call does

The contact verification endpoint fixes the address in the postal form of its country and the name that goes with it. It reads street, house number, postcode and city together, not one field at a time, 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.

How the result comes back

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. Nothing is ever corrected silently: if we change something we tell you, and if we are not sure we say that just as clearly instead of guessing. 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.

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 selection instead of having to check it later with 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 it makes sense to integrate it

It makes sense when the address enters your records again and again, not once: 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.

Errors, limits and full 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. An address that cannot be normalised is not an API error: the response comes anyway, 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.