API documentation

Adrescheck Internationaal v3

Summary

Use this API to validate international address data, including the Netherlands, that is entered in your webshop or CRM. This API supports autocomplete functionality. To use this functionality, simply add the field “Autocomplete” with value “true” to your request. This functionality is currently available for Belgium and Luxembourg only, and is turned off by default. This functionality will be added to more countries in the future.

Methods and endpoints

MethodEndpoint
POSThttps://api.postnl.nl/address/international/v3/validate

Required headers

Header keyHeader ValueMandatory / optional
apikeyyour apikey

Mandatory

content-typeapplication/jsonMandatory

Input parameters


Fieldname

Mandatory/optional

Format

Example

CountryIso

Mandatory

String [2] or [3], according to ISO 3166-1 ‘alpha-2’ and ‘alpha-3’, not ‘numeric-3’.

BE/BEL

City

Optional

String [0-50]

Antwerpen

PostalCode

Optional

String [0-16]

2000

Street

Optional

String [0-50]

Oude Koornmarkt

HouseNumber

Optional

String or Number [0-8]

39

HuseNumberAddition

Optional

String [0-50]

A

Building

Optional

String [0-50]

De molensteen

Autocomplete

Optional

Bool

true / false

Supported countries

This API supports over 250 countries, regions, island groups. You can download the list below or find a general list of county ISO codes

Download documentation

Input field ‘strength’ per country

Depending on the country, addresses are set up differently. Therefore, input data fields can be more (or less) indicative of an address. We use that varying field indication ‘strength’ in our queries as well. For the most requested countries, these are the indication strengths of input fields. This overview will be updated regularly.

CountryISOStreetHouseNumberHouseNumberAdditionPostalCodeCityBuilding
AustriaMandatoryStrongVery strongNormalVery strongStrongNormal
BelgiumMandatoryStrongVery strongNormalVery strongStrongNormal
FranceMandatoryStrongVery strongNormalVery strongStrongStrong
GermanyMandatoryStrongVery strongNormalVery strongStrongStrong
Great BritainMandatoryStrongVery strongNormalVery strongStrongStrong
NetherlandsMandatoryStrongVery strongNormalVery strongStrongStrong
SpainMandatoryStrongVery strongNormalVery strongStrongStrong

Autocomplete

This API supports autocomplete functionality. To use this functionality, simply add the field “Autocomplete” with value “true” to your request. This functionality is off by default, and is currently only available for the following countries: Belgium, Luxembourg. When using autocomplete, the fields “ResultNumber”, “MailabilityScore” and “ResultPercentage” will be given a null value. This is because we don't want to put a score on potentially incomplete input data.

Output parameters

Fieldname

Description of attribute

Format [length]

ResultNumber

The number of results (multiple addresses in the response is temporarily unavailable)

Number [0-5]

MailabilityScore

Indication of certainty that the address is mailable

Number [0-3]

ResultPercentage

Level of similarity between the input and output address data

Number [0-3]

FormattedAddress

The full address according to local/national formatting standards

String [0-95]

Street

Street name of the address

String [0-95]

HouseNumber

House number of the address

Number [0-35]

HouseNumberAddition

House number addidtion of the address

Number [0-35]

PostalCode

Postal code of the address

String [4-10]

City

City of the address

String [0-35]

Country

Country of the address

String [0-95]

CountryIso2

ISO 3166-1 alpha-2 code of the country of the address

String [2]

CountryIso3

ISO 3166-1 alpha-3 code of the country of the address

String [3]

CompanyName

Name of company, when located on the address

String [0-95]

Building

Name of the building

String [0-95]

Locality 

Locality of the address

String [0-95]

State 

State of the address

String [0-95]

Latitude 

Latitudinal coordinate of address

Number [0-15]

Longitude 

Longitudinal coordinate of address

Number [0-15]

MailabilityScore

ScoreDefintion
100Exact unique match
80Almost exact match. In most cases just 1 element missing, such as a postcode or streetname, but match is still unique.
60Lot of discrepancies, but unique match with our database.
40Housenumber missing and less than 20 possible results.
20Housenumber missing more than 20 possible results.
0No results.

Example request & response

Request

Response

{

"City": "Antwerpen",

"Country": "BEL",

"PostalCode": "2000",

"Street" : "Oude Koornmarkt",

"HouseNumber" : "39",

"Building" : "",

"SubBuilding" : ""

}

{

"ResultNumber": 1,

"MailabilityScore": 100,

"ResultPercentage": 100,

"Country": "Belgium",

"Street": "Oude Koornmarkt",

"HouseNumber": 39,

"PostalCode": "2000",

"City": "Antwerpen",

"Province": "Antwerpen",

"FormattedAddress": [

"Oude Koornmarkt 39",

"2000 Antwerpen",

"Belgium"

]

}

Possible error codes

Error code

Error message

200

JSON response with requested data.

4xx

Error on customer-side. Example:

{

"code": 400,

"message": "Invalid request",

"errors": {

"countryCode": "This value is not valid."

}

}

500

Error on PostNL side.